Built-in template tags and filters
==================================
.. _built-in-tags:
Built-in Tags
-------------
``for``
~~~~~~~
A for loop allows you to iterate over an array found by variable lookup.
.. code-block:: html+django
{% for user in users %}
- {{ user }}
{% endfor %}
The ``for`` tag can iterate over dictionaries.
.. code-block:: html+django
{% for key, value in dict %}
- {{ key }}: {{ value }}
{% endfor %}
It can also iterate over ranges, tuple elements, structs' and classes' stored properties (using ``Mirror``).
You can iterate over range literals created using ``N...M`` syntax, both in ascending and descending order:
.. code-block:: html+django
{% for i in 1...array.count %}
- {{ i }}
{% endfor %}
The ``for`` tag can contain optional ``where`` expression to filter out elements on which this expression evaluates to false.
.. code-block:: html+django
{% for user in users where user.name != "Kyle" %}
- {{ user }}
{% endfor %}
The ``for`` tag can take an optional ``{% empty %}`` block that will be displayed if the given list is empty or could not be found.
.. code-block:: html+django
{% for user in users %}
- {{ user }}
{% empty %}
- There are no users.
{% endfor %}
The for block sets a few variables available within the loop:
- ``first`` - True if this is the first time through the loop
- ``last`` - True if this is the last time through the loop
- ``counter`` - The current iteration of the loop (1 indexed)
- ``counter0`` - The current iteration of the loop (0 indexed)
- ``length`` - The total length of the loop
For example:
.. code-block:: html+django
{% for user in users %}
{% if forloop.first %}
This is the first user.
{% endif %}
{% endfor %}
.. code-block:: html+django
{% for user in users %}
This is user number {{ forloop.counter }} user.
{% endfor %}
The ``for`` tag accepts an optional label, so that it may later be referred to by name. The contexts of parent labeled loops can be accessed via the `forloop` property:
.. code-block:: html+django
{% outer: for item in users %}
{% for item in 1..3 %}
{% if forloop.outer.first %}
This is the first user.
{% endif %}
{% endfor %}
{% endfor %}
``break``
~~~~~~~~~
The ``break`` tag lets you jump out of a for loop, for example if a certain condition is met:
.. code-block:: html+django
{% for user in users %}
{% if user.inaccessible %}
{% break %}
{% endif %}
This is user {{ user.name }}.
{% endfor %}
Break tags accept an optional label parameter, so that you may break out of multiple loops:
.. code-block:: html+django
{% outer: for user in users %}
{% for address in user.addresses %}
{% if address.isInvalid %}
{% break outer %}
{% endif %}
{% endfor %}
{% endfor %}
``continue``
~~~~~~~~~
The ``continue`` tag lets you skip the rest of the blocks in a loop, for example if a certain condition is met:
.. code-block:: html+django
{% for user in users %}
{% if user.inaccessible %}
{% continue %}
{% endif %}
This is user {{ user.name }}.
{% endfor %}
Continue tags accept an optional label parameter, so that you may skip the execution of multiple loops:
.. code-block:: html+django
{% outer: for user in users %}
{% for address in user.addresses %}
{% if address.isInvalid %}
{% continue outer %}
{% endif %}
{% endfor %}
{% endfor %}
``if``
~~~~~~
The ``{% if %}`` tag evaluates a variable, and if that variable evaluates to true the contents of the block are processed. Being true is defined as:
* Present in the context
* Being non-empty (dictionaries or arrays)
* Not being a false boolean value
* Not being a numerical value of 0 or below
* Not being an empty string
.. code-block:: html+django
{% if admin %}
The user is an administrator.
{% elif user %}
A user is logged in.
{% else %}
No user was found.
{% endif %}
Operators
^^^^^^^^^
``if`` tags may combine ``and``, ``or`` and ``not`` to test multiple variables or to negate a variable.
.. code-block:: html+django
{% if one and two %}
Both one and two evaluate to true.
{% endif %}
{% if not one %}
One evaluates to false
{% endif %}
{% if one or two %}
Either one or two evaluates to true.
{% endif %}
{% if not one or two %}
One does not evaluate to false or two evaluates to true.
{% endif %}
You may use ``and``, ``or`` and ``not`` multiple times together. ``not`` has
higest precedence followed by ``and``. For example:
.. code-block:: html+django
{% if one or two and three %}
Will be treated as:
.. code-block:: text
one or (two and three)
You can use parentheses to change operator precedence. For example:
.. code-block:: html+django
{% if (one or two) and three %}
Will be treated as:
.. code-block:: text
(one or two) and three
``==`` operator
"""""""""""""""
.. code-block:: html+django
{% if value == other_value %}
value is equal to other_value
{% endif %}
.. note:: The equality operator only supports numerical, string and boolean types.
``!=`` operator
"""""""""""""""
.. code-block:: html+django
{% if value != other_value %}
value is not equal to other_value
{% endif %}
.. note:: The inequality operator only supports numerical, string and boolean types.
``<`` operator
"""""""""""""""
.. code-block:: html+django
{% if value < other_value %}
value is less than other_value
{% endif %}
.. note:: The less than operator only supports numerical types.
``<=`` operator
"""""""""""""""
.. code-block:: html+django
{% if value <= other_value %}
value is less than or equal to other_value
{% endif %}
.. note:: The less than equal operator only supports numerical types.
``>`` operator
"""""""""""""""
.. code-block:: html+django
{% if value > other_value %}
value is more than other_value
{% endif %}
.. note:: The more than operator only supports numerical types.
``>=`` operator
"""""""""""""""
.. code-block:: html+django
{% if value >= other_value %}
value is more than or equal to other_value
{% endif %}
.. note:: The more than equal operator only supports numerical types.
``ifnot``
~~~~~~~~~
.. note:: ``{% ifnot %}`` is deprecated. You should use ``{% if not %}``.
.. code-block:: html+django
{% ifnot variable %}
The variable was NOT found in the current context.
{% else %}
The variable was found.
{% endif %}
``now``
~~~~~~~
``filter``
~~~~~~~~~~
Filters the contents of the block.
.. code-block:: html+django
{% filter lowercase %}
This Text Will Be Lowercased.
{% endfilter %}
You can chain multiple filters with a pipe (`|`).
.. code-block:: html+django
{% filter lowercase|capitalize %}
This Text Will First Be Lowercased, Then The First Character Will BE
Capitalised.
{% endfilter %}
``include``
~~~~~~~~~~~
You can include another template using the `include` tag.
.. code-block:: html+django
{% include "comment.html" %}
By default the included file gets passed the current context. You can pass a sub context by using an optional 2nd parameter as a lookup in the current context.
.. code-block:: html+django
{% include "comment.html" comment %}
The `include` tag requires you to provide a loader which will be used to lookup the template.
.. code-block:: swift
let environment = Environment(bundle: [Bundle.main])
let template = environment.loadTemplate(name: "index.html")
``extends``
~~~~~~~~~~~
Extends the template from a parent template.
.. code-block:: html+django
{% extends "base.html" %}
See :ref:`template-inheritance` for more information.
``block``
~~~~~~~~~
Defines a block that can be overridden by child templates. See :ref:`template-inheritance` for more information.
.. _built-in-filters:
Built-in Filters
----------------
``capitalize``
~~~~~~~~~~~~~~
The capitalize filter allows you to capitalize a string. For example, `stencil` to `Stencil`. Can be applied to array of strings to change each string.
.. code-block:: html+django
{{ "stencil"|capitalize }}
``uppercase``
~~~~~~~~~~~~~
The uppercase filter allows you to transform a string to uppercase. For example, `Stencil` to `STENCIL`. Can be applied to array of strings to change each string.
.. code-block:: html+django
{{ "Stencil"|uppercase }}
``lowercase``
~~~~~~~~~~~~~
The uppercase filter allows you to transform a string to lowercase. For example, `Stencil` to `stencil`. Can be applied to array of strings to change each string.
.. code-block:: html+django
{{ "Stencil"|lowercase }}
``default``
~~~~~~~~~~~
If a variable not present in the context, use given default. Otherwise, use the value of the variable. For example:
.. code-block:: html+django
Hello {{ name|default:"World" }}
``join``
~~~~~~~~
Join an array of items.
.. code-block:: html+django
{{ value|join:", " }}
.. note:: The value MUST be an array. Default argument value is empty string.
``split``
~~~~~~~~~
Split string into substrings by separator.
.. code-block:: html+django
{{ value|split:", " }}
.. note:: The value MUST be a String. Default argument value is a single-space string.
``indent``
~~~~~~~~~
Indents lines of rendered value or block.
.. code-block:: html+django
{{ value|indent:2," ",true }}
Filter accepts several arguments:
* indentation width: number of indentation characters to indent lines with. Default is ``4``.
* indentation character: character to be used for indentation. Default is a space.
* indent first line: whether first line of output should be indented or not. Default is ``false``.
``filter``
~~~~~~~~~
Applies the filter with the name provided as an argument to the current expression.
.. code-block:: html+django
{{ string|filter:myfilter }}
This expression will resolve the `myfilter` variable, find a filter named the same as resolved value, and will apply it to the `string` variable. I.e. if `myfilter` variable resolves to string `uppercase` this expression will apply file `uppercase` to `string` variable.