714 lines
23 KiB
ReStructuredText
714 lines
23 KiB
ReStructuredText
======================
|
|
Designer Documentation
|
|
======================
|
|
|
|
This part of the Jinja documentaton is meant for template designers.
|
|
|
|
Basics
|
|
======
|
|
|
|
The Jinja template language is designed to strike a balance between content
|
|
and application logic. Nevertheless you can use a python like statement
|
|
language. You don't have to know how Python works to create Jinja templates,
|
|
but if you know it you can use some additional statements you may know from
|
|
Python.
|
|
|
|
Here is a small example template:
|
|
|
|
.. sourcecode:: html+jinja
|
|
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
|
|
<head>
|
|
<title>My Webpage</title>
|
|
</head>
|
|
<body>
|
|
<ul id="navigation">
|
|
{% for item in navigation %}
|
|
<li><a href="{{ item.href|e }}">{{ item.caption|e }}</a></li>
|
|
{% endfor %}
|
|
</ul>
|
|
|
|
<h1>My Webpage</h1>
|
|
{{ variable }}
|
|
</body>
|
|
</html>
|
|
|
|
This covers the default settings. The application developer might have changed
|
|
the syntax from ``{% foo %}`` to ``<% foo %>`` or something similar. This
|
|
documentation just covers the default values.
|
|
|
|
A variable looks like ``{{ foobar }}`` where foobar is the variable name. Inside
|
|
of statements (``{% some content here %}``) variables are just normal names
|
|
without the braces around it. In fact ``{{ foobar }}`` is just an alias for
|
|
the statement ``{% print foobar %}``.
|
|
|
|
Variables are coming from the context provided by the application. Normally there
|
|
should be a documentation regarding the context contents but if you want to know
|
|
the content of the current context, you can add this to your template:
|
|
|
|
.. sourcecode:: html+jinja
|
|
|
|
<pre>{{ debug()|e }}</pre>
|
|
|
|
A context isn't flat which means that each variable can has subvariables, as long
|
|
as it is representable as python data structure. You can access attributes of
|
|
a variable using the dot and bracket operators. The following examples show
|
|
this:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{{ user.username }}
|
|
is the same as
|
|
{{ user['username'] }}
|
|
you can also use a variable to access an attribute:
|
|
{{ users[current_user].username }}
|
|
If you have numerical indices you have to use the [] syntax:
|
|
{{ users[0].username }}
|
|
|
|
Filters
|
|
=======
|
|
|
|
In the examples above you might have noticed the pipe symbols. Pipe symbols tell
|
|
the engine that it has to apply a filter on the variable. Here is a small example:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{{ variable|replace('foo', 'bar')|escape }}
|
|
|
|
If you want, you can also put whitespace between the filters.
|
|
|
|
This will look for a variable `variable`, pass it to the filter `replace`
|
|
with the arguments ``'foo'`` and ``'bar'``, and pass the result to the filter
|
|
`escape` that automatically XML-escapes the value. The `e` filter is an alias for
|
|
`escape`. Here is the complete list of supported filters:
|
|
|
|
[[list_of_filters]]
|
|
|
|
.. admonition:: note
|
|
|
|
Filters have a pretty low priority. If you want to add fitered values
|
|
you have to put them into parentheses. The same applies if you want to access
|
|
attributes:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
correct:
|
|
{{ (foo|filter) + (bar|filter) }}
|
|
wrong:
|
|
{{ foo|filter + bar|filter }}
|
|
|
|
correct:
|
|
{{ (foo|filter).attribute }}
|
|
wrong:
|
|
{{ foo|filter.attribute }}
|
|
|
|
Tests
|
|
=====
|
|
|
|
You can use the `is` operator to perform tests on a value:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{{ 42 is numeric }} -> true
|
|
{{ "foobar" is numeric }} -> false
|
|
{{ 'FOO' is upper }} -> true
|
|
|
|
These tests are especially useful when used in `if` conditions.
|
|
|
|
[[list_of_tests]]
|
|
|
|
Global Functions
|
|
================
|
|
|
|
Test functions and filter functions live in their own namespace. Global
|
|
functions not. They behave like normal objects in the context. Beside the
|
|
functions added by the application or framewhere there are two functions
|
|
available per default:
|
|
|
|
`range`
|
|
|
|
Works like the python `range function`_ just that it doesn't support
|
|
ranges greater than ``1000000``.
|
|
|
|
`debug`
|
|
|
|
Function that outputs the contents of the context.
|
|
|
|
Loops
|
|
=====
|
|
|
|
To iterate over a sequence, you can use the `for` loop. It basically looks like a
|
|
normal Python `for` loop and works pretty much the same:
|
|
|
|
.. sourcecode:: html+jinja
|
|
|
|
<h1>Members</h1>
|
|
<ul>
|
|
{% for user in users %}
|
|
<li>{{ loop.index }} / {{ loop.length }} - {{ user.username|escape }}</li>
|
|
{% else %}
|
|
<li><em>no users found</em></li>
|
|
{% endfor %}
|
|
</ul>
|
|
|
|
*Important* Contrary to Python is the optional ``else`` block only
|
|
executed if there was no iteration because the sequence was empty.
|
|
|
|
Inside of a `for` loop block you can access some special variables:
|
|
|
|
+----------------------+----------------------------------------+
|
|
| Variable | Description |
|
|
+======================+========================================+
|
|
| `loop.index` | The current iteration of the loop. |
|
|
+----------------------+----------------------------------------+
|
|
| `loop.index0` | The current iteration of the loop, |
|
|
| | starting counting by 0. |
|
|
+----------------------+----------------------------------------+
|
|
| `loop.revindex` | The number of iterations from the end |
|
|
| | of the loop. |
|
|
+----------------------+----------------------------------------+
|
|
| `loop.revindex0` | The number of iterations from the end |
|
|
| | of the loop, starting counting by 0. |
|
|
+----------------------+----------------------------------------+
|
|
| `loop.first` | True if first iteration. |
|
|
+----------------------+----------------------------------------+
|
|
| `loop.last` | True if last iteration. |
|
|
+----------------------+----------------------------------------+
|
|
| `loop.even` | True if current iteration is even. |
|
|
+----------------------+----------------------------------------+
|
|
| `loop.odd` | True if current iteration is odd. |
|
|
+----------------------+----------------------------------------+
|
|
| `loop.length` | Total number of items in the sequence. |
|
|
+----------------------+----------------------------------------+
|
|
| `loop.parent` | The context of the parent loop. |
|
|
+----------------------+----------------------------------------+
|
|
|
|
Loops also support recursion. Let's assume you have a sitemap where each item
|
|
might have a number of child items. A template for that could look like this:
|
|
|
|
.. sourcecode:: html+jinja
|
|
|
|
<h1>Sitemap
|
|
<ul id="sitemap">
|
|
{% for item in sitemap recursive %}
|
|
<li><a href="{{ item.url|e }}">{{ item.title|e }}</a>
|
|
{% if item.children %}<ul>{{ loop(item.children) }}</ul>{% endif %}</li>
|
|
{% endfor %}
|
|
</ul>
|
|
|
|
What happens here? Basically the first thing that is different to a normal
|
|
loop is the additional ``recursive`` modifier in the `for`-loop declaration.
|
|
It tells the template engine that we want recursion. If recursion is enabled
|
|
the special `loop` variable is callable. If you call it with a sequence it will
|
|
automatically render the loop at that position with the new sequence as argument.
|
|
|
|
Cycling
|
|
=======
|
|
|
|
Sometimes you might want to have different text snippets for each row in a list,
|
|
for example to have alternating row colors. You can easily do this by using the
|
|
``{% cycle %}`` tag:
|
|
|
|
.. sourcecode:: html+jinja
|
|
|
|
<ul id="messages">
|
|
{% for message in messages %}
|
|
<li class="{% cycle 'row1', 'row2' %}">{{ message|e }}</li>
|
|
{% endfor %}
|
|
</ul>
|
|
|
|
Each time Jinja encounters a `cycle` tag it will cycle through the list
|
|
of given items and return the next one. If you pass it one item jinja assumes
|
|
that this item is a sequence from the context and uses this:
|
|
|
|
.. sourcecode:: html+jinja
|
|
|
|
<li style="color: {% cycle rowcolors %}">...</li>
|
|
|
|
Conditions
|
|
==========
|
|
|
|
Jinja supports Python-like `if` / `elif` / `else` constructs:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{% if user.active %}
|
|
user {{ user.name|e }} is active.
|
|
{% elif user.deleted %}
|
|
user {{ user.name|e }} was deleted some time ago.
|
|
{% else %}
|
|
i don't know what's wrong with {{ user.username|e }}
|
|
{% endif %}
|
|
|
|
If the user is active the first block is rendered. If not and the user was
|
|
deleted the second one, in all other cases the third one.
|
|
|
|
You can also use comparison operators:
|
|
|
|
.. sourcecode:: html+jinja
|
|
|
|
{% if amount < 0 %}
|
|
<span style="color: red">{{ amount }}</span>
|
|
{% else %}
|
|
<span style="color: black">{{ amount }}</span>
|
|
{% endif %}
|
|
|
|
.. admonition:: Note
|
|
|
|
Of course you can use `or` / `and` and parentheses to create more complex
|
|
conditions, but usually the logic is already handled in the application and
|
|
you don't have to create such complex constructs in the template code. However
|
|
in some situations it might be a good thing to have the abilities to create
|
|
them.
|
|
|
|
Operators
|
|
=========
|
|
|
|
Inside ``{{ variable }}`` blocks, `if` conditions and many other parts you can
|
|
can use expressions. In expressions you can use any of the following operators:
|
|
|
|
======= ===================================================================
|
|
``+`` add the right operand to the left one.
|
|
``{{ 1 + 2 }}`` would return ``3``.
|
|
``-`` subtract the right operand from the left one.
|
|
``{{ 1 - 1 }}`` would return ``0``.
|
|
``/`` divide the left operand by the right one.
|
|
``{{ 1 / 2 }}`` would return ``0.5``.
|
|
``*`` multiply the left operand with the right one.
|
|
``{{ 2 * 2 }}`` would return ``4``.
|
|
``**`` raise the left operand to the power of the right
|
|
operand. ``{{ 2**3 }}`` would return ``8``.
|
|
``in`` perform sequence membership test. ``{{ 1 in [1,2,3] }}`` would
|
|
return true.
|
|
``is`` perform a test on the value. See the section about
|
|
tests for more information.
|
|
``|`` apply a filter on the value. See the section about
|
|
filters for more information.
|
|
``and`` return true if the left and the right operand is true.
|
|
``or`` return true if the left or the right operand is true.
|
|
``not`` negate a statement (see below)
|
|
``()`` call a callable: ``{{ user.get_username() }}``. Inside of the
|
|
parentheses you can use variables: ``{{ user.get(username) }}``.
|
|
======= ===================================================================
|
|
|
|
Note that there is no support for any bit operations or something similar.
|
|
|
|
* special note regarding `not`: The `is` and `in` operators support negation
|
|
using an infix notation too: ``foo is not bar`` and ``foo not in bar``
|
|
instead of ``not foo is bar`` and ``not foo in bar``. All other expressions
|
|
require a prefix notation: ``not (foo and bar)``.
|
|
|
|
Boolean Values
|
|
==============
|
|
|
|
In If-Conditions Jinja performs a boolean check. All empty values (eg: empty
|
|
lists ``[]``, empty dicts ``{}`` etc) evaluate to `false`. Numbers that are
|
|
equal to `0`/`0.00` are considered `false` too. The boolean value of other
|
|
objects depends on the behavior the application developer gave it. Usually
|
|
items are `true`.
|
|
|
|
Here some examples that should explain it:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{% if [] %}
|
|
will always be false because it's an empty list
|
|
|
|
{% if {} %}
|
|
false too.
|
|
|
|
{% if ['foo'] %}
|
|
this is true. Because the list is not empty.
|
|
|
|
{% if "foobar" %}
|
|
this is also true because the string is not empty.
|
|
|
|
Slicing
|
|
=======
|
|
|
|
Some objects support slicing operations. For example lists:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{% for item in items[:5] %}
|
|
This will only iterate over the first 5 items of the list
|
|
|
|
{% for item in items[5:10] %}
|
|
This will only iterate from item 5 to 10.
|
|
|
|
{% for item in items[:10:2] %}
|
|
This will only yield items from start to ten and only returing
|
|
even items.
|
|
|
|
For more informations about slicing have a look at the `slicing chapter`_
|
|
in the "Dive into Python" e-book.
|
|
|
|
Macros
|
|
======
|
|
|
|
If you want to use a partial template in more than one place, you might want to
|
|
create a macro from it:
|
|
|
|
.. sourcecode:: html+jinja
|
|
|
|
{% macro show_user user %}
|
|
<h1>{{ user.name|e }}</h1>
|
|
<div class="test">
|
|
{{ user.description }}
|
|
</div>
|
|
{% endmacro %}
|
|
|
|
Now you can use it from everywhere in the code by passing it an item:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{% for user in users %}
|
|
{{ show_user(user) }}
|
|
{% endfor %}
|
|
|
|
You can also specify more than one value:
|
|
|
|
.. sourcecode:: html+jinja
|
|
|
|
{% macro show_dialog title, text %}
|
|
<div class="dialog">
|
|
<h1>{{ title|e }}</h1>
|
|
<div class="test">{{ text|e }}</div>
|
|
</div>
|
|
{% endmacro %}
|
|
|
|
{{ show_dialog('Warning', 'something went wrong i guess') }}
|
|
|
|
Inheritance
|
|
===========
|
|
|
|
The most powerful part of Jinja is template inheritance. Template inheritance
|
|
allows you to build a base "skeleton" template that contains all the common
|
|
elements of your site and defines **blocks** that child templates can override.
|
|
|
|
Sounds complicated but is very basic. It's easiest to understand it by starting
|
|
with an example.
|
|
|
|
Base Template
|
|
-------------
|
|
|
|
This template, which we'll call ``base.html``, defines a simple HTML skeleton
|
|
document that you might use for a simple two-column page. It's the job of
|
|
"child" templates to fill the empty blocks with content:
|
|
|
|
.. sourcecode:: html+jinja
|
|
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<link rel="stylesheet" href="style.css" />
|
|
<title>{% block title %}{% endblock %} - My Webpage</title>
|
|
{% block html_head %}{% endblock %}
|
|
</head>
|
|
<body>
|
|
<div id="content">
|
|
{% block content %}{% endblock %}
|
|
</div>
|
|
|
|
<div id="footer">
|
|
{% block footer %}
|
|
© Copyright 2006 by <a href="http://mydomain.tld">myself</a>.
|
|
{% endblock %}
|
|
</div>
|
|
</body>
|
|
|
|
In this example, the ``{% block %}`` tags define four blocks that child templates
|
|
can fill in. All the `block` tag does is to tell the template engine that a
|
|
child template may override those portions of the template.
|
|
|
|
Child Template
|
|
--------------
|
|
|
|
A child template might look like this:
|
|
|
|
.. sourcecode:: html+jinja
|
|
|
|
{% extends "base.html" %}
|
|
{% block title %}Index{% endblock %}
|
|
|
|
{% block html_head %}
|
|
<style type="text/css">
|
|
.important {
|
|
color: #336699;
|
|
}
|
|
</style>
|
|
{% endblock %}
|
|
|
|
{% block content %}
|
|
<h1>Index</h1>
|
|
<p class="important">
|
|
Welcome on my awsome homepage.
|
|
</p>
|
|
{% endblock %}
|
|
|
|
The ``{% extends %}`` tag is the key here. It tells the template engine that
|
|
this template "extends" another template. When the template system evaluates
|
|
this template, first it locates the parent.
|
|
|
|
The filename of the template depends on the template loader. For example the
|
|
``FileSystemLoader`` allows you to access other templates by giving the
|
|
filename. You can access templates in subdirectories with an slash:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{% extends "layout/default.html" %}
|
|
|
|
But this behavior can depend on the application using Jinja.
|
|
|
|
Note that since the child template didn't define the ``footer`` block, the
|
|
value from the parent template is used instead.
|
|
|
|
.. admonition:: Note
|
|
|
|
You can't define multiple ``{% block %}`` tags with the same name in the
|
|
same template. This limitation exists because a block tag works in "both"
|
|
directions. That is, a block tag doesn't just provide a hole to fill - it
|
|
also defines the content that fills the hole in the *parent*. If there were
|
|
two similarly-named ``{% block %}`` tags in a template, that template's
|
|
parent wouldn't know which one of the blocks' content to use.
|
|
|
|
Template Inclusion
|
|
==================
|
|
|
|
You can load another template at a given position using ``{% include %}``.
|
|
Usually it's a better idea to use inheritance but if you for example want to
|
|
load macros, `include` works better than `extends`:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{% include "myhelpers.html" %}
|
|
{{ my_helper("foo") }}
|
|
|
|
If you define a macro called ``my_helper`` in ``myhelpers.html``, you can now
|
|
use it from the template as shown above.
|
|
|
|
Filtering Blocks
|
|
================
|
|
|
|
Sometimes it could be a good idea to filter a complete block of text. For
|
|
example, if you want to escape some html code:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{% filter escape %}
|
|
<html>
|
|
<code>goes here</code>
|
|
</html>
|
|
{% endfilter %}
|
|
|
|
Of course you can chain filters too:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{% filter lower|escape %}
|
|
<B>SOME TEXT</B>
|
|
{% endfilter %}
|
|
|
|
returns ``"<b>some text</b>"``.
|
|
|
|
Defining Variables
|
|
==================
|
|
|
|
You can also define variables in the namespace using the ``{% set %}`` tag:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{% set foo = 'foobar' %}
|
|
{{ foo }}
|
|
|
|
This should ouput ``foobar``.
|
|
|
|
Scopes
|
|
======
|
|
|
|
Jinja has multiple scopes. A scope is something like a new transparent foil on
|
|
a stack of foils. You can only write to the outermost foil but read all of them
|
|
since you can look through them. If you remove the top foil all data on that
|
|
foil disappears. Some tags in Jinja add a new layer to the stack. Currently
|
|
these are `block`, `for`, `macro` and `filter`. This means that variables and
|
|
other elements defined inside a macro, loop or some of the other tags listed
|
|
above will be only available in that block. Here an example:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{% macro angryhello name %}
|
|
{% set angryname = name|upper %}
|
|
Hello {{ name }}. Hello {{ name }}!
|
|
HELLO {{ angryname }}!!!!!!111
|
|
{% endmacro %}
|
|
|
|
The variable ``angryname`` just exists inside the macro, not outside it.
|
|
|
|
Defined macros appear on the context as variables. Because of this, they are
|
|
affected by the scoping too. A macro defined inside of a macro is just available
|
|
in those two macros (the macro itself and the macro it's defined in). For `set`
|
|
and `macro` two additional rules exist: If a macro is defined in an extended
|
|
template but outside of a visible block (thus outside of any block) will be
|
|
available in all blocks below. This allows you to use `include` statements to
|
|
load often used macros at once.
|
|
|
|
Undefined Variables
|
|
===================
|
|
|
|
If you have already worked with python you probably know about the fact that
|
|
undefined variables raise an exception. This is different in Jinja. There is a
|
|
special value called `undefined` that represents values that do not exist.
|
|
|
|
This special variable works complete different from any variables you maybe
|
|
know. If you print it using ``{{ variable }}`` it will not appear because it's
|
|
literally empty. If you try to iterate over it, it will work. But no items
|
|
are returned. Comparing this value to any other value results in `false`.
|
|
Even if you compare it to itself:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{{ undefined == undefined }}
|
|
will return false. Not even undefined is undefined :)
|
|
Use `is defined` / `is not defined`:
|
|
|
|
{{ undefined is not defined }}
|
|
will return true.
|
|
|
|
There are also some additional rules regarding this special value. Any
|
|
mathematical operators (``+``, ``-``, ``*``, ``/``) return the operand
|
|
as result:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{{ undefined + "foo" }}
|
|
returns "foo"
|
|
|
|
{{ undefined - 42 }}
|
|
returns 42. Note: not -42!
|
|
|
|
In any expression `undefined` evaluates to `false`. It has no length, all
|
|
attribute calls return undefined, calling too:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{{ undefined.attribute().attribute_too[42] }}
|
|
still returns `undefined`.
|
|
|
|
Escaping
|
|
========
|
|
|
|
Sometimes you might want to add Jinja syntax elements into the template
|
|
without executing them. In that case you have quite a few possibilities.
|
|
|
|
For small parts this might be a good way:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{{ "{{ foo }} is variable syntax and {% foo %} is block syntax" }}
|
|
|
|
When you have multiple elements you can use the ``raw`` block:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{% raw %}
|
|
Filtering blocks works like this in Jinja:
|
|
{% filter escape %}
|
|
<html>
|
|
<code>goes here</code>
|
|
</html>
|
|
{% endfilter %}
|
|
{% endraw %}
|
|
|
|
Reserved Keywords
|
|
=================
|
|
|
|
Jinja has some keywords you cannot use a variable names. This limitation
|
|
exists to make look coherent. Syntax highlighters won't mess things up and
|
|
you will don't have unexpected output.
|
|
|
|
The following keywords exist and cannot be used as identifiers:
|
|
|
|
`and`, `block`, `cycle`, `elif`, `else`, `endblock`, `endfilter`,
|
|
`endfor`, `endif`, `endmacro`, `endraw`, `endtrans`, `extends`, `filter`,
|
|
`for`, `if`, `in`, `include`, `is`, `macro`, `not`, `or`, `pluralize`,
|
|
`raw`, `recursive`, `set`, `trans`
|
|
|
|
If you want to use such a name you have to prefix or suffix it or use
|
|
alternative names:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{% for macro_ in macros %}
|
|
{{ macro_('foo') }}
|
|
{% endfor %}
|
|
|
|
If future Jinja releases add new keywords those will be "light" keywords which
|
|
means that they won't raise an error for several releases but yield warnings
|
|
on the application side. But it's very unlikely that new keywords will be
|
|
added.
|
|
|
|
Internationalization
|
|
====================
|
|
|
|
If the application is configured for i18n, you can define translatable blocks
|
|
for translators using the `trans` tag or the special underscore function:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{% trans %}
|
|
this is a translatable block
|
|
{% endtrans %}
|
|
|
|
{% trans "This is a translatable string" %}
|
|
|
|
{{ _("This is a translatable string") }}
|
|
|
|
The latter one is useful if you want translatable arguments for filters etc.
|
|
|
|
If you want to have plural forms too, use the `pluralize` block:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{% trans users=users %}
|
|
One user found.
|
|
{% pluralize %}
|
|
{{ users }} users found.
|
|
{% endtrans %}
|
|
|
|
{% trans first=(users|first).username|escape, user=users|length %}
|
|
one user {{ first }} found.
|
|
{% pluralize users %}
|
|
{{ users }} users found, the first one is called {{ first }}.
|
|
{% endtrans %}
|
|
|
|
If you have multiple arguments, the first one is assumed to be the indicator (the
|
|
number that is used to determine the correct singular or plural form. If you
|
|
don't have the indicator variable on position 1 you have to tell the `pluralize`
|
|
tag the correct variable name.
|
|
|
|
Inside translatable blocks you cannot use blocks or expressions (however you can
|
|
still use the ``raw`` block which will work as expected). The variable
|
|
print syntax (``{{ variablename }}``) is the only way to insert the variables
|
|
defined in the ``trans`` header. Filters must be applied in the header.
|
|
|
|
.. admonition:: note
|
|
|
|
Please make sure that you always use pluralize blocks where required.
|
|
Many languages have more complex plural forms than the English language.
|
|
|
|
Never try to workaround that issue by using something like this:
|
|
|
|
.. sourcecode:: jinja
|
|
|
|
{% if count != 1 %}
|
|
{{ count }} users found.
|
|
{% else %}
|
|
one user found.
|
|
{% endif %}
|
|
|
|
.. _slicing chapter: http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice
|
|
.. _range function: http://docs.python.org/tut/node6.html#SECTION006300000000000000000
|