| Template Designer Documentation |
| =============================== |
| |
| .. highlight:: html+jinja |
| |
| This document describes the syntax and semantics of the template engine and |
| will be most useful as reference to those creating Jinja templates. As the |
| template engine is very flexible the configuration from the application might |
| be slightly different from here in terms of delimiters and behavior of |
| undefined values. |
| |
| |
| Synopsis |
| -------- |
| |
| A template is simply a text file. It can generate any text-based format |
| (HTML, XML, CSV, LaTeX, etc.). It doesn't have a specific extension, |
| ``.html`` or ``.xml`` are just fine. |
| |
| A template contains **variables** or **expressions**, which get replaced with |
| values when the template is evaluated, and tags, which control the logic of |
| the template. The template syntax is heavily inspired by Django and Python. |
| |
| Below is a minimal template that illustrates a few basics. We will cover |
| the details later in that document:: |
| |
| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> |
| <html lang="en"> |
| <head> |
| <title>My Webpage</title> |
| </head> |
| <body> |
| <ul id="navigation"> |
| {% for item in navigation %} |
| <li><a href="{{ item.href }}">{{ item.caption }}</a></li> |
| {% endfor %} |
| </ul> |
| |
| <h1>My Webpage</h1> |
| {{ a_variable }} |
| </body> |
| </html> |
| |
| 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 |
| one is used to execute statements such as for-loops or assign values, the |
| latter prints the result of the expression to the template. |
| |
| .. _variables: |
| |
| Variables |
| --------- |
| |
| The application passes variables to the templates you can mess around in the |
| template. Variables may have attributes or elements on them you can access |
| too. How a variable looks like, heavily depends on the application providing |
| those. |
| |
| You can use a dot (``.``) to access attributes of a variable, alternative the |
| so-called "subscribe" syntax (``[]``) can be used. The following lines do |
| the same:: |
| |
| {{ foo.bar }} |
| {{ foo['bar'] }} |
| |
| It's important to know that the curly braces are *not* part of the variable |
| but the print statement. If you access variables inside tags don't put the |
| braces around. |
| |
| If a variable or attribute does not exist you will get back an undefined |
| value. What you can do with that kind of value depends on the application |
| configuration, the default behavior is that it evaluates to an empty string |
| if printed and that you can iterate over it, but every other operation fails. |
| |
| .. _filters: |
| |
| Filters |
| ------- |
| |
| Variables can by 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. |
| |
| ``{{ name|striptags|title }}`` for example will remove all HTML Tags from the |
| `name` and title-cases it. Filters that accept arguments have parentheses |
| around the arguments, like a function call. This example will join a list |
| by spaces: ``{{ list|join(', ') }}``. |
| |
| The :ref:`builtin-filters` below describes all the builtin filters. |
| |
| .. _tests: |
| |
| Tests |
| ----- |
| |
| Beside filters there are also so called "tests" available. Tests can be used |
| to test a variable against a common expression. To test a variable or |
| expression you add `is` plus the name of the test after the variable. For |
| example to find out if a variable is defined you can do ``name is defined`` |
| which will then return true or false depending on if `name` is defined. |
| |
| Tests can accept arguments too. If the test only takes one argument you can |
| leave out the parentheses to group them. For example the following two |
| expressions do the same:: |
| |
| {% if loop.index is divisibleby 3 %} |
| {% if loop.index is divisibleby(3) %} |
| |
| The :ref:`builtin-tests` below describes all the builtin tests. |
| |
| |
| Comments |
| -------- |
| |
| To comment-out part of a line in a template, use the comment syntax which is |
| by default set to ``{# ... #}``. This is useful to comment out parts of the |
| template for debugging or to add information for other template designers or |
| yourself:: |
| |
| {# note: disabled template because we no longer user this |
| {% for user in users %} |
| ... |
| {% endfor %} |
| #} |
| |
| .. _template-inheritance: |
| |
| Template 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:: |
| |
| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> |
| <html lang="en"> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| {% block head %} |
| <link rel="stylesheet" href="style.css" /> |
| <title>{% block title %}{% endblock %} - My Webpage</title> |
| {% endblock %} |
| </head> |
| <body> |
| <div id="content">{% block content %}{% endblock %}</div> |
| <div id="footer"> |
| {% block footer %} |
| © Copyright 2008 by <a href="http://domain.invalid/">you</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:: |
| |
| {% extends "base.html" %} |
| {% block title %}Index{% endblock %} |
| {% block head %} |
| {{ super() }} |
| <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 extends tag should be the |
| first tag in the template. Everything before it is printed out normally and |
| may cause confusion. |
| |
| 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:: |
| |
| {% extends "layout/default.html" %} |
| |
| But this behavior can depend on the application embedding Jinja. Note that |
| since the child template doesn't define the ``footer`` block, the value from |
| the parent template is used instead. |
| |
| 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. |
| |
| If you want to print a block multiple times you can however use the special |
| `self` variable and call the block with that name:: |
| |
| <title>{% block title %}{% endblock %}</title> |
| <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 |
| ~~~~~~~~~~~~ |
| |
| It's possible to render the contents of the parent block by calling `super`. |
| This gives back the results of the parent block:: |
| |
| {% block sidebar %} |
| <h3>Table Of Contents</h3> |
| ... |
| {{ super() }} |
| {% endblock %} |
| |
| |
| HTML Escaping |
| ------------- |
| |
| When generating HTML from templates, there's always a risk that a variable will |
| include characters that affect the resulting HTML. There are two approaches: |
| manually escaping each variable or automatically escaping everything by default. |
| |
| Jinja supports both, but what is used depends on the application configuration. |
| The default configuaration is no automatic escaping for various reasons: |
| |
| - escaping everything except of safe values will also mean that Jinja is |
| escaping variables known to not include HTML such as numbers which is |
| a huge performance hit. |
| |
| - The information about the safety of a variable is very fragile. It could |
| happen that by coercing safe and unsafe values the return value is double |
| escaped HTML. |
| |
| Working with Manual Escaping |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| If manual escaping is enabled it's **your** responsibility to escape |
| variables if needed. What to escape? If you have a variable that *may* |
| include any of the following chars (``>``, ``<``, ``&``, or ``"``) you |
| **have to** escape it unless the variable contains well-formed and trusted |
| HTML. Escaping works by piping the variable through the ``|e`` filter: |
| ``{{ user.username|e }}``. |
| |
| Working with Automatic Escaping |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| When automatic escaping is enabled everything is escaped by default except |
| for values explicitly marked as safe. Those can either be marked by the |
| application or in the template by using the `|safe` filter. The main |
| problem with this approach is that Python itself doesn't have the concept |
| of tainted values so the information if a value is safe or unsafe can get |
| lost. If the information is lost escaping will take place which means that |
| you could end up with double escaped contents. |
| |
| Double escaping is easy to avoid however, just rely on the tools Jinja2 |
| provides and don't use builtin Python constructs such as the string modulo |
| operator. |
| |
| Functions returning template data (macros, `super`, `self.BLOCKNAME`) return |
| safe markup always. |
| |
| String literals in templates with automatic escaping are considered unsafe |
| too. The reason for this is that the safe string is an extension to Python |
| and not every library will work properly with it. |
| |
| |
| List of Control Structures |
| -------------------------- |
| |
| A control structure refers to all those things that control the flow of a |
| program - conditionals (i.e. if/elif/else), for-loops, as well as things like |
| macros and blocks. Control structures appear inside ``{% ... %}`` blocks |
| in the default syntax. |
| |
| For |
| ~~~ |
| |
| Loop over each item in a sequence. For example, to display a list of users |
| provided in a variable called `users`:: |
| |
| <h1>Members</h1> |
| <ul> |
| {% for user in users %} |
| <li>{{ user.username|e }}</li> |
| {% endfor %} |
| </ul> |
| |
| Inside of a for loop block you can access some special variables: |
| |
| +-----------------------+---------------------------------------------------+ |
| | Variable | Description | |
| +=======================+===================================================+ |
| | `loop.index` | The current iteration of the loop. (1 indexed) | |
| +-----------------------+---------------------------------------------------+ |
| | `loop.index0` | The current iteration of the loop. (0 indexed) | |
| +-----------------------+---------------------------------------------------+ |
| | `loop.revindex` | The number of iterations from the end of the loop | |
| | | (1 indexed) | |
| +-----------------------+---------------------------------------------------+ |
| | `loop.revindex0` | The number of iterations from the end of the loop | |
| | | (0 indexed) | |
| +-----------------------+---------------------------------------------------+ |
| | `loop.first` | True if first iteration. | |
| +-----------------------+---------------------------------------------------+ |
| | `loop.last` | True if last iteration. | |
| +-----------------------+---------------------------------------------------+ |
| | `loop.length` | The number of items in the sequence. | |
| +-----------------------+---------------------------------------------------+ |
| | `loop.cycle` | A helper function to cycle between a list of | |
| | | sequences. See the explanation below. | |
| +-----------------------+---------------------------------------------------+ |
| |
| Within a for-loop, it's possible to cycle among a list of strings/variables |
| each time through the loop by using the special `loop.cycle` helper:: |
| |
| {% for row in rows %} |
| <li class="{{ loop.cycle('odd', 'even') }}">{{ row }}</li> |
| {% endfor %} |
| |
| .. _loop-filtering: |
| |
| Unlike in Python it's not possible to `break` or `continue` in a loop. You |
| can however filter the sequence during iteration which allows you to skip |
| items. The following example skips all the users which are hidden:: |
| |
| {% for user in users if not user.hidden %} |
| <li>{{ user.username|e }}</li> |
| {% endfor %} |
| |
| The advantage is that the special `loop` variable will count correctly thus |
| not counting the users not iterated over. |
| |
| If no iteration took place because the sequence was empty or the filtering |
| removed all the items from the sequence you can render a replacement block |
| by using `else`:: |
| |
| <ul> |
| {% for user in users %} |
| <li>{{ user.username|e }}</li> |
| {% else %} |
| <li><em>no users found</em></li> |
| {% endif %} |
| </ul> |
| |
| |
| If |
| ~~ |
| |
| The `if` statement in Jinja is comparable with the if statements of Python. |
| In the simplest form you can use it to test if a variable is defined, not |
| empty or not false:: |
| |
| {% if users %} |
| <ul> |
| {% for user in users %} |
| <li>{{ user.username|e }}</li> |
| {% endfor %} |
| </ul> |
| {% endif %} |
| |
| For multiple branches `elif` and `else` can be used like in Python. You can |
| use more complex :ref:`expressions` there too:: |
| |
| {% if kenny.sick %} |
| Kenny is sick. |
| {% elif kenny.dead %} |
| You killed Kenny! You bastard!!! |
| {% else %} |
| Kenny looks okay --- so far |
| {% endif %} |
| |
| If can also be used as :ref:`inline expression <if-expression>` and for |
| :ref:`loop filtering <loop-filtering>`. |
| |
| |
| Macros |
| ~~~~~~ |
| |
| Macros are comparable with functions in regular programming languages. They |
| are useful to put often used idioms into reusable functions to not repeat |
| yourself. |
| |
| Macros can be defined in helper templates which then are :ref:`imported |
| <import>` or directly in the template where they are used. There is one big |
| difference between those two possibilities. A macro that is defined in the |
| template where it's also used has access to the context passed to the template. |
| A macro defined in another template and then imported can only access variables |
| defined there or in the global context. |
| |
| Here a small example of a macro that renders a form element:: |
| |
| {% macro input(name, value='', type='text', size=20) -%} |
| <input type="{{ type }}" name="{{ name }}" value="{{ |
| value|e }}" size="{{ size }}"> |
| {%- endmacro %} |
| |
| The macro can then be called like a function in the namespace:: |
| |
| <p>{{ input('username') }}</p> |
| <p>{{ input('password', type='password') }}</p> |
| |
| If the macro was defined in a different template you have to |
| :ref:`import <import>` it first. |
| |
| Inside macros you have access to three special variables: |
| |
| `varargs` |
| If more positional arguments are passed to the macro than accepted by the |
| macro they end up in the special `varargs` variable as list of values. |
| |
| `kwargs` |
| Like `varargs` but for keyword arguments. All unconsumed keyword |
| arguments are stored in this special variable. |
| |
| `caller` |
| If the macro was called from a :ref:`call<call>` tag the caller is stored |
| in this variable as macro which can be called. |
| |
| Macros also expose some of their internal details. The following attributes |
| are available on a macro object: |
| |
| `name` |
| The name of the macro. ``{{ input.name }}`` will print ``input``. |
| |
| `arguments` |
| A tuple of the names of arguments the macro accepts. |
| |
| `defaults` |
| A tuple of default values. |
| |
| `catch_kwargs` |
| This is `true` if the macro accepts extra keyword arguments (ie: accesses |
| the special `kwargs` variable). |
| |
| `catch_varargs` |
| This is `true` if the macro accepts extra positional arguments (ie: |
| accesses the special `varargs` variable). |
| |
| `caller` |
| This is `true` if the macro accesses the special `caller` variable and may |
| be called from a :ref:`call<call>` tag. |
| |
| |
| .. _call: |
| |
| Call |
| ~~~~ |
| |
| In some cases it can be useful to pass a macro to another macro. For this |
| purpose you can use the special `call` block. The following example shows |
| a macro that takes advantage of the call functionality and how it can be |
| used:: |
| |
| {% macro render_dialog(title, class='dialog') -%} |
| <div class="{{ class }}"> |
| <h2>{{ title }}</h2> |
| <div class="contents"> |
| {{ caller() }} |
| </div> |
| </div> |
| {%- endmacro %} |
| |
| {% call render_dialog('Hello World') %} |
| This is a simple dialog rendered by using a macro and |
| a call block. |
| {% endcall %} |
| |
| It's also possible to pass arguments back to the call block. This makes it |
| useful as replacement for loops. It is however not possible to call a |
| call block with another call block. |
| |
| Here an example of how a call block can be used with arguments:: |
| |
| {% macro dump_users(users) -%} |
| <ul> |
| {%- for user in users %} |
| <li><p>{{ user.username|e }}</p>{{ caller(user) }}</li> |
| {%- endfor %} |
| </ul> |
| {%- endmacro %} |
| |
| {% call(user) dump_users(list_of_user) %} |
| <dl> |
| <dl>Realname</dl> |
| <dd>{{ user.realname|e }}</dd> |
| <dl>Description</dl> |
| <dd>{{ user.description }}</dd> |
| </dl> |
| {% endcall %} |
| |
| |
| Assignments |
| ~~~~~~~~~~~ |
| |
| Inside code blocks you can also assign values to variables. Assignments at |
| top level (outside of blocks, macros or loops) are exported from the template |
| like top level macros and can be imported by other templates. |
| |
| Assignments are just written in code blocks like any other statement just |
| without explicit keyword:: |
| |
| {% navigation = [('index.html', 'Index'), ('about.html', 'About')] %} |
| |
| |
| Extends |
| ~~~~~~~ |
| |
| 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. |
| |
| |
| Block |
| ~~~~~ |
| |
| Blocks are used for inheritance and act as placeholders and replacements |
| at the same time. They are documented in detail as part of the section |
| about :ref:`template-inheritance`. |
| |
| |
| Include |
| ~~~~~~~ |
| |
| The `include` statement is useful to include a template and return the |
| rendered contents of that file into the current namespace:: |
| |
| {% include 'header.html' %} |
| Body |
| {% include 'footer.html' %} |
| |
| Included templates have access to the current template variables minus local |
| modifications. |
| |
| .. _import: |
| |
| Import |
| ~~~~~~ |
| |
| Jinja2 supports putting often used code into macros. These macros can go into |
| 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. |
| |
| There are two ways to import templates. You can import the complete template |
| into a variable or request specific macros / exported variables from it. |
| |
| Imagine we have a helper module that renders forms (called `forms.html`):: |
| |
| {% macro input(name, value='', type='text') -%} |
| <input type="{{ type }}" value="{{ value|e }}" name="{{ name }}"> |
| {%- endmacro %} |
| |
| {%- macro textarea(name, value='', rows=10, cols=40) -%} |
| <textarea name="{{ name }}" rows="{{ rows }}" cols="{{ cols |
| }}">{{ value|e }}</textarea> |
| {%- endmacro %} |
| |
| The easiest and most flexible is importing the whole module into a variable. |
| That way you can access the attributes:: |
| |
| {% import 'forms.html' as forms %} |
| <dl> |
| <dt>Username</dt> |
| <dd>{{ forms.input('username') }}</dd> |
| <dt>Password</dt> |
| <dd>{{ forms.input('password', type='password') }}</dd> |
| </dl> |
| <p>{{ forms.textarea('comment') }}</p> |
| |
| |
| Alternatively you can import names from the template into the current |
| namespace:: |
| |
| {% from 'forms.html' import input as input_field, textarea %} |
| <dl> |
| <dt>Username</dt> |
| <dd>{{ input_field('username') }}</dd> |
| <dt>Password</dt> |
| <dd>{{ input_field('password', type='password') }}</dd> |
| </dl> |
| <p>{{ textarea('comment') }}</p> |
| |
| |
| .. _expressions: |
| |
| Expressions |
| ----------- |
| |
| Jinja allows basic expressions everywhere. These work very similar to regular |
| Python and even if you're not working with Python you should feel comfortable |
| with it. |
| |
| Literals |
| ~~~~~~~~ |
| |
| The simplest form of expressions are literals. Literals are representations |
| for Python objects such as strings and numbers. The following literals exist: |
| |
| "Hello World": |
| Everything between two double or single quotes is a string. They are |
| useful whenever you need a string in the template (for example as |
| arguments to function calls, filters or just to extend or include a |
| template). |
| |
| 42 / 42.23: |
| Integers and floating point numbers are created by just writing the |
| number down. If a dot is present the number is a float, otherwise an |
| integer. Keep in mind that for Python ``42`` and ``42.0`` is something |
| different. |
| |
| ['list', 'of', 'objects']: |
| Everything between two brackets is a list. Lists are useful to store |
| sequential data in or to iterate over them. For example you can easily |
| create a list of links using lists and tuples with a for loop:: |
| |
| <ul> |
| {% for href, caption in [('index.html', 'Index'), ('about.html', 'About'), |
| ('downloads.html', 'Downloads')] %} |
| <li><a href="{{ href }}">{{ caption }}</a></li> |
| {% endfor %} |
| </ul> |
| |
| ('tuple', 'of', 'values'): |
| Tuples are like lists, just that you can't modify them. If the tuple |
| only has one item you have to end it with a comma. Tuples are usually |
| used to represent items of two or more elements. See the example above |
| for more details. |
| |
| {'dict': 'of', 'key': 'and', 'value': 'pairs'}: |
| A dict in Python is a structure that combines keys and values. Keys must |
| be unique and always have exactly one value. Dicts are rarely used in |
| templates, they are useful in some rare cases such as the :func:`xmlattr` |
| filter. |
| |
| true / false: |
| true is always true and false is always false. Keep in mind that those |
| literals are lowercase! |
| |
| Math |
| ~~~~ |
| |
| Jinja allows you to calculate with values. This is rarely useful in templates |
| but exists for completeness sake. The following operators are supported: |
| |
| \+ |
| Adds two objects with each other. Usually numbers but if both objects are |
| strings or lists you can concatenate them this way. This however is not |
| the preferred way to concatenate strings! For string concatenation have |
| a look at the ``~`` operator. ``{{ 1 + 1 }}`` is ``2``. |
| |
| \- |
| Substract two numbers from each other. ``{{ 3 - 2 }}`` is ``1``. |
| |
| / |
| Divide two numbers. The return value will be a floating point number. |
| ``{{ 1 / 2 }}`` is ``{{ 0.5 }}``. |
| |
| // |
| Divide two numbers and return the truncated integer result. |
| ``{{ 20 / 7 }}`` is ``2``. |
| |
| % |
| Calculate the remainder of an integer division between the left and right |
| operand. ``{{ 11 % 7 }}`` is ``4``. |
| |
| \* |
| Multiply the left operand with the right one. ``{{ 2 * 2 }}`` would |
| return ``4``. This can also be used to repeat string multiple times. |
| ``{{ '=' * 80 }}`` would print a bar of 80 equal signs. |
| |
| \** |
| Raise the left operand to the power of the right operand. ``{{ 2**3 }}`` |
| would return ``8``. |
| |
| Logic |
| ~~~~~ |
| |
| For `if` statements / `for` filtering or `if` expressions it can be useful to |
| combine group multiple expressions: |
| |
| 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). |
| |
| (expr) |
| group an expression. |
| |
| 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).`` |
| |
| |
| Other Operators |
| ~~~~~~~~~~~~~~~ |
| |
| The following operators are very useful but don't fit into any of the other |
| two categories: |
| |
| in |
| Perform sequence / mapping containment test. Returns true if the left |
| operand is contained in the right. ``{{ 1 in [1, 2, 3] }}`` would for |
| example return true. |
| |
| is |
| Performs a :ref:`test <tests>`. |
| |
| \| |
| Applies a :ref:`filter <filters>`. |
| |
| ~ |
| Converts all operands into strings and concatenates them. |
| ``{{ "Hello " ~ name ~ "!" }}`` would return (assuming `name` is |
| ``'John'``) ``Hello John!``. |
| |
| () |
| Call a callable: ``{{ post.render() }}``. Inside of the parentheses you |
| can use arguments and keyword arguments like in python: |
| ``{{ post.render(user, full=true) }}``. |
| |
| . / [] |
| Get an attribute of an object. (See :ref:`variables`) |
| |
| |
| .. _if-expression: |
| |
| If Expression |
| ~~~~~~~~~~~~~ |
| |
| It is also possible to use inline `if` expressions. These are useful in some |
| situations. For example you can use this to extend from one template if a |
| variable is defined, otherwise from the default layout template:: |
| |
| {% extends layout_template if layout_template is defined else 'master.html' %} |
| |
| The general syntax is ``<do something> if <something is true> else <do |
| something else>``. |
| |
| |
| .. _builtin-filters: |
| |
| List of Builtin Filters |
| ----------------------- |
| |
| .. jinjafilters:: |
| |
| |
| .. _builtin-tests: |
| |
| List of Builtin Tests |
| --------------------- |
| |
| .. jinjatests:: |
| |
| |
| List of Global Functions |
| ------------------------ |
| |
| The following functions are available in the global scope by default: |
| |
| .. function:: 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> |
| |
| .. function:: 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. |