A template engine for people who enjoy the simpler things in life.

Version 3.2.0

Instruction Tag Reference


{% block <title> %} ... {% endblock %}

The block tag is used with the extends tag to implement template inheritance. The title argument is an arbitrary alphanumeric identifier for the block.


{% cycle <expr> %}

The cycle tag can be used within a loop to cycle over the values of an iterable expression. Each time the tag is encountered it prints the next value in the sequence.

A typical use case might be to add alternating CSS classes to elements in a list:

    {% for item in somelist %}
        <li class="{% cycle 'odd', 'even' %}">{{ item }}</li>
    {% endfor %}


{% extends <parent-template> %}

The extends tag is used with the block tag to implement template inheritance. The parent-template argument should be a quoted string literal specifying the name of the parent template.


{% include <template-name> %}

The include tag incorporates a sub-template into the current template. The template-name argument should be a quoted string literal or an expression that evaluates to a string; it should specify the name of the sub-template to include. (Note that you need to configure a template loader to use this tag.)

You can specify variables for the included template using the with keyword:

{% include "gallery.html" with size = "large" %}

Use & symbols to separate multiple variable declarations:

{% include "gallery.html" with size = "large" & max = 25 %}

A variable's value can be any valid expression.


{% for <varname> in <expr> %} ... [ {% empty %} ... ] {% endfor %}

The for tag implements looping over an iterable expression. for tags support variable unpacking and an optional empty clause that gets rendered if the sequence is empty:

{% for key, value in somedict.items() %}
    {{ key }}: {{ value }}
{% empty %}
    The dictionary is empty.
{% endfor %}

The automatic loop variable gives access to some useful data within the body of the loop:

loop.index The current iteration of the loop (0-indexed).
loop.count The current iteration of the loop (1-indexed).
loop.length The number of items in the sequence.
loop.is_first True on the first iteration of the loop.
loop.is_last True on the last iteration of the loop.
loop.parent For nested loops, the loop variable of the parent loop.


{% if <expr> %} ... {% endif %}

{% if <expr> <operator> <expr> %} ... {% endif %}

The if tag implements conditional branching. You can test the 'truthiness' of an expression or use any of the standard ==, !=, <, >, <=, >=, in, not in operators to compare pairs of expressions:

{% if author %}
    By {{ author }}.
{% endif %}

{% if author|lower == "bob" %}
    It's Bob again.
{% endif %}

The if tag supports multiple elif clauses, along with an optional else clause:

{% if balance > 100 %}
    We have lots of money.
{% elif balance > 50 %}
    We have some money.
{% else %}
    We're a little short on money.
{% endif %}

The if tag also supports negation with the not keyword and combination with the and and or keywords; and has higher precedence than or so the condition:

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

is evaluated as:

{% if (a and b) or (c and d) %}

Note that explicit brackets are not supported by the syntax.


{% spaceless %} ... {% endspaceless %}

The spaceless tag strips all whitespace from between HTML tags. For example, the HTML string:

{% spaceless %}
        <li>List item.</li>
{% endspaceless %}

would be rendered as:

<ul><li>List item.</li></ul>

Note that leading and trailing whitespace is also stripped.


{% trim %} ... {% endtrim %}

The trim tag strips all leading and trailing whitespace from its content.


{% with <name> = <expr> %} ... {% endwith %}

The with tag caches a complex expression under a simpler alias. It's particularly useful for caching expensive method calls, e.g. database lookups:

{% with foo = expensive.database.lookup("arg") %}
    ... do something with {{ foo }} ...
{% endwith %}

Use & symbols to separate multiple variable declarations:

{% with foo = get_foo() & bar = get_bar() %}
    ... do something with {{ foo }} and {{ bar }} ...
{% endwith %}

A variable's value can be any valid expression.