==================================

Built-in template tags and filters

==================================

This document describes Django's built-in template tags and filters. It is

recommended that you use the :doc:`automatic documentation

</ref/contrib/admin/admindocs>`, if available, as this will also include

documentation for any custom tags or filters installed.

.. _ref-templates-builtins-tags:

Built-in tag reference

----------------------

.. highlightlang:: html+django

.. templatetag:: autoescape

autoescape

~~~~~~~~~~

.. versionadded:: 1.0

Control the current auto-escaping behavior. This tag takes either ``on`` or

``off`` as an argument and that determines whether auto-escaping is in effect

inside the block. The block is closed with an ``endautoescape`` ending tag.

When auto-escaping is in effect, all variable content has HTML escaping applied

to it before placing the result into the output (but after any filters have

been applied). This is equivalent to manually applying the ``escape`` filter

to each variable.

The only exceptions are variables that are already marked as "safe" from

escaping, either by the code that populated the variable, or because it has had

the ``safe`` or ``escape`` filters applied.

Sample usage::

    {% autoescape on %}

        {{ body }}

    {% endautoescape %}

.. templatetag:: block

block

~~~~~

Define a block that can be overridden by child templates. See

:ref:`Template inheritance <template-inheritance>` for more information.

.. templatetag:: comment

comment

~~~~~~~

Ignore everything between ``{% comment %}`` and ``{% endcomment %}``

.. templatetag:: csrf_token

csrf_token

~~~~~~~~~~

.. versionadded:: 1.1.2

In the Django 1.1.X series, this is a no-op tag that returns an empty string for

future compatibility purposes.  In Django 1.2 and later, it is used for CSRF

protection, as described in the documentation for :doc:`Cross Site Request

Forgeries </ref/contrib/csrf>`.

.. templatetag:: cycle

cycle

~~~~~

.. versionchanged:: 1.0

    Cycle among the given strings or variables each time this tag is encountered.

Within a loop, cycles among the given strings each time through the

loop::

    {% for o in some_list %}

        <tr class="{% cycle 'row1' 'row2' %}">

            ...

        </tr>

    {% endfor %}

You can use variables, too. For example, if you have two template variables,

``rowvalue1`` and ``rowvalue2``, you can cycle between their values like this::

    {% for o in some_list %}

        <tr class="{% cycle rowvalue1 rowvalue2 %}">

            ...

        </tr>

    {% endfor %}

Yes, you can mix variables and strings::

    {% for o in some_list %}

        <tr class="{% cycle 'row1' rowvalue2 'row3' %}">

            ...

        </tr>

    {% endfor %}

In some cases you might want to refer to the next value of a cycle from

outside of a loop. To do this, just give the ``{% cycle %}`` tag a name, using

"as", like this::

    {% cycle 'row1' 'row2' as rowcolors %}

From then on, you can insert the current value of the cycle wherever you'd like

in your template::

    <tr class="{% cycle rowcolors %}">...</tr>

    <tr class="{% cycle rowcolors %}">...</tr>

You can use any number of values in a ``{% cycle %}`` tag, separated by spaces.

Values enclosed in single (``'``) or double quotes (``"``) are treated as

string literals, while values without quotes are treated as template variables.

Note that the variables included in the cycle will not be escaped.

This is because template tags do not escape their content. Any HTML or

Javascript code contained in the printed variable will be rendered

as-is, which could potentially lead to security issues.

If you need to escape the variables in the cycle, you must do so

explicitly::

    {% filter force_escape %}

        {% cycle var1 var2 var3 %}

    {% endfilter %}

For backwards compatibility, the ``{% cycle %}`` tag supports the much inferior

old syntax from previous Django versions. You shouldn't use this in any new

projects, but for the sake of the people who are still using it, here's what it

looks like::

    {% cycle row1,row2,row3 %}

In this syntax, each value gets interpreted as a literal string, and there's no

way to specify variable values. Or literal commas. Or spaces. Did we mention

you shouldn't use this syntax in any new projects?

.. templatetag:: debug

debug

~~~~~

Output a whole load of debugging information, including the current context and

imported modules.

.. templatetag:: extends

extends

~~~~~~~

Signal that this template extends a parent template.

This tag can be used in two ways:

   * ``{% extends "base.html" %}`` (with quotes) uses the literal value

     ``"base.html"`` as the name of the parent template to extend.

   * ``{% extends variable %}`` uses the value of ``variable``. If the variable

     evaluates to a string, Django will use that string as the name of the

     parent template. If the variable evaluates to a ``Template`` object,

     Django will use that object as the parent template.

See :ref:`template-inheritance` for more information.

.. templatetag:: filter

filter

~~~~~~

Filter the contents of the variable through variable filters.

Filters can also be piped through each other, and they can have arguments --

just like in variable syntax.

Sample usage::

    {% filter force_escape|lower %}

        This text will be HTML-escaped, and will appear in all lowercase.

    {% endfilter %}

.. templatetag:: firstof

firstof

~~~~~~~

Outputs the first variable passed that is not False, without escaping.

Outputs nothing if all the passed variables are False.

Sample usage::

    {% firstof var1 var2 var3 %}

This is equivalent to::

    {% if var1 %}

        {{ var1|safe }}

    {% else %}{% if var2 %}

        {{ var2|safe }}

    {% else %}{% if var3 %}

        {{ var3|safe }}

    {% endif %}{% endif %}{% endif %}

You can also use a literal string as a fallback value in case all

passed variables are False::

    {% firstof var1 var2 var3 "fallback value" %}

Note that the variables included in the firstof tag will not be

escaped. This is because template tags do not escape their content.

Any HTML or Javascript code contained in the printed variable will be

rendered as-is, which could potentially lead to security issues.

If you need to escape the variables in the firstof tag, you must do so

explicitly::

    {% filter force_escape %}

        {% firstof var1 var2 var3 "fallback value" %}

    {% endfilter %}

.. templatetag:: for

for

~~~

Loop over each item in an array.  For example, to display a list of athletes

provided in ``athlete_list``::

    <ul>

    {% for athlete in athlete_list %}

        <li>{{ athlete.name }}</li>

    {% endfor %}

    </ul>

You can loop over a list in reverse by using ``{% for obj in list reversed %}``.

.. versionadded:: 1.0

If you need to loop over a list of lists, you can unpack the values

in each sub-list into individual variables. For example, if your context

contains a list of (x,y) coordinates called ``points``, you could use the

following to output the list of points::

    {% for x, y in points %}

        There is a point at {{ x }},{{ y }}

    {% endfor %}

This can also be useful if you need to access the items in a dictionary.

For example, if your context contained a dictionary ``data``, the following

would display the keys and values of the dictionary::

    {% for key, value in data.items %}

        {{ key }}: {{ value }}

    {% endfor %}

The for loop sets a number of variables available within the loop:

    ==========================  ================================================

    Variable                    Description

    ==========================  ================================================

    ``forloop.counter``         The current iteration of the loop (1-indexed)

    ``forloop.counter0``        The current iteration of the loop (0-indexed)

    ``forloop.revcounter``      The number of iterations from the end of the

                                loop (1-indexed)

    ``forloop.revcounter0``     The number of iterations from the end of the

                                loop (0-indexed)

    ``forloop.first``           True if this is the first time through the loop

    ``forloop.last``            True if this is the last time through the loop

    ``forloop.parentloop``      For nested loops, this is the loop "above" the

                                current one

    ==========================  ================================================

for ... empty

^^^^^^^^^^^^^

.. versionadded:: 1.1

The ``for`` tag can take an optional ``{% empty %}`` clause that will be

displayed if the given array is empty or could not be found::

    <ul>

    {% for athlete in athlete_list %}

        <li>{{ athlete.name }}</li>

    {% empty %}

        <li>Sorry, no athlete in this list!</li>

    {% endfor %}

    <ul>

The above is equivalent to -- but shorter, cleaner, and possibly faster

than -- the following::

    <ul>

      {% if athlete_list %}

        {% for athlete in athlete_list %}

          <li>{{ athlete.name }}</li>

        {% endfor %}

      {% else %}

        <li>Sorry, no athletes in this list.</li>

      {% endif %}

    </ul>

.. templatetag:: if

if

~~

The ``{% if %}`` tag evaluates a variable, and if that variable is "true" (i.e.

exists, is not empty, and is not a false boolean value) the contents of the

block are output::

    {% if athlete_list %}

        Number of athletes: {{ athlete_list|length }}

    {% else %}

        No athletes.

    {% endif %}

In the above, if ``athlete_list`` is not empty, the number of athletes will be

displayed by the ``{{ athlete_list|length }}`` variable.

As you can see, the ``if`` tag can take an optional ``{% else %}`` clause that

will be displayed if the test fails.

Boolean operators

^^^^^^^^^^^^^^^^^

``if`` tags may use ``and``, ``or`` or ``not`` to test a number of variables or

to negate a given variable::

    {% if athlete_list and coach_list %}

        Both athletes and coaches are available.

    {% endif %}

    {% if not athlete_list %}

        There are no athletes.

    {% endif %}

    {% if athlete_list or coach_list %}

        There are some athletes or some coaches.

    {% endif %}

    {% if not athlete_list or coach_list %}

        There are no athletes or there are some coaches (OK, so

        writing English translations of boolean logic sounds

        stupid; it's not our fault).

    {% endif %}

    {% if athlete_list and not coach_list %}

        There are some athletes and absolutely no coaches.

    {% endif %}

.. versionchanged:: 1.2

Use of both ``and`` and ``or`` clauses within the same tag is allowed, with

``and`` having higher precedence than ``or`` e.g.::

    {% if athlete_list and coach_list or cheerleader_list %}

will be interpreted like:

.. code-block:: python

    if (athlete_list and coach_list) or cheerleader_list

Use of actual brackets in the ``if`` tag is invalid syntax.  If you need them to

indicate precedence, you should use nested ``if`` tags.

.. versionadded:: 1.2

``if`` tags may also use the operators ``==``, ``!=``, ``<``, ``>``,

``<=``, ``>=`` and ``in`` which work as follows:

``==`` operator

^^^^^^^^^^^^^^^

Equality. Example::

    {% if somevar == "x" %}

      This appears if variable somevar equals the string "x"

    {% endif %}

``!=`` operator

^^^^^^^^^^^^^^^

Inequality. Example::

    {% if somevar != "x" %}

      This appears if variable somevar does not equal the string "x",

      or if somevar is not found in the context

    {% endif %}

``<`` operator

^^^^^^^^^^^^^^

Less than. Example::

    {% if somevar < 100 %}

      This appears if variable somevar is less than 100.

    {% endif %}

``>`` operator

^^^^^^^^^^^^^^

Greater than. Example::

    {% if somevar > 0 %}

      This appears if variable somevar is greater than 0.

    {% endif %}

``<=`` operator

^^^^^^^^^^^^^^^

Less than or equal to. Example::

    {% if somevar <= 100 %}

      This appears if variable somevar is less than 100 or equal to 100.

    {% endif %}

``>=`` operator

^^^^^^^^^^^^^^^

Greater than or equal to. Example::

    {% if somevar >= 1 %}

      This appears if variable somevar is greater than 1 or equal to 1.

    {% endif %}

``in`` operator

^^^^^^^^^^^^^^^

Contained within. This operator is supported by many Python containers to test

whether the given value is in the container.  The following are some examples of

how ``x in y`` will be interpreted::

    {% if "bc" in "abcdef" %}

      This appears since "bc" is a substring of "abcdef"

    {% endif %}

    {% if "hello" in greetings %}

      If greetings is a list or set, one element of which is the string

      "hello", this will appear.

    {% endif %}

    {% if user in users %}

      If users is a QuerySet, this will appear if user is an

      instance that belongs to the QuerySet.

    {% endif %}

``not in`` operator

~~~~~~~~~~~~~~~~~~~~

Not contained within.  This is the negation of the ``in`` operator.

The comparison operators cannot be 'chained' like in Python or in mathematical

notation. For example, instead of using::

    {% if a > b > c %}  (WRONG)

you should use::

    {% if a > b and b > c %}

Filters

^^^^^^^

You can also use filters in the ``if`` expression. For example::

    {% if messages|length >= 100 %}

       You have lots of messages today!

    {% endif %}

Complex expressions

^^^^^^^^^^^^^^^^^^^

All of the above can be combined to form complex expressions. For such

expressions, it can be important to know how the operators are grouped when the

expression is evaluated - that is, the precedence rules.  The precedence of the

operators, from lowest to highest, is as follows:

 * ``or``

 * ``and``

 * ``not``

 * ``in``

 * ``==``, ``!=``, ``<``, ``>``,``<=``, ``>=``

(This follows Python exactly). So, for example, the following complex if tag:

    {% if a == b or c == d and e %}

...will be interpreted as:

.. code-block:: python

    (a == b) or ((c == d) and e)

If you need different precedence, you will need to use nested if tags. Sometimes

that is better for clarity anyway, for the sake of those who do not know the

precedence rules.

.. templatetag:: ifchanged

ifchanged

~~~~~~~~~

Check if a value has changed from the last iteration of a loop.

The 'ifchanged' block tag is used within a loop. It has two possible uses.

1. Checks its own rendered contents against its previous state and only

   displays the content if it has changed. For example, this displays a list of

   days, only displaying the month if it changes::

        <h1>Archive for {{ year }}</h1>

        {% for date in days %}

            {% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %}

            <a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a>

        {% endfor %}

2. If given a variable, check whether that variable has changed. For