docs/src/builtins.txt

===================================
Filters, Tests and Helper Functions
===================================

This part of the documentation lists the filter-, test- and helper functions
you can use in templates.


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

    *Jinja 1.0 and 1.1 notice*

    The filter operator has a pretty low priority in Jinja 1.0 and 1.1. If you
    want to add fitered values you have to put them into parentheses. The same
    applies if you want to access attributes or return values:

    .. sourcecode:: jinja

        correct:
            {{ (foo|filter) + (bar|filter) }}
        wrong:
            {{ foo|filter + bar|filter }}

        correct:
            {{ (foo|filter).attribute }}
        wrong:
            {{ foo|filter.attribute }}

    This changed in Jinja 1.2, from that version one the filter operator has
    the highest priority so you can do ``foo|filter + bar|filter``.

*new in Jinja 1.1*:

Because the application can provide additional filters you can get a documentation
of all the provided filters by calling ``debug.filters()``:

.. sourcecode:: jinja

    {{ debug.filters() }}
        -> returns a plain text representation of all the filters

    {{ debug.filters(False) }}
        -> same as above but without the builtin ones.

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]]

*new in Jinja 1.1*:

Because the application can provide additional tests you can get a documentation
of all the provided tests by calling ``debug.tests()``:

.. sourcecode:: jinja

    {{ debug.tests() }}
        -> returns a plain text representation of all the tests

    {{ debug.tests(False) }}
        -> same as above but without the builtin ones.

*new in Jinja 1.2*:

If a test function expects one or no argument you can leave out the parentheses.
Previously this was only possible for text functions without arguments:

.. sourcecode:: jinja

    {{ foo is matching @/\s+/ }}
        is the same as
    {{ foo is matching(@/\s+/) }}


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.

`lipsum`

    Generate some paragraphs of random text:

    .. sourcecode:: jinja

        {{ lipsum(5) }}
            five html paragraphs

        {{ lipsum(2, False) }}
            two ascii only paragraphs

    Per default a paragraph is between 20 and 100 words long. You can
    override this default with the third and fourth parameter:

    .. sourcecode:: jinja

        {{ lipsum(10, True, 50, 200) }}
            generate 10 HTML paragraphs between 50 and 200 words.

    *new in Jinja 1.1*

`watchchanges`

    Jinja does not provide an django like ``{% ifchanged %}`` tag. As
    replacement for this tag there is a special function in the namespace
    called `watchchanges`.

    You can use it like this:

    .. sourcecode:: html+jinja

        {% for changed, article in watchchanges(articles, 'date', 'day') %}
            {% if changed %}<h3>{{ articles.date.day }}</h3>{% endif %}
            <h4>{{ article.title|e }}</h4>
            <p>{{ article.body|e }}</p>
        {% endif %}

    For each iteration `watchchanges` will check the given attribute. If it
    changed to the former iteration the first yielded item (in this example
    it's called `changed`) will be `true`, else `false`.

    In this example `articles` is a list of articles for the template with
    an attribute called `date.day` which represents the current day. To only
    add a new day headline if the day has changed `watchchanges` is now told
    to check `articles.date.days`.

    If you want to observe more than one attribute you can provide pairs:

    .. sourcecode:: html+jinja

        {% for changed, item in watchchanges(foo, ('a', 'b'), ('a', 'c')) %}
            ...
        {% endfor %}

    Note that if you want to watch two first level attributes you have to
    either use the list syntax `[]` or add a colon:

    .. sourcecode:: html+jinja

        {% for changed, item in watchchanges(foo, ['a'], ('b',)) %}
            ...
        {% endfor %}

    otherwise Jinja cannot differ between a pair of parentheses to group
    expressions or the sequence syntax.

    If you don't provide any arguments the value of the variable itself
    is checked.

    *new in Jinja 1.1*

`rendertemplate`

    Loads and renders a template with a copy of the current context. This works
    in many situations like the ``{% include %}`` tag, just that it does not
    include a template and merges it into the template structure but renders
    it completely independent and returns the rendered data as string.

    *new in Jinja 1.1*


Global Constants
================

Jinja provides some special variables which cannot be overridden in templates.
Those are not affected by the variable lookup:

    `_`, `true`, `false`, `none`, `undefined`

You cannot use those names for your own variables or macros. It's however no
problem to have blocks with that name.

**Notice** due to a bug in Jinja 1.0 it was possible to override `_`, `true`,
`false`, `none` and `undefined` from the template by either using `{% set %}`
or in a for loop. While overriding `true`, `false` etc just caused nothing
overriding the translation marker `_` would crash the translation interface.
If you want to use `_` for unpacking in for loops (eg. skipping items) you
have to give it a proper name:

.. sourcecode:: jinja

    {% for key, ignore in mydict|dictsort %}
        {{ key|e }}
    {% endfor %}


.. _range function: http://docs.python.org/tut/node6.html#SECTION006300000000000000000