Standard tags ============= .. note:: This page describes "standard" tags. Python Liquid also has some extra tags and extended expression syntax that are disabled by default. See :doc:`extra_tags` and :doc:`expressions` for documentation on non-standard features. Comments -------- Comments can be used to add documentation to your templates or "comment out" chunks of Liquid markup and text so that it wont be rendered. Block comments ^^^^^^^^^^^^^^ .. code-block:: liquid2 {% comment %} ... {% endcomment %} Block comments start with the ``comment`` tag and end with the ``endcomment`` tag. It is OK for comment text to contain matching ``comment`` / ``endcomment`` or ``raw`` / ``endraw`` pairs, but it's a syntax error if ``comment`` or ``raw`` tags are unbalanced. .. code-block:: liquid2 {% comment %}This is a comment{% endcomment %} {% comment %} Comments can span multiple lines {% endcomment %} Inline comments ^^^^^^^^^^^^^^^ .. code-block:: liquid2 {% # ... %} An inline comment is a tag named ``#``. Everything after the hash up to the end tag delimiter (``%}``) is comment text. Text can span multiple lines, but each line must start with a ``#``. .. code-block:: liquid2 {% # This is a comment %} {%- # Comments can span multiple lines, # but every line must start with a hash. -%} Inside `liquid`_, any line starting with a hash will be considered a comment. .. code-block:: liquid2 {% liquid # This is a comment echo "Hello" %} Doc comments ------------ **New in version 2.0.0** .. code-block:: liquid2 {% doc %} ... {% enddoc %} Like `Block comments`_, doc comments are not rendered. Doc comments are designed to be read by tooling to improve Liquid template development. Output ------ .. code-block:: liquid2 {{ }} An expression surrounded by double curly braces (``{{`` and ``}}``) is an *output statement*. When rendered, the expression will be evaluated and the result inserted into the output text. In this example the expression is a variable, which will be resolved to a value and the value's string representation will output, but output statements can contain any expression. .. code-block:: liquid2 Hello, {{ you }}! Filters ^^^^^^^ .. code-block:: text {{ | [| ...] }} Values can be modified prior to output using filters. Filters are applied to an expression using the pipe operator (``|``), followed by the filter's name and, possibly, some filter arguments. Filter arguments appear after a colon (``:``) and are separated by commas (``,``). Multiple filters can be chained together, effectively piping the output of one filter into the input of another. See the :doc:`./filters` for details of all built-in filters. .. code-block:: liquid2 {{ user_name | upcase }} {{ 42 | plus: 7 | modulo: 3 }} assign ------ .. code-block:: text {% assign = %} The ``assign`` tag is used to define and initialize variables, or reassign existing variables. .. code-block:: liquid2 {% assign foo = "bar" %} foo is equal to {{ foo }}. {% assign foo = 42 %} foo is now equal to {{ foo }}. The expression on the right-hand side of the assignment operator (``=``) follows the syntax described in `Output`_ above, including `Filters`_. capture ------- .. code-block:: liquid2 {% capture %} {% endcapture %} The ``capture`` tag evaluates the contents of its block and saves the resulting string as a new variable, or reassigns an existing variable, without immediately rendering it. .. code-block:: liquid2 {% capture welcome_message %} Hello, {{ customer.name }}! Welcome to our store. {% endcapture %} {{ welcome_message }} case ---- .. code-block:: liquid2 {% case %} [ {% when %} ] ... [ {% else %} ] {% endcase %} The ``case`` tag evaluates an expression, matching the result against one or more ``when`` clauses. In the event of a match, the ``when`` block is rendered. The ``else`` clause is rendered if no ``when`` clauses match the ``case`` expression. .. code-block:: liquid2 {% assign day = "Monday" %} {% case day %} {% when "Monday" %} Start of the work week! {% when "Friday" %} It's almost the weekend! {% when "Saturday" or "Sunday" %} Enjoy your weekend! {% else %} Just another weekday. {% endcase %} cycle ----- .. code-block:: text {% cycle [ : ] [, ... ] %} Render the next item the argument list. When items are exhausted, the sequence starts again from the beginning. .. code-block:: liquid2 {% cycle 'odd', 'even' %} {% cycle 'odd', 'even' %} {% cycle 'odd', 'even' %} You can give ``cycle`` a name to further distinguish multiple iterators with the same items. .. code-block:: liquid2 {% cycle 'odd', 'even' %} {% cycle 'odd', 'even' %} {% cycle inner: 'odd', 'even' %} decrement --------- .. code-block:: liquid2 {% decrement %} The ``decrement`` tag renders the next value in a named counter, reducing the count by one each time. If a counter with the given name does not already exist, it is created automatically and initialized to zero, before subtracting 1 and outputting ``-1``. .. code-block:: liquid2 {% decrement some %} {% decrement thing %} {% decrement thing %} echo ---- .. code-block:: liquid2 {% echo %} ``echo`` is the tag form of an output statement (an expression surrounded by ``{{`` and ``}}``). It is mostly used inside ``{% liquid %}`` tags where output statements are not allowed. .. code-block:: liquid2 Hello, {% echo you %}! Hello, {{ you }}! {% liquid for product in collection.products echo product.title | capitalize endfor %} Just like output statements and the `assign`_ tag, the expression can include `filters`_. .. code-block:: liquid2 {% echo "bar" | upcase if x else "baz" | capitalize %} {% liquid for product in collection.products echo product.title | capitalize endfor %} for --- .. code-block:: text {% for in [ limit: ] [ offset: ] [ reversed ] %} [ {% else %} ] {% endfor %} The ``for`` tag is a for-each loop. It renders its block once for each item in an iterable. If the iterable is empty and an ``else`` block given, the ``else`` block will be rendered instead. .. code-block:: liquid2 {% for product in collection %} - {{ product.title }} {% else %} No products available {% endfor %} Range expression are often used with the ``for`` tag to loop over increasing integers. .. code-block:: liquid2 {% for i in (1..4) %} {{ i }} {% endfor %} limit ^^^^^ If a ``limit`` argument is given, the loop will stop after the specified number of iterations. .. code-block:: liquid2 {% for product in collection.products limit: 2 %} - {{ product.title }} {% endfor %} offset ^^^^^^ If an ``offset`` argument is given, it should be an integer specifying how many items to skip before starting the loop. .. code-block:: liquid2 {% for product in collection.products offset: 1 %} - {{ product.title }} {% endfor %} ``offset`` can also be given the special value ``"continue"``, in which case the loop will start from where a previous loop with the same iterable left off. .. code-block:: liquid2 {% for product in collection.products limit: 2 %} - {{ product.title }} {% endfor %} {% for product in collection.products offset: "continue" %} - {{ product.title }}! {% endfor %} reversed ^^^^^^^^ If the reversed flag is given, the target iterable will be iterated in reverse order. .. code-block:: liquid2 {% for product in collection.products reversed %} - {{ product.title }} {% endfor %} break ^^^^^ You can exit a loop early using the ``break`` tag. .. code-block:: liquid2 {% for product in collection.products %} {% if product.title == "Shirt" %} {% break %} {% endif %} - {{ product.title }} {% endfor %} continue ^^^^^^^^ You can skip all or part of a loop iteration with the ``continue`` tag. .. code-block:: liquid2 {% for product in collection.products %} {% if product.title == "Shirt" %} {% continue %} {% endif %} - {{ product.title }} {% endfor %} forloop ^^^^^^^ A ``forloop`` object is available inside every ``for`` tag block. +----------------+---------------------------------------------------------------------+---------+ | Property | Description | Type | +================+=====================================================================+=========+ | ``name`` | The loop variable name and target identifier, separated by a | string | | | hyphen. | | +----------------+---------------------------------------------------------------------+---------+ | ``length`` | The length of the sequence being iterated. | integer | +----------------+---------------------------------------------------------------------+---------+ | ``index`` | The 1-base index of the current iteration. | integer | +----------------+---------------------------------------------------------------------+---------+ | ``index0`` | The 0-base index of the current iteration. | integer | +----------------+---------------------------------------------------------------------+---------+ | ``rindex`` | The 1-base index of the current iteration counting from the end. | integer | +----------------+---------------------------------------------------------------------+---------+ | ``rindex0`` | The 0-base index of the current iteration counting from the end. | integer | +----------------+---------------------------------------------------------------------+---------+ | ``first`` | ``true`` if the current iteration is the first, ``false`` | bool | | | otherwise. | | +----------------+---------------------------------------------------------------------+---------+ | ``last`` | ``true`` is the current iteration is the last, ``false`` otherwise. | bool | +----------------+---------------------------------------------------------------------+---------+ | ``parentloop`` | the ``forloop`` object of an enclosing ``for`` loop. | forloop | +----------------+---------------------------------------------------------------------+---------+ .. code-block:: liquid2 {% for product in collection.products %} {% if forloop.first %} {{ product.title }} - {{ forloop.index0 }} {% else %} {{ product.title }} - {{ forloop.index0 }} {% endif %} {% endfor %} if -- .. code-block:: liquid2 {% if %} [ {% elsif %} [ {% elsif %} ... ]] [ {% else %} ... ] {% endif %} The ``if`` tag renders its block if its expression is truthy. Any number of ``elsif`` blocks can be given to add alternative branches, and an ``else`` block is used as a default if no preceding conditions were truthy. .. code-block:: liquid2 {% if product.title == "OK Hat" %} This hat is OK. {% elsif product.title == "Rubbish Tie" %} This tie is rubbish. {% else %} Not sure what this is. {% endif %} Conditional expressions ^^^^^^^^^^^^^^^^^^^^^^^ Any primitive expression can be tested for truthiness, like ``{% if some_variable %}``, or you can use a combination of the following operators. Only ``false``, ``nil``, ``null`` and the special *undefined* object are falsy in Liquid. ======== ======================== ===================================== Operator Description Example ======== ======================== ===================================== ``==`` Equals ``product.title == "Nice Shoes"`` ``!=`` Not equals ``user.name != "anonymous"`` ``>`` Greater than ``product.was_price > product.price`` ``<`` Less than ``collection.products.size < 10`` ``>=`` Greater than or equal to ``user.age >= 18`` ``<=`` Less than or equal to ``basket.size <= 0`` ``and`` Logical and ``x and y`` ``or`` Logical or ``x or y`` ======== ======================== ===================================== Operator precedence ^^^^^^^^^^^^^^^^^^^ In Liquid, ``and`` and ``or`` operators are right associative. Where ``true and false and false or true`` is equivalent to ``(true and (false and (false or true)))``, evaluating to ``false``. Python, on the other hand, would parse the same expression as ``(((true and false) and false) or true)``, evaluating to ``true``. include ------- .. code-block:: text {% include