Aliases :	`count`

<div class="columwrapper"> {%- for column in items|slice(3) %} <ul class="column-{{ loop.index }}"> {%- for item in column %} <li>{{ item }}</li> {%- endfor %} </ul> {%- endfor %} </div>

List of Builtin Tests¶

callable(object)¶: Return whether the object is callable (i.e., some kind of function). Note that classes are callable, as are instances with a __call__() method.

defined(value)¶

Return true if the variable is defined:

{% if variable is defined %}
    value of variable: {{ variable }}
{% else %}
    variable is not defined
{% endif %}

See the default() filter for a simple way to set undefined variables.

divisibleby(value, num)¶: Check if a variable is divisible by a number.

escaped(value)¶: Check if the value is escaped.

even(value)¶: Return true if the variable is even.

iterable(value)¶: Check if it’s possible to iterate over an object.

lower(value): Return true if the variable is lowercased.

mapping(value)¶

Return true if the object is a mapping (dict etc.).

New in version 2.6.

none(value)¶: Return true if the variable is none.

number(value)¶: Return true if the variable is a number.

odd(value)¶: Return true if the variable is odd.

sameas(value, other)¶

Check if an object points to the same memory address than another object:

{% if foo.attribute is sameas false %}
    the foo attribute really is the `False` singleton
{% endif %}

sequence(value)¶: Return true if the variable is a sequence. Sequences are variables that are iterable.

string(value): Return true if the object is a string.

undefined(value)¶: Like defined() but the other way round.

upper(value): Return true if the variable is uppercased.

List of Global Functions¶

The following functions are available in the global scope by default:

range([start], stop[, step])¶

Return a list containing an arithmetic progression of integers. range(i, j) returns [i, i+1, i+2, ..., j-1]; start (!) defaults to 0. When step is given, it specifies the increment (or decrement). For example, range(4) returns [0, 1, 2, 3]. The end point is omitted! These are exactly the valid indices for a list of 4 elements.

This is useful to repeat a template block multiple times for example to fill a list. Imagine you have 7 users in the list but you want to render three empty items to enforce a height with CSS:

<ul>
{% for user in users %}
    <li>{{ user.username }}</li>
{% endfor %}
{% for number in range(10 - users|count) %}
    <li class="empty"><span>...</span></li>
{% endfor %}
</ul>

lipsum(n=5, html=True, min=20, max=100)¶: Generates some lorem ipsum for the template. Per default five paragraphs with HTML are generated each paragraph between 20 and 100 words. If html is disabled regular text is returned. This is useful to generate simple contents for layout testing.

dict(**items)¶: A convenient alternative to dict literals. {'foo': 'bar'} is the same as dict(foo='bar').

class cycler(*items)¶

The cycler allows you to cycle among values similar to how loop.cycle works. Unlike loop.cycle however you can use this cycler outside of loops or over multiple loops.

This is for example very useful if you want to show a list of folders and files, with the folders on top, but both in the same list with alternating row colors.

The following example shows how cycler can be used:

{% set row_class = cycler('odd', 'even') %}
<ul class="browser">
{% for folder in folders %}
  <li class="folder {{ row_class.next() }}">{{ folder|e }}</li>
{% endfor %}
{% for filename in files %}
  <li class="file {{ row_class.next() }}">{{ filename|e }}</li>
{% endfor %}
</ul>

A cycler has the following attributes and methods:

reset()¶: Resets the cycle to the first item.

next()¶: Goes one item a head and returns the then current item.

current¶: Returns the current item.

new in Jinja 2.1

class joiner(sep=', ')¶

A tiny helper that can be use to “join” multiple sections. A joiner is passed a string and will return that string every time it’s called, except the first time in which situation it returns an empty string. You can use this to join things:

{% set pipe = joiner("|") %}
{% if categories %} {{ pipe() }}
    Categories: {{ categories|join(", ") }}
{% endif %}
{% if author %} {{ pipe() }}
    Author: {{ author() }}
{% endif %}
{% if can_edit %} {{ pipe() }}
    <a href="?action=edit">Edit</a>
{% endif %}

new in Jinja 2.1

Extensions¶

The following sections cover the built-in Jinja2 extensions that may be enabled by the application. The application could also provide further extensions not covered by this documentation. In that case there should be a separate document explaining the extensions.

i18n¶

If the i18n extension is enabled it’s possible to mark parts in the template as translatable. To mark a section as translatable you can use trans:

<p>{% trans %}Hello {{ user }}!{% endtrans %}</p>

To translate a template expression — say, using template filters or just accessing an attribute of an object — you need to bind the expression to a name for use within the translation block:

<p>{% trans user=user.username %}Hello {{ user }}!{% endtrans %}</p>

If you need to bind more than one expression inside a trans tag, separate the pieces with a comma (,):

{% trans book_title=book.title, author=author.name %}
This is {{ book_title }} by {{ author }}
{% endtrans %}

Inside trans tags no statements are allowed, only variable tags are.

To pluralize, specify both the singular and plural forms with the pluralize tag, which appears between trans and endtrans:

{% trans count=list|length %}
There is {{ count }} {{ name }} object.
{% pluralize %}
There are {{ count }} {{ name }} objects.
{% endtrans %}

Per default the first variable in a block is used to determine the correct singular or plural form. If that doesn’t work out you can specify the name which should be used for pluralizing by adding it as parameter to pluralize:

{% trans ..., user_count=users|length %}...
{% pluralize user_count %}...{% endtrans %}

It’s also possible to translate strings in expressions. For that purpose three functions exist:

_ gettext: translate a single string - ngettext: translate a pluralizable string - _: alias for gettext

For example you can print a translated string easily this way:

{{ _('Hello World!') }}

To use placeholders you can use the format filter:

{{ _('Hello %(user)s!')|format(user=user.username) }}

For multiple placeholders always use keyword arguments to format as other languages may not use the words in the same order.

Changed in version 2.5.

If newstyle gettext calls are activated (Newstyle Gettext), using placeholders is a lot easier:

{{ gettext('Hello World!') }}
{{ gettext('Hello %(name)s!', name='World') }}
{{ ngettext('%(num)d apple', '%(num)d apples', apples|count) }}

Note that the ngettext function’s format string automatically receives the count as num parameter additionally to the regular parameters.

Expression Statement¶

If the expression-statement extension is loaded a tag called do is available that works exactly like the regular variable expression ({{ ... }}) just that it doesn’t print anything. This can be used to modify lists:

{% do navigation.append('a string') %}

Loop Controls¶

If the application enables the Loop Controls it’s possible to use break and continue in loops. When break is reached, the loop is terminated; if continue is reached, the processing is stopped and continues with the next iteration.

Here a loop that skips every second item:

{% for user in users %}
    {%- if loop.index is even %}{% continue %}{% endif %}
    ...
{% endfor %}

Likewise a look that stops processing after the 10th iteration:

{% for user in users %}
    {%- if loop.index >= 10 %}{% break %}{% endif %}
{%- endfor %}

With Statement¶

New in version 2.3.

If the application enables the With Statement it is possible to use the with keyword in templates. This makes it possible to create a new inner scope. Variables set within this scope are not visible outside of the scope.

With in a nutshell:

{% with %}
    {% set foo = 42 %}
    {{ foo }}           foo is 42 here
{% endwith %}
foo is not visible here any longer

Because it is common to set variables at the beginning of the scope you can do that within the with statement. The following two examples are equivalent:

{% with foo = 42 %}
    {{ foo }}
{% endwith %}

{% with %}
    {% set foo = 42 %}
    {{ foo }}
{% endwith %}

Autoescape Extension¶

New in version 2.4.

If the application enables the Autoescape Extension one can activate and deactivate the autoescaping from within the templates.

Example:

{% autoescape true %}
    Autoescaping is active within this block
{% endautoescape %}

{% autoescape false %}
    Autoescaping is inactive within this block
{% endautoescape %}

After the endautoescape the behavior is reverted to what it was before.