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.
{% 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``.
<h1>{{ self.title() }}</h1>
{% block body %}{% endblock %}
-Unlike Python Jinja does not support multiple inheritance. So you can only have
-one extends tag called per rendering.
-
Super Blocks
~~~~~~~~~~~~
<li>{% block loop_item scoped %}{{ item }}{% endblock %}</li>
{% endfor %}
- When overriding a block the `scoped` modifier does not have to be provided.
+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
<li>{{ user.username|e }}</li>
{% else %}
<li><em>no users found</em></li>
- {% endif %}
+ {% endfor %}
</ul>
It is also possible to use loops recursively. This is useful if you are
The `extends` tag can be used to extend a template from another one. You
can have multiple of them in a file but only one of them may be executed
-at the time. There is no support for multiple inheritance. See the section
-about :ref:`template-inheritance` above.
+at the time. See the section about :ref:`template-inheritance` above.
Block
{% include "sidebar.html" ignore missing with context %}
{% include "sidebar.html" ignore missing without context %}
+.. versionadded:: 2.2
+
+You can also provide a list of templates that are checked for existence
+before inclusion. The first template that exists will be included. If
+`ignore missing` is given, it will fall back to rendering nothing if
+none of the templates exist, otherwise it will raise an exception.
+
+Example::
+
+ {% 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
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=', ')
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 recieves
+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