This covers the default settings. The application developer might have
changed the syntax from ``{% foo %}`` to ``<% foo %>`` or something similar.
-There are two kinds of delimiers. ``{% ... %}`` and ``{{ ... }}``. The first
+There are two kinds of delimiters. ``{% ... %}`` and ``{{ ... }}``. The first
one is used to execute statements such as for-loops or assign values, the
latter prints the result of the expression to the template.
Filters
-------
-Variables can by modified by **filters**. Filters are separated from the
+Variables can be modified by **filters**. Filters are separated from the
variable by a pipe symbol (``|``) and may have optional arguments in
parentheses. Multiple filters can be chained. The output of one filter is
applied to the next.
Whitespace Control
------------------
-In the default configuration whitespace is not further modified by the
-template engine, so each whitespace (spaces, tabs, newlines etc.) is returned
-unchanged. If the application configures Jinja to `trim_blocks` the first
-newline after a a template tag is removed automatically (like in PHP).
+In the default configuration, a single trailing newline is stripped if
+present, and whitespace is not further modified by the template engine. Each
+whitespace (spaces, tabs, newlines etc.) is returned unchanged. If the
+application configures Jinja to `trim_blocks` the first newline after a a
+template tag is removed automatically (like in PHP).
But you can also strip whitespace in templates by hand. If you put an minus
sign (``-``) to the start or end of an block (for example a for tag), a
{% for item in seq -%}
{{ item }}
{%- endfor %}
-
+
This will yield all elements without whitespace between them. If `seq` was
a list of numbers from ``1`` to ``9`` the output would be ``123456789``.
The filename of the template depends on the template loader. For example the
:class:`FileSystemLoader` allows you to access other templates by giving the
-filename. You can access templates in subdirectories with an slash::
+filename. You can access templates in subdirectories with a slash::
{% extends "layout/default.html" %}
When overriding a block the `scoped` modifier does not have to be provided.
+Template Objects
+~~~~~~~~~~~~~~~~
+
+.. versionchanged:: 2.4
+
+If a template object was passed to the template context you can
+extend from that object as well. Assuming the calling code passes
+a layout template as `layout_template` to the environment, this
+code works::
+
+ {% extends layout_template %}
+
+Previously the `layout_template` variable had to be a string with
+the layout template's filename for this to work.
+
+
HTML Escaping
-------------
{% endfor %}
</ul>
-Inside of a for loop block you can access some special variables:
+As variables in templates retain their object properties, it is possible to
+iterate over containers like `dict`::
+
+ <dl>
+ {% for key, value in my_dict.iteritems() %}
+ <dt>{{ key|e }}</dt>
+ <dd>{{ value|e }}</dd>
+ {% endfor %}
+ </dl>
+
+Note however that dictionaries usually are unordered so you might want to
+either pass it as a sorted list to the template or use the `dictsort`
+filter.
+
+Inside of a for-loop block you can access some special variables:
+-----------------------+---------------------------------------------------+
| Variable | Description |
<li class="{{ loop.cycle('odd', 'even') }}">{{ row }}</li>
{% endfor %}
-With Jinja 2.1 an extra `cycle` helper exists that allows loop-unbound
+Since Jinja 2.1 an extra `cycle` helper exists that allows loop-unbound
cycling. For more information have a look at the :ref:`builtin-globals`.
.. _loop-filtering:
{% include ['page_detailed.html', 'page.html'] %}
{% include ['special_sidebar.html', 'sidebar.html'] ignore missing %}
+.. versionchanged:: 2.4
+ If a template object was passed to the template context you can
+ include that object using `include`.
+
.. _import:
Import
different templates and get imported from there. This works similar to the
import statements in Python. It's important to know that imports are cached
and imported templates don't have access to the current template variables,
-just the globals by defualt. For more details about context behavior of
+just the globals by default. For more details about context behavior of
imports and includes see :ref:`import-visibility`.
There are two ways to import templates. You can import the complete template
Macros and variables starting with one ore more underscores are private and
cannot be imported.
+.. versionchanged:: 2.4
+ If a template object was passed to the template context you can
+ import from that object.
+
.. _import-visibility:
{% include "render_box.html" %}
{% endfor %}
- The included template ``render_box.html`` is not able to access
- `box` in Jinja 2.0, but in Jinja 2.1.
+ The included template ``render_box.html`` is *not* able to access
+ `box` in Jinja 2.0. As of Jinja 2.1 ``render_box.html`` *is* able
+ to do so.
.. _expressions:
//
Divide two numbers and return the truncated integer result.
- ``{{ 20 / 7 }}`` is ``2``.
+ ``{{ 20 // 7 }}`` is ``2``.
%
Calculate the remainder of an integer division. ``{{ 11 % 7 }}`` is ``4``.
Raise the left operand to the power of the right operand. ``{{ 2**3 }}``
would return ``8``.
+Comparisons
+~~~~~~~~~~~
+
+==
+ Compares two objects for equality.
+
+!=
+ Compares two objects for inequality.
+
+>
+ `true` if the left hand side is greater than the right hand side.
+
+>=
+ `true` if the left hand side is greater or equal to the right hand side.
+
+<
+ `true` if the left hand side is lower than the right hand side.
+
+<=
+ `true` if the left hand side is lower or equal to the right hand side.
+
Logic
~~~~~
.. attribute:: 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 calld, except
+ 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::
To use placeholders you can use the `format` filter::
{{ _('Hello %(user)s!')|format(user=user.username) }}
- or
- {{ _('Hello %s')|format(user.username) }}
For multiple placeholders always use keyword arguments to `format` as other
languages may not use the words in the same order.
+.. versionchanged:: 2.5
+
+If newstyle gettext calls are activated (:ref:`newstyle-gettext`), using
+placeholders is a lot easier:
+
+.. sourcecode:: html+jinja
+
+ {{ 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 application enables the :ref:`loopcontrols-extension` it's possible to
use `break` and `continue` in loops. When `break` is reached, the loop is
-terminated, if `continue` is eached the processing is stopped and continues
+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 >= 10 %}{% break %}{% endif %}
{%- endfor %}
+
+
+With Statement
+~~~~~~~~~~~~~~
+
+.. versionadded:: 2.3
+
+If the application enables the :ref:`with-extension` 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-overrides:
+
+Autoescape Extension
+--------------------
+
+.. versionadded:: 2.4
+
+If the application enables the :ref:`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.
projects / jinja2.git / blobdiff