Built-in template tags and filters

Built-in template tags and filters

This document describes Django’s built-in template tags and filters. It is recommended that you use the automatic documentation, if available, as this will also include documentation for any custom tags or filters installed.

Built-in tag reference

autoescape

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 %}

block

Define a block that can be overridden by child templates. See Template inheritance for more information.

comment

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

csrf_token

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 Cross Site Request Forgeries.

cycle

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?

New in Django Development version.

By default, when you use the as keyword with the cycle tag, the usage of {% cycle %} that declares the cycle will itself output the first value in the cycle. This could be a problem if you want to use the value in a nested loop or an included template. If you want to just declare the cycle, but not output the first value, you can add a silent keyword as the last keyword in the tag. For example:

{% cycle 'row1' 'row2' as rowcolors silent %}
{% for obj in some_list %}
<tr class="{% cycle rowcolors %}">{{ obj }}</tr>
{% endfor %}

This will output a list of <tr> elements with class alternating between row1 and row2. If the silent keyword were to be omitted, row1 would be emitted as normal text, outside the list of <tr> elements, and the first <tr> would have a class ofrow2.

debug

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

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 Template inheritance for more information.

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 %}

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 %}

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 %}.
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 dictionarydata, 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

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: