Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 1367 lines (979 sloc) 44.268 kb
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
1 Template Designer Documentation
2 ===============================
3
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
4 .. highlight:: html+jinja
5
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
6 This document describes the syntax and semantics of the template engine and
7 will be most useful as reference to those creating Jinja templates. As the
8 template engine is very flexible the configuration from the application might
9 be slightly different from here in terms of delimiters and behavior of
10 undefined values.
11
12
13 Synopsis
14 --------
15
16 A template is simply a text file. It can generate any text-based format
17 (HTML, XML, CSV, LaTeX, etc.). It doesn't have a specific extension,
18 ``.html`` or ``.xml`` are just fine.
19
20 A template contains **variables** or **expressions**, which get replaced with
21 values when the template is evaluated, and tags, which control the logic of
22 the template. The template syntax is heavily inspired by Django and Python.
23
24 Below is a minimal template that illustrates a few basics. We will cover
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
25 the details later in that document::
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
26
27 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
28 <html lang="en">
29 <head>
30 <title>My Webpage</title>
31 </head>
32 <body>
33 <ul id="navigation">
34 {% for item in navigation %}
35 <li><a href="{{ item.href }}">{{ item.caption }}</a></li>
36 {% endfor %}
37 </ul>
38
39 <h1>My Webpage</h1>
40 {{ a_variable }}
41 </body>
42 </html>
43
44 This covers the default settings. The application developer might have
45 changed the syntax from ``{% foo %}`` to ``<% foo %>`` or something similar.
46
2004449 @andymckay fix typo
andymckay authored
47 There are two kinds of delimiters. ``{% ... %}`` and ``{{ ... }}``. The first
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
48 one is used to execute statements such as for-loops or assign values, the
49 latter prints the result of the expression to the template.
50
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
51 .. _variables:
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
52
53 Variables
54 ---------
55
56 The application passes variables to the templates you can mess around in the
57 template. Variables may have attributes or elements on them you can access
58 too. How a variable looks like, heavily depends on the application providing
59 those.
60
61 You can use a dot (``.``) to access attributes of a variable, alternative the
b938877 @mitsuhiko Changed all sentences with occurrences of subscribing to a similar sente...
authored
62 so-called "subscript" syntax (``[]``) can be used. The following lines do
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
63 the same::
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
64
65 {{ foo.bar }}
66 {{ foo['bar'] }}
67
68 It's important to know that the curly braces are *not* part of the variable
69 but the print statement. If you access variables inside tags don't put the
70 braces around.
71
72 If a variable or attribute does not exist you will get back an undefined
73 value. What you can do with that kind of value depends on the application
74 configuration, the default behavior is that it evaluates to an empty string
75 if printed and that you can iterate over it, but every other operation fails.
76
b938877 @mitsuhiko Changed all sentences with occurrences of subscribing to a similar sente...
authored
77 .. _notes-on-subscriptions:
6dc6f29 @mitsuhiko Improved attribute and item lookup by allowing template designers to exp...
authored
78
79 .. admonition:: Implementation
80
b938877 @mitsuhiko Changed all sentences with occurrences of subscribing to a similar sente...
authored
81 For convenience sake ``foo.bar`` in Jinja2 does the following things on
82 the Python layer:
6dc6f29 @mitsuhiko Improved attribute and item lookup by allowing template designers to exp...
authored
83
84 - check if there is an attribute called `bar` on `foo`.
85 - if there is not, check if there is an item ``'bar'`` in `foo`.
86 - if there is not, return an undefined object.
87
88 ``foo['bar']`` on the other hand works mostly the same with the a small
89 difference in the order:
90
91 - check if there is an item ``'bar'`` in `foo`.
92 - if there is not, check if there is an attribute called `bar` on `foo`.
93 - if there is not, return an undefined object.
94
95 This is important if an object has an item or attribute with the same
96 name. Additionally there is the :func:`attr` filter that just looks up
97 attributes.
98
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
99 .. _filters:
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
100
101 Filters
102 -------
103
0614747 @mineo Fix a typo
mineo authored
104 Variables can be modified by **filters**. Filters are separated from the
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
105 variable by a pipe symbol (``|``) and may have optional arguments in
106 parentheses. Multiple filters can be chained. The output of one filter is
107 applied to the next.
108
109 ``{{ name|striptags|title }}`` for example will remove all HTML Tags from the
110 `name` and title-cases it. Filters that accept arguments have parentheses
111 around the arguments, like a function call. This example will join a list
0aa0f58 @mitsuhiko Applied documentation patches by Clemens Hermann.
authored
112 by commas: ``{{ list|join(', ') }}``.
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
113
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt wron...
authored
114 The :ref:`builtin-filters` below describes all the builtin filters.
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
115
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
116 .. _tests:
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
117
118 Tests
119 -----
120
121 Beside filters there are also so called "tests" available. Tests can be used
122 to test a variable against a common expression. To test a variable or
123 expression you add `is` plus the name of the test after the variable. For
124 example to find out if a variable is defined you can do ``name is defined``
ad48a2e Fixed typos in documentation
Lukas Meuser authored
125 which will then return true or false depending on if `name` is defined.
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
126
127 Tests can accept arguments too. If the test only takes one argument you can
128 leave out the parentheses to group them. For example the following two
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
129 expressions do the same::
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
130
131 {% if loop.index is divisibleby 3 %}
132 {% if loop.index is divisibleby(3) %}
133
ad48a2e Fixed typos in documentation
Lukas Meuser authored
134 The :ref:`builtin-tests` below describes all the builtin tests.
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
135
136
137 Comments
138 --------
139
140 To comment-out part of a line in a template, use the comment syntax which is
141 by default set to ``{# ... #}``. This is useful to comment out parts of the
142 template for debugging or to add information for other template designers or
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
143 yourself::
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
144
a092a78 @dennda typo fix
dennda authored
145 {# note: disabled template because we no longer use this
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
146 {% for user in users %}
147 ...
148 {% endfor %}
149 #}
150
f35e281 @mitsuhiko some documentation improvements, jinja escapes " and ' now, both into ch...
authored
151
152 Whitespace Control
153 ------------------
154
155 In the default configuration whitespace is not further modified by the
156 template engine, so each whitespace (spaces, tabs, newlines etc.) is returned
157 unchanged. If the application configures Jinja to `trim_blocks` the first
158 newline after a a template tag is removed automatically (like in PHP).
159
160 But you can also strip whitespace in templates by hand. If you put an minus
161 sign (``-``) to the start or end of an block (for example a for tag), a
162 comment or variable expression you can remove the whitespaces after or before
163 that block::
164
165 {% for item in seq -%}
166 {{ item }}
167 {%- endfor %}
2004449 @andymckay fix typo
andymckay authored
168
f35e281 @mitsuhiko some documentation improvements, jinja escapes " and ' now, both into ch...
authored
169 This will yield all elements without whitespace between them. If `seq` was
170 a list of numbers from ``1`` to ``9`` the output would be ``123456789``.
171
9bb7e47 @mitsuhiko some more documentation updates and minor code cleanups. Additionally T...
authored
172 If :ref:`line-statements` are enabled they strip leading whitespace
173 automatically up to the beginning of the line.
174
175 .. admonition:: Note
f35e281 @mitsuhiko some documentation improvements, jinja escapes " and ' now, both into ch...
authored
176
9bb7e47 @mitsuhiko some more documentation updates and minor code cleanups. Additionally T...
authored
177 You must not use a whitespace between the tag and the minus sign.
178
179 **valid**::
61a5a24 @mitsuhiko fixed a bug in error reporting and some small documentation updates
authored
180
f35e281 @mitsuhiko some documentation improvements, jinja escapes " and ' now, both into ch...
authored
181 {%- if foo -%}...{% endif %}
182
9bb7e47 @mitsuhiko some more documentation updates and minor code cleanups. Additionally T...
authored
183 **invalid**::
f35e281 @mitsuhiko some documentation improvements, jinja escapes " and ' now, both into ch...
authored
184
185 {% - if foo - %}...{% endif %}
186
187
188 Escaping
189 --------
190
191 It is sometimes desirable or even necessary to have Jinja ignore parts it
192 would otherwise handle as variables or blocks. For example if the default
193 syntax is used and you want to use ``{{`` as raw string in the template and
194 not start a variable you have to use a trick.
195
196 The easiest way is to output the variable delimiter (``{{``) by using a
197 variable expression::
198
199 {{ '{{' }}
200
201 For bigger sections it makes sense to mark a block `raw`. For example to
202 put Jinja syntax as example into a template you can use this snippet::
203
204 {% raw %}
205 <ul>
206 {% for item in seq %}
207 <li>{{ item }}</li>
208 {% endfor %}
209 </ul>
210 {% endraw %}
211
212
213 .. _line-statements:
214
215 Line Statements
216 ---------------
217
218 If line statements are enabled by the application it's possible to mark a
219 line as a statement. For example if the line statement prefix is configured
220 to ``#`` the following two examples are equivalent::
221
222 <ul>
223 # for item in seq
224 <li>{{ item }}</li>
225 # endfor
226 </ul>
227
228 <ul>
229 {% for item in seq %}
230 <li>{{ item }}</li>
231 {% endfor %}
232 </ul>
233
234 The line statement prefix can appear anywhere on the line as long as no text
235 precedes it. For better readability statements that start a block (such as
236 `for`, `if`, `elif` etc.) may end with a colon::
237
238 # for item in seq:
239 ...
ac61b24 @birkenfeld Fix two typos.
birkenfeld authored
240 # endfor
f35e281 @mitsuhiko some documentation improvements, jinja escapes " and ' now, both into ch...
authored
241
242
3ef2043 @mitsuhiko updated documentation
authored
243 .. admonition:: Note
244
245 Line statements can span multiple lines if there are open parentheses,
246 braces or brackets::
247
248 <ul>
249 # for href, caption in [('index.html', 'Index'),
250 ('about.html', 'About')]:
251 <li><a href="{{ href }}">{{ caption }}</a></li>
252 # endfor
253 </ul>
254
59b6bd5 @mitsuhiko Added support for line-based comments.
authored
255 Since Jinja 2.2 line-based comments are available as well. For example if
256 the line-comment prefix is configured to be ``##`` everything from ``##`` to
257 the end of the line is ignored (excluding the newline sign)::
258
259 # for item in seq:
260 <li>{{ item }}</li> ## this comment is ignored
261 # endfor
262
3ef2043 @mitsuhiko updated documentation
authored
263
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
264 .. _template-inheritance:
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
265
266 Template Inheritance
267 --------------------
268
269 The most powerful part of Jinja is template inheritance. Template inheritance
270 allows you to build a base "skeleton" template that contains all the common
271 elements of your site and defines **blocks** that child templates can override.
272
273 Sounds complicated but is very basic. It's easiest to understand it by starting
274 with an example.
275
276
277 Base Template
278 ~~~~~~~~~~~~~
279
280 This template, which we'll call ``base.html``, defines a simple HTML skeleton
281 document that you might use for a simple two-column page. It's the job of
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
282 "child" templates to fill the empty blocks with content::
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
283
284 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
285 <html lang="en">
286 <html xmlns="http://www.w3.org/1999/xhtml">
287 <head>
288 {% block head %}
289 <link rel="stylesheet" href="style.css" />
290 <title>{% block title %}{% endblock %} - My Webpage</title>
291 {% endblock %}
292 </head>
293 <body>
294 <div id="content">{% block content %}{% endblock %}</div>
295 <div id="footer">
296 {% block footer %}
297 &copy; Copyright 2008 by <a href="http://domain.invalid/">you</a>.
298 {% endblock %}
299 </div>
300 </body>
301
302 In this example, the ``{% block %}`` tags define four blocks that child templates
303 can fill in. All the `block` tag does is to tell the template engine that a
304 child template may override those portions of the template.
305
306 Child Template
307 ~~~~~~~~~~~~~~
308
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
309 A child template might look like this::
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
310
311 {% extends "base.html" %}
312 {% block title %}Index{% endblock %}
313 {% block head %}
314 {{ super() }}
315 <style type="text/css">
316 .important { color: #336699; }
317 </style>
318 {% endblock %}
319 {% block content %}
320 <h1>Index</h1>
321 <p class="important">
6601537 @mitsuhiko Fixed typo.
authored
322 Welcome on my awesome homepage.
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
323 </p>
324 {% endblock %}
325
326 The ``{% extends %}`` tag is the key here. It tells the template engine that
327 this template "extends" another template. When the template system evaluates
328 this template, first it locates the parent. The extends tag should be the
329 first tag in the template. Everything before it is printed out normally and
fdf9530 @mitsuhiko added parsing code for "for item in seq recursive" and improved parser i...
authored
330 may cause confusion. For details about this behavior and how to take
331 advantage of it, see :ref:`null-master-fallback`.
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
332
333 The filename of the template depends on the template loader. For example the
334 :class:`FileSystemLoader` allows you to access other templates by giving the
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
335 filename. You can access templates in subdirectories with an slash::
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
336
337 {% extends "layout/default.html" %}
338
339 But this behavior can depend on the application embedding Jinja. Note that
340 since the child template doesn't define the ``footer`` block, the value from
341 the parent template is used instead.
342
343 You can't define multiple ``{% block %}`` tags with the same name in the
344 same template. This limitation exists because a block tag works in "both"
345 directions. That is, a block tag doesn't just provide a hole to fill - it
346 also defines the content that fills the hole in the *parent*. If there
347 were two similarly-named ``{% block %}`` tags in a template, that template's
348 parent wouldn't know which one of the blocks' content to use.
349
350 If you want to print a block multiple times you can however use the special
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
351 `self` variable and call the block with that name::
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
352
353 <title>{% block title %}{% endblock %}</title>
354 <h1>{{ self.title() }}</h1>
355 {% block body %}{% endblock %}
356
357
358 Super Blocks
359 ~~~~~~~~~~~~
360
361 It's possible to render the contents of the parent block by calling `super`.
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
362 This gives back the results of the parent block::
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
363
364 {% block sidebar %}
365 <h3>Table Of Contents</h3>
366 ...
367 {{ super() }}
368 {% endblock %}
369
370
fd31049 @mitsuhiko all calls are proxied by context.call now so that we can inject environm...
authored
371 Named Block End-Tags
372 ~~~~~~~~~~~~~~~~~~~~
373
374 Jinja2 allows you to put the name of the block after the end tag for better
375 readability::
376
377 {% block sidebar %}
378 {% block inner_sidebar %}
379 ...
380 {% endblock inner_sidebar %}
381 {% endblock sidebar %}
382
383 However the name after the `endblock` word must match the block name.
384
385
74a0cd9 @mitsuhiko Added support for optional `scoped` modifier to blocks.
authored
386 Block Nesting and Scope
387 ~~~~~~~~~~~~~~~~~~~~~~~
388
389 Blocks can be nested for more complex layouts. However per default blocks
390 may not access variables from outer scopes::
391
392 {% for item in seq %}
393 <li>{% block loop_item %}{{ item }}{% endblock %}</li>
394 {% endfor %}
395
396 This example would output empty ``<li>`` items because `item` is unavailable
397 inside the block. The reason for this is that if the block is replaced by
398 a child template a variable would appear that was not defined in the block or
399 passed to the context.
400
401 Starting with Jinja 2.2 you can explicitly specify that variables are
402 available in a block by setting the block to "scoped" by adding the `scoped`
403 modifier to a block declaration::
404
405 {% for item in seq %}
406 <li>{% block loop_item scoped %}{{ item }}{% endblock %}</li>
407 {% endfor %}
408
a93df48 @mitsuhiko speedup extension is now disabled by default (added message) and fixed a
authored
409 When overriding a block the `scoped` modifier does not have to be provided.
74a0cd9 @mitsuhiko Added support for optional `scoped` modifier to blocks.
authored
410
411
9165d3e @mitsuhiko the environment template loading functions now transparently
authored
412 Template Objects
413 ~~~~~~~~~~~~~~~~
414
415 .. versionchanged:: 2.4
416
417 If a template object was passed to the template context you can
418 extend from that object as well. Assuming the calling code passes
419 a layout template as `layout_template` to the environment, this
420 code works::
421
422 {% extends layout_template %}
423
424 Previously the `layout_template` variable had to be a string with
425 the layout template's filename for this to work.
426
427
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
428 HTML Escaping
429 -------------
430
431 When generating HTML from templates, there's always a risk that a variable will
432 include characters that affect the resulting HTML. There are two approaches:
433 manually escaping each variable or automatically escaping everything by default.
434
435 Jinja supports both, but what is used depends on the application configuration.
436 The default configuaration is no automatic escaping for various reasons:
437
438 - escaping everything except of safe values will also mean that Jinja is
439 escaping variables known to not include HTML such as numbers which is
440 a huge performance hit.
441
442 - The information about the safety of a variable is very fragile. It could
443 happen that by coercing safe and unsafe values the return value is double
444 escaped HTML.
445
446 Working with Manual Escaping
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt wron...
authored
447 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
448
449 If manual escaping is enabled it's **your** responsibility to escape
450 variables if needed. What to escape? If you have a variable that *may*
451 include any of the following chars (``>``, ``<``, ``&``, or ``"``) you
452 **have to** escape it unless the variable contains well-formed and trusted
453 HTML. Escaping works by piping the variable through the ``|e`` filter:
454 ``{{ user.username|e }}``.
455
456 Working with Automatic Escaping
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt wron...
authored
457 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
458
459 When automatic escaping is enabled everything is escaped by default except
460 for values explicitly marked as safe. Those can either be marked by the
461 application or in the template by using the `|safe` filter. The main
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt wron...
authored
462 problem with this approach is that Python itself doesn't have the concept
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
463 of tainted values so the information if a value is safe or unsafe can get
464 lost. If the information is lost escaping will take place which means that
465 you could end up with double escaped contents.
466
ad48a2e Fixed typos in documentation
Lukas Meuser authored
467 Double escaping is easy to avoid however, just rely on the tools Jinja2
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt wron...
authored
468 provides and don't use builtin Python constructs such as the string modulo
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
469 operator.
470
471 Functions returning template data (macros, `super`, `self.BLOCKNAME`) return
472 safe markup always.
473
474 String literals in templates with automatic escaping are considered unsafe
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt wron...
authored
475 too. The reason for this is that the safe string is an extension to Python
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
476 and not every library will work properly with it.
477
478
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt wron...
authored
479 List of Control Structures
480 --------------------------
481
482 A control structure refers to all those things that control the flow of a
483 program - conditionals (i.e. if/elif/else), for-loops, as well as things like
484 macros and blocks. Control structures appear inside ``{% ... %}`` blocks
485 in the default syntax.
486
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
487 For
488 ~~~
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt wron...
authored
489
ad48a2e Fixed typos in documentation
Lukas Meuser authored
490 Loop over each item in a sequence. For example, to display a list of users
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
491 provided in a variable called `users`::
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt wron...
authored
492
493 <h1>Members</h1>
494 <ul>
495 {% for user in users %}
496 <li>{{ user.username|e }}</li>
497 {% endfor %}
498 </ul>
499
500 Inside of a for loop block you can access some special variables:
501
502 +-----------------------+---------------------------------------------------+
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
503 | Variable | Description |
504 +=======================+===================================================+
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt wron...
authored
505 | `loop.index` | The current iteration of the loop. (1 indexed) |
506 +-----------------------+---------------------------------------------------+
507 | `loop.index0` | The current iteration of the loop. (0 indexed) |
508 +-----------------------+---------------------------------------------------+
509 | `loop.revindex` | The number of iterations from the end of the loop |
510 | | (1 indexed) |
511 +-----------------------+---------------------------------------------------+
512 | `loop.revindex0` | The number of iterations from the end of the loop |
513 | | (0 indexed) |
514 +-----------------------+---------------------------------------------------+
515 | `loop.first` | True if first iteration. |
516 +-----------------------+---------------------------------------------------+
517 | `loop.last` | True if last iteration. |
518 +-----------------------+---------------------------------------------------+
519 | `loop.length` | The number of items in the sequence. |
520 +-----------------------+---------------------------------------------------+
521 | `loop.cycle` | A helper function to cycle between a list of |
522 | | sequences. See the explanation below. |
523 +-----------------------+---------------------------------------------------+
524
ad48a2e Fixed typos in documentation
Lukas Meuser authored
525 Within a for-loop, it's possible to cycle among a list of strings/variables
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
526 each time through the loop by using the special `loop.cycle` helper::
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt wron...
authored
527
528 {% for row in rows %}
529 <li class="{{ loop.cycle('odd', 'even') }}">{{ row }}</li>
530 {% endfor %}
531
ccae055 @mitsuhiko Various cleanups and added custom cycler.
authored
532 With Jinja 2.1 an extra `cycle` helper exists that allows loop-unbound
533 cycling. For more information have a look at the :ref:`builtin-globals`.
534
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
535 .. _loop-filtering:
536
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt wron...
authored
537 Unlike in Python it's not possible to `break` or `continue` in a loop. You
538 can however filter the sequence during iteration which allows you to skip
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
539 items. The following example skips all the users which are hidden::
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt wron...
authored
540
541 {% for user in users if not user.hidden %}
542 <li>{{ user.username|e }}</li>
543 {% endfor %}
544
545 The advantage is that the special `loop` variable will count correctly thus
546 not counting the users not iterated over.
547
548 If no iteration took place because the sequence was empty or the filtering
549 removed all the items from the sequence you can render a replacement block
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
550 by using `else`::
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt wron...
authored
551
552 <ul>
553 {% for user in users %}
554 <li>{{ user.username|e }}</li>
555 {% else %}
556 <li><em>no users found</em></li>
890dac0 @mitsuhiko Fixed typo in documentation.
authored
557 {% endfor %}
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt wron...
authored
558 </ul>
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
559
1de4c64 @mitsuhiko documented recursive loops
authored
560 It is also possible to use loops recursively. This is useful if you are
561 dealing with recursive data such as sitemaps. To use loops recursively you
562 basically have to add the `recursive` modifier to the loop definition and
563 call the `loop` variable with the new iterable where you want to recurse.
564
565 The following example implements a sitemap with recursive loops::
566
567 <ul class="sitemap">
568 {%- for item in sitemap recursive %}
569 <li><a href="{{ item.href|e }}">{{ item.title }}</a>
570 {%- if item.children -%}
571 <ul class="submenu">{{ loop(item.children) }}</ul>
572 {%- endif %}</li>
573 {%- endfor %}
574 </ul>
575
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
576
577 If
578 ~~
579
580 The `if` statement in Jinja is comparable with the if statements of Python.
581 In the simplest form you can use it to test if a variable is defined, not
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
582 empty or not false::
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
583
584 {% if users %}
585 <ul>
586 {% for user in users %}
587 <li>{{ user.username|e }}</li>
588 {% endfor %}
589 </ul>
590 {% endif %}
591
592 For multiple branches `elif` and `else` can be used like in Python. You can
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
593 use more complex :ref:`expressions` there too::
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
594
595 {% if kenny.sick %}
596 Kenny is sick.
597 {% elif kenny.dead %}
598 You killed Kenny! You bastard!!!
599 {% else %}
600 Kenny looks okay --- so far
601 {% endif %}
602
603 If can also be used as :ref:`inline expression <if-expression>` and for
604 :ref:`loop filtering <loop-filtering>`.
605
606
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
607 Macros
608 ~~~~~~
609
ad48a2e Fixed typos in documentation
Lukas Meuser authored
610 Macros are comparable with functions in regular programming languages. They
611 are useful to put often used idioms into reusable functions to not repeat
612 yourself.
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
613
614 Here a small example of a macro that renders a form element::
615
616 {% macro input(name, value='', type='text', size=20) -%}
617 <input type="{{ type }}" name="{{ name }}" value="{{
618 value|e }}" size="{{ size }}">
619 {%- endmacro %}
620
621 The macro can then be called like a function in the namespace::
622
623 <p>{{ input('username') }}</p>
624 <p>{{ input('password', type='password') }}</p>
625
ad48a2e Fixed typos in documentation
Lukas Meuser authored
626 If the macro was defined in a different template you have to
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
627 :ref:`import <import>` it first.
628
629 Inside macros you have access to three special variables:
630
631 `varargs`
ad48a2e Fixed typos in documentation
Lukas Meuser authored
632 If more positional arguments are passed to the macro than accepted by the
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
633 macro they end up in the special `varargs` variable as list of values.
634
635 `kwargs`
636 Like `varargs` but for keyword arguments. All unconsumed keyword
637 arguments are stored in this special variable.
638
639 `caller`
ad48a2e Fixed typos in documentation
Lukas Meuser authored
640 If the macro was called from a :ref:`call<call>` tag the caller is stored
641 in this variable as macro which can be called.
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
642
643 Macros also expose some of their internal details. The following attributes
644 are available on a macro object:
645
646 `name`
647 The name of the macro. ``{{ input.name }}`` will print ``input``.
648
649 `arguments`
650 A tuple of the names of arguments the macro accepts.
651
652 `defaults`
653 A tuple of default values.
654
655 `catch_kwargs`
656 This is `true` if the macro accepts extra keyword arguments (ie: accesses
657 the special `kwargs` variable).
658
659 `catch_varargs`
660 This is `true` if the macro accepts extra positional arguments (ie:
661 accesses the special `varargs` variable).
662
663 `caller`
664 This is `true` if the macro accesses the special `caller` variable and may
ad48a2e Fixed typos in documentation
Lukas Meuser authored
665 be called from a :ref:`call<call>` tag.
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
666
c347ed0 @mitsuhiko Unified some code in the super/template reference system.
authored
667 If a macro name starts with an underscore it's not exported and can't
668 be imported.
669
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
670
671 .. _call:
672
673 Call
674 ~~~~
675
676 In some cases it can be useful to pass a macro to another macro. For this
677 purpose you can use the special `call` block. The following example shows
678 a macro that takes advantage of the call functionality and how it can be
679 used::
680
681 {% macro render_dialog(title, class='dialog') -%}
682 <div class="{{ class }}">
683 <h2>{{ title }}</h2>
684 <div class="contents">
685 {{ caller() }}
686 </div>
687 </div>
688 {%- endmacro %}
689
690 {% call render_dialog('Hello World') %}
691 This is a simple dialog rendered by using a macro and
692 a call block.
693 {% endcall %}
694
695 It's also possible to pass arguments back to the call block. This makes it
a2eb77d @mitsuhiko call is now handled like a regular unnamed macro, refactored compiled a ...
authored
696 useful as replacement for loops. Generally speaking a call block works
697 exactly like an macro, just that it doesn't have a name.
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
698
699 Here an example of how a call block can be used with arguments::
700
701 {% macro dump_users(users) -%}
702 <ul>
703 {%- for user in users %}
704 <li><p>{{ user.username|e }}</p>{{ caller(user) }}</li>
705 {%- endfor %}
706 </ul>
707 {%- endmacro %}
708
709 {% call(user) dump_users(list_of_user) %}
710 <dl>
711 <dl>Realname</dl>
712 <dd>{{ user.realname|e }}</dd>
713 <dl>Description</dl>
714 <dd>{{ user.description }}</dd>
715 </dl>
716 {% endcall %}
717
718
76f9aa4 @mitsuhiko Altered filesizeformat to support both MB and MiB, documented `{% filter...
authored
719 Filters
720 ~~~~~~~
721
722 Filter sections allow you to apply regular Jinja2 filters on a block of
723 template data. Just wrap the code in the special `filter` section::
724
725 {% filter upper %}
726 This text becomes uppercase
727 {% endfilter %}
728
729
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
730 Assignments
731 ~~~~~~~~~~~
732
733 Inside code blocks you can also assign values to variables. Assignments at
734 top level (outside of blocks, macros or loops) are exported from the template
735 like top level macros and can be imported by other templates.
736
2e30cf5 @mitsuhiko documented set changes
authored
737 Assignments use the `set` tag and can have multiple targets::
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
738
2e30cf5 @mitsuhiko documented set changes
authored
739 {% set navigation = [('index.html', 'Index'), ('about.html', 'About')] %}
740 {% set key, value = call_something() %}
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
741
742
743 Extends
744 ~~~~~~~
745
746 The `extends` tag can be used to extend a template from another one. You
747 can have multiple of them in a file but only one of them may be executed
4ac4bdf @mitsuhiko Documentation no longer mentiones "no multiple inheritance" support. tha...
authored
748 at the time. See the section about :ref:`template-inheritance` above.
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
749
750
751 Block
752 ~~~~~
753
754 Blocks are used for inheritance and act as placeholders and replacements
755 at the same time. They are documented in detail as part of the section
756 about :ref:`template-inheritance`.
757
758
759 Include
760 ~~~~~~~
761
762 The `include` statement is useful to include a template and return the
763 rendered contents of that file into the current namespace::
764
765 {% include 'header.html' %}
766 Body
767 {% include 'footer.html' %}
768
ea847c5 @mitsuhiko added "with context" or "without context" import/include modifiers
authored
769 Included templates have access to the variables of the active context by
770 default. For more details about context behavior of imports and includes
771 see :ref:`import-visibility`.
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
772
37f58ce @mitsuhiko Include statements can now be marked with ``ignore missing`` to skip
authored
773 From Jinja 2.2 onwards you can mark an include with ``ignore missing`` in
774 which case Jinja will ignore the statement if the template to be ignored
775 does not exist. When combined with ``with`` or ``without context`` it has
776 to be placed *before* the context visibility statement. Here some valid
777 examples::
778
779 {% include "sidebar.html" ignore missing %}
780 {% include "sidebar.html" ignore missing with context %}
781 {% include "sidebar.html" ignore missing without context %}
782
31bbd9e @mitsuhiko include tags are now able to select between multiple templates
authored
783 .. versionadded:: 2.2
784
785 You can also provide a list of templates that are checked for existence
786 before inclusion. The first template that exists will be included. If
787 `ignore missing` is given, it will fall back to rendering nothing if
788 none of the templates exist, otherwise it will raise an exception.
789
790 Example::
791
792 {% include ['page_detailed.html', 'page.html'] %}
793 {% include ['special_sidebar.html', 'sidebar.html'] ignore missing %}
794
9165d3e @mitsuhiko the environment template loading functions now transparently
authored
795 .. versionchanged:: 2.4
796 If a template object was passed to the template context you can
797 include that object using `include`.
798
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
799 .. _import:
800
801 Import
802 ~~~~~~
803
804 Jinja2 supports putting often used code into macros. These macros can go into
805 different templates and get imported from there. This works similar to the
806 import statements in Python. It's important to know that imports are cached
807 and imported templates don't have access to the current template variables,
ea847c5 @mitsuhiko added "with context" or "without context" import/include modifiers
authored
808 just the globals by defualt. For more details about context behavior of
809 imports and includes see :ref:`import-visibility`.
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
810
811 There are two ways to import templates. You can import the complete template
812 into a variable or request specific macros / exported variables from it.
813
814 Imagine we have a helper module that renders forms (called `forms.html`)::
815
816 {% macro input(name, value='', type='text') -%}
817 <input type="{{ type }}" value="{{ value|e }}" name="{{ name }}">
818 {%- endmacro %}
819
820 {%- macro textarea(name, value='', rows=10, cols=40) -%}
821 <textarea name="{{ name }}" rows="{{ rows }}" cols="{{ cols
822 }}">{{ value|e }}</textarea>
823 {%- endmacro %}
824
825 The easiest and most flexible is importing the whole module into a variable.
826 That way you can access the attributes::
827
828 {% import 'forms.html' as forms %}
829 <dl>
830 <dt>Username</dt>
831 <dd>{{ forms.input('username') }}</dd>
832 <dt>Password</dt>
833 <dd>{{ forms.input('password', type='password') }}</dd>
834 </dl>
835 <p>{{ forms.textarea('comment') }}</p>
836
837
838 Alternatively you can import names from the template into the current
839 namespace::
840
841 {% from 'forms.html' import input as input_field, textarea %}
842 <dl>
843 <dt>Username</dt>
844 <dd>{{ input_field('username') }}</dd>
845 <dt>Password</dt>
846 <dd>{{ input_field('password', type='password') }}</dd>
847 </dl>
848 <p>{{ textarea('comment') }}</p>
849
903d168 @mitsuhiko variables starting with one or more underscores are not exported
authored
850 Macros and variables starting with one ore more underscores are private and
851 cannot be imported.
852
9165d3e @mitsuhiko the environment template loading functions now transparently
authored
853 .. versionchanged:: 2.4
854 If a template object was passed to the template context you can
855 import from that object.
856
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
857
ea847c5 @mitsuhiko added "with context" or "without context" import/include modifiers
authored
858 .. _import-visibility:
859
860 Import Context Behavior
861 -----------------------
862
863 Per default included templates are passed the current context and imported
864 templates not. The reason for this is that imports unlike includes are
865 cached as imports are often used just as a module that holds macros.
866
867 This however can be changed of course explicitly. By adding `with context`
868 or `without context` to the import/include directive the current context
869 can be passed to the template and caching is disabled automatically.
870
871 Here two examples::
872
873 {% from 'forms.html' import input with context %}
874 {% include 'header.html' without context %}
875
673aa88 @mitsuhiko imports and includes "with context" are passed the full context now, not...
authored
876 .. admonition:: Note
877
878 In Jinja 2.0 the context that was passed to the included template
0aa0f58 @mitsuhiko Applied documentation patches by Clemens Hermann.
authored
879 did not include variables defined in the template. As a matter of
673aa88 @mitsuhiko imports and includes "with context" are passed the full context now, not...
authored
880 fact this did not work::
881
882 {% for box in boxes %}
883 {% include "render_box.html" %}
884 {% endfor %}
885
02901a8 @alanhogan Clarity
alanhogan authored
886 The included template ``render_box.html`` is *not* able to access
887 `box` in Jinja 2.0. As of Jinja 2.1 ``render_box.html`` *is* able
888 to do so.
673aa88 @mitsuhiko imports and includes "with context" are passed the full context now, not...
authored
889
ea847c5 @mitsuhiko added "with context" or "without context" import/include modifiers
authored
890
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
891 .. _expressions:
892
893 Expressions
894 -----------
895
896 Jinja allows basic expressions everywhere. These work very similar to regular
897 Python and even if you're not working with Python you should feel comfortable
898 with it.
899
900 Literals
901 ~~~~~~~~
902
903 The simplest form of expressions are literals. Literals are representations
904 for Python objects such as strings and numbers. The following literals exist:
905
316157d @mitsuhiko fixed another python2.4 bug
authored
906 "Hello World":
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
907 Everything between two double or single quotes is a string. They are
908 useful whenever you need a string in the template (for example as
909 arguments to function calls, filters or just to extend or include a
910 template).
911
316157d @mitsuhiko fixed another python2.4 bug
authored
912 42 / 42.23:
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
913 Integers and floating point numbers are created by just writing the
914 number down. If a dot is present the number is a float, otherwise an
915 integer. Keep in mind that for Python ``42`` and ``42.0`` is something
916 different.
917
316157d @mitsuhiko fixed another python2.4 bug
authored
918 ['list', 'of', 'objects']:
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
919 Everything between two brackets is a list. Lists are useful to store
920 sequential data in or to iterate over them. For example you can easily
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
921 create a list of links using lists and tuples with a for loop::
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
922
923 <ul>
924 {% for href, caption in [('index.html', 'Index'), ('about.html', 'About'),
925 ('downloads.html', 'Downloads')] %}
926 <li><a href="{{ href }}">{{ caption }}</a></li>
927 {% endfor %}
928 </ul>
929
316157d @mitsuhiko fixed another python2.4 bug
authored
930 ('tuple', 'of', 'values'):
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
931 Tuples are like lists, just that you can't modify them. If the tuple
932 only has one item you have to end it with a comma. Tuples are usually
933 used to represent items of two or more elements. See the example above
934 for more details.
935
ad48a2e Fixed typos in documentation
Lukas Meuser authored
936 {'dict': 'of', 'key': 'and', 'value': 'pairs'}:
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
937 A dict in Python is a structure that combines keys and values. Keys must
938 be unique and always have exactly one value. Dicts are rarely used in
939 templates, they are useful in some rare cases such as the :func:`xmlattr`
940 filter.
941
316157d @mitsuhiko fixed another python2.4 bug
authored
942 true / false:
9bb7e47 @mitsuhiko some more documentation updates and minor code cleanups. Additionally T...
authored
943 true is always true and false is always false.
944
945 .. admonition:: Note
946
947 The special constants `true`, `false` and `none` are indeed lowercase.
948 Because that caused confusion in the past, when writing `True` expands
949 to an undefined variable that is considered false, all three of them can
950 be written in title case too (`True`, `False`, and `None`). However for
951 consistency (all Jinja identifiers are lowercase) you should use the
952 lowercase versions.
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
953
954 Math
955 ~~~~
956
957 Jinja allows you to calculate with values. This is rarely useful in templates
0aa0f58 @mitsuhiko Applied documentation patches by Clemens Hermann.
authored
958 but exists for completeness' sake. The following operators are supported:
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
959
316157d @mitsuhiko fixed another python2.4 bug
authored
960 \+
0aa0f58 @mitsuhiko Applied documentation patches by Clemens Hermann.
authored
961 Adds two objects together. Usually the objects are numbers but if both are
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
962 strings or lists you can concatenate them this way. This however is not
963 the preferred way to concatenate strings! For string concatenation have
964 a look at the ``~`` operator. ``{{ 1 + 1 }}`` is ``2``.
965
316157d @mitsuhiko fixed another python2.4 bug
authored
966 \-
0aa0f58 @mitsuhiko Applied documentation patches by Clemens Hermann.
authored
967 Substract the second number from the first one. ``{{ 3 - 2 }}`` is ``1``.
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
968
316157d @mitsuhiko fixed another python2.4 bug
authored
969 /
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
970 Divide two numbers. The return value will be a floating point number.
971 ``{{ 1 / 2 }}`` is ``{{ 0.5 }}``.
972
316157d @mitsuhiko fixed another python2.4 bug
authored
973 //
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
974 Divide two numbers and return the truncated integer result.
6ae1285 @fabiant7t Fixed example of a division with a truncated integer result (it's // ins...
fabiant7t authored
975 ``{{ 20 // 7 }}`` is ``2``.
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
976
316157d @mitsuhiko fixed another python2.4 bug
authored
977 %
0aa0f58 @mitsuhiko Applied documentation patches by Clemens Hermann.
authored
978 Calculate the remainder of an integer division. ``{{ 11 % 7 }}`` is ``4``.
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
979
316157d @mitsuhiko fixed another python2.4 bug
authored
980 \*
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
981 Multiply the left operand with the right one. ``{{ 2 * 2 }}`` would
0aa0f58 @mitsuhiko Applied documentation patches by Clemens Hermann.
authored
982 return ``4``. This can also be used to repeat a string multiple times.
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
983 ``{{ '=' * 80 }}`` would print a bar of 80 equal signs.
984
316157d @mitsuhiko fixed another python2.4 bug
authored
985 \**
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
986 Raise the left operand to the power of the right operand. ``{{ 2**3 }}``
987 would return ``8``.
988
3c95532 @mitsuhiko Fixed spelling
authored
989 Comparisons
990 ~~~~~~~~~~~
13203e1 @mitsuhiko Added docs for comparisions
authored
991
992 ==
993 Compares two objects for equality.
994
995 !=
996 Compares two objects for inequality.
997
998 >
999 `true` if the left hand side is greater than the right hand side.
1000
1001 >=
1002 `true` if the left hand side is greater or equal to the right hand side.
1003
1004 <
1005 `true` if the left hand side is lower than the right hand side.
1006
1007 <=
1008 `true` if the left hand side is lower or equal to the right hand side.
1009
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
1010 Logic
1011 ~~~~~
1012
0aa0f58 @mitsuhiko Applied documentation patches by Clemens Hermann.
authored
1013 For `if` statements, `for` filtering or `if` expressions it can be useful to
1014 combine multiple expressions:
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
1015
316157d @mitsuhiko fixed another python2.4 bug
authored
1016 and
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
1017 Return true if the left and the right operand is true.
1018
316157d @mitsuhiko fixed another python2.4 bug
authored
1019 or
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
1020 Return true if the left or the right operand is true.
1021
316157d @mitsuhiko fixed another python2.4 bug
authored
1022 not
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
1023 negate a statement (see below).
1024
316157d @mitsuhiko fixed another python2.4 bug
authored
1025 (expr)
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
1026 group an expression.
1027
9bb7e47 @mitsuhiko some more documentation updates and minor code cleanups. Additionally T...
authored
1028 .. admonition:: Note
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
1029
9bb7e47 @mitsuhiko some more documentation updates and minor code cleanups. Additionally T...
authored
1030 The ``is`` and ``in`` operators support negation using an infix notation
1031 too: ``foo is not bar`` and ``foo not in bar`` instead of ``not foo is bar``
1032 and ``not foo in bar``. All other expressions require a prefix notation:
1033 ``not (foo and bar).``
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
1034
1035
1036 Other Operators
1037 ~~~~~~~~~~~~~~~
1038
1039 The following operators are very useful but don't fit into any of the other
1040 two categories:
1041
316157d @mitsuhiko fixed another python2.4 bug
authored
1042 in
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
1043 Perform sequence / mapping containment test. Returns true if the left
1044 operand is contained in the right. ``{{ 1 in [1, 2, 3] }}`` would for
1045 example return true.
1046
316157d @mitsuhiko fixed another python2.4 bug
authored
1047 is
1048 Performs a :ref:`test <tests>`.
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
1049
316157d @mitsuhiko fixed another python2.4 bug
authored
1050 \|
1051 Applies a :ref:`filter <filters>`.
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
1052
316157d @mitsuhiko fixed another python2.4 bug
authored
1053 ~
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
1054 Converts all operands into strings and concatenates them.
1055 ``{{ "Hello " ~ name ~ "!" }}`` would return (assuming `name` is
1056 ``'John'``) ``Hello John!``.
1057
316157d @mitsuhiko fixed another python2.4 bug
authored
1058 ()
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
1059 Call a callable: ``{{ post.render() }}``. Inside of the parentheses you
0aa0f58 @mitsuhiko Applied documentation patches by Clemens Hermann.
authored
1060 can use positional arguments and keyword arguments like in python:
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
1061 ``{{ post.render(user, full=true) }}``.
1062
316157d @mitsuhiko fixed another python2.4 bug
authored
1063 . / []
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
1064 Get an attribute of an object. (See :ref:`variables`)
1065
1066
1067 .. _if-expression:
1068
1069 If Expression
1070 ~~~~~~~~~~~~~
1071
b2a36aa @mitsuhiko updated jinja docs
authored
1072 It is also possible to use inline `if` expressions. These are useful in some
1073 situations. For example you can use this to extend from one template if a
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
1074 variable is defined, otherwise from the default layout template::
b2a36aa @mitsuhiko updated jinja docs
authored
1075
1076 {% extends layout_template if layout_template is defined else 'master.html' %}
709f6e5 @mitsuhiko python2.4 compatibility and doc updates
authored
1077
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports are n...
authored
1078 The general syntax is ``<do something> if <something is true> else <do
1079 something else>``.
1080
a0e3ac0 @mitsuhiko Documented if-conditional changes.
authored
1081 The `else` part is optional. If not provided the else block implicitly
1082 evaluates into an undefined object::
1083
1084 {{ '[%s]' % page.title if page.title }}
1085
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt wron...
authored
1086
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
1087 .. _builtin-filters:
1088
1089 List of Builtin Filters
1090 -----------------------
1091
1092 .. jinjafilters::
1093
1094
1095 .. _builtin-tests:
1096
1097 List of Builtin Tests
1098 ---------------------
1099
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt wron...
authored
1100 .. jinjatests::
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
1101
ccae055 @mitsuhiko Various cleanups and added custom cycler.
authored
1102 .. _builtin-globals:
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
1103
1104 List of Global Functions
1105 ------------------------
1106
1107 The following functions are available in the global scope by default:
1108
1109 .. function:: range([start,] stop[, step])
1110
1111 Return a list containing an arithmetic progression of integers.
1112 range(i, j) returns [i, i+1, i+2, ..., j-1]; start (!) defaults to 0.
1113 When step is given, it specifies the increment (or decrement).
1114 For example, range(4) returns [0, 1, 2, 3]. The end point is omitted!
1115 These are exactly the valid indices for a list of 4 elements.
1116
19cf9c2 @mitsuhiko small performance improvements
authored
1117 This is useful to repeat a template block multiple times for example
1118 to fill a list. Imagine you have 7 users in the list but you want to
1119 render three empty items to enforce a height with CSS::
1120
1121 <ul>
1122 {% for user in users %}
1123 <li>{{ user.username }}</li>
1124 {% endfor %}
1125 {% for number in range(10 - users|count) %}
1126 <li class="empty"><span>...</span></li>
1127 {% endfor %}
1128 </ul>
1129
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
1130 .. function:: lipsum(n=5, html=True, min=20, max=100)
1131
1132 Generates some lorem ipsum for the template. Per default five paragraphs
1133 with HTML are generated each paragraph between 20 and 100 words. If html
1134 is disabled regular text is returned. This is useful to generate simple
1135 contents for layout testing.
76c280b @mitsuhiko improved sandbox, added proper striptags and updated documentation to la...
authored
1136
ed98cac @mitsuhiko some documentation updates
authored
1137 .. function:: dict(\**items)
76c280b @mitsuhiko improved sandbox, added proper striptags and updated documentation to la...
authored
1138
1139 A convenient alternative to dict literals. ``{'foo': 'bar'}`` is the same
1140 as ``dict(foo='bar')``.
ed98cac @mitsuhiko some documentation updates
authored
1141
ccae055 @mitsuhiko Various cleanups and added custom cycler.
authored
1142 .. class:: cycler(\*items)
1143
1144 The cycler allows you to cycle among values similar to how `loop.cycle`
1145 works. Unlike `loop.cycle` however you can use this cycler outside of
1146 loops or over multiple loops.
1147
1148 This is for example very useful if you want to show a list of folders and
0aa0f58 @mitsuhiko Applied documentation patches by Clemens Hermann.
authored
1149 files, with the folders on top, but both in the same list with alternating
ccae055 @mitsuhiko Various cleanups and added custom cycler.
authored
1150 row colors.
1151
1152 The following example shows how `cycler` can be used::
1153
1154 {% set row_class = cycler('odd', 'even') %}
1155 <ul class="browser">
1156 {% for folder in folders %}
1157 <li class="folder {{ row_class.next() }}">{{ folder|e }}</li>
1158 {% endfor %}
1159 {% for filename in files %}
1160 <li class="file {{ row_class.next() }}">{{ filename|e }}</li>
1161 {% endfor %}
1162 </ul>
1163
1164 A cycler has the following attributes and methods:
1165
1166 .. method:: reset()
1167
1168 Resets the cycle to the first item.
1169
1170 .. method:: next()
1171
1172 Goes one item a head and returns the then current item.
1173
1174 .. attribute:: current
1175
1176 Returns the current item.
2004449 @andymckay fix typo
andymckay authored
1177
ccae055 @mitsuhiko Various cleanups and added custom cycler.
authored
1178 **new in Jinja 2.1**
1179
d34eb12 @mitsuhiko Implemented and documented "joiner"
authored
1180 .. class:: joiner(sep=', ')
1181
1182 A tiny helper that can be use to "join" multiple sections. A joiner is
bc542b0 @kschuetz calld->called
kschuetz authored
1183 passed a string and will return that string every time it's called, except
d34eb12 @mitsuhiko Implemented and documented "joiner"
authored
1184 the first time in which situation it returns an empty string. You can
1185 use this to join things::
1186
1187 {% set pipe = joiner("|") %}
1188 {% if categories %} {{ pipe() }}
1189 Categories: {{ categories|join(", ") }}
1190 {% endif %}
1191 {% if author %} {{ pipe() }}
1192 Author: {{ author() }}
1193 {% endif %}
1194 {% if can_edit %} {{ pipe() }}
1195 <a href="?action=edit">Edit</a>
1196 {% endif %}
1197
1198 **new in Jinja 2.1**
1199
ed98cac @mitsuhiko some documentation updates
authored
1200
1201 Extensions
1202 ----------
1203
1204 The following sections cover the built-in Jinja2 extensions that may be
1205 enabled by the application. The application could also provide further
1206 extensions not covered by this documentation. In that case there should
1207 be a separate document explaining the extensions.
1208
1209 .. _i18n-in-templates:
1210
1211 i18n
1212 ~~~~
1213
1214 If the i18n extension is enabled it's possible to mark parts in the template
1215 as translatable. To mark a section as translatable you can use `trans`::
1216
1217 <p>{% trans %}Hello {{ user }}!{% endtrans %}</p>
1218
1219 To translate a template expression --- say, using template filters or just
1220 accessing an attribute of an object --- you need to bind the expression to a
1221 name for use within the translation block::
1222
1223 <p>{% trans user=user.username %}Hello {{ user }}!{% endtrans %}</p>
1224
1225 If you need to bind more than one expression inside a `trans` tag, separate
1226 the pieces with a comma (``,``)::
1227
1228 {% trans book_title=book.title, author=author.name %}
1229 This is {{ book_title }} by {{ author }}
1230 {% endtrans %}
1231
1232 Inside trans tags no statements are allowed, only variable tags are.
1233
1234 To pluralize, specify both the singular and plural forms with the `pluralize`
1235 tag, which appears between `trans` and `endtrans`::
1236
1237 {% trans count=list|length %}
1238 There is {{ count }} {{ name }} object.
1239 {% pluralize %}
1240 There are {{ count }} {{ name }} objects.
1241 {% endtrans %}
1242
1243 Per default the first variable in a block is used to determine the correct
1244 singular or plural form. If that doesn't work out you can specify the name
1245 which should be used for pluralizing by adding it as parameter to `pluralize`::
1246
1247 {% trans ..., user_count=users|length %}...
1248 {% pluralize user_count %}...{% endtrans %}
1249
1250 It's also possible to translate strings in expressions. For that purpose
1251 three functions exist:
1252
1253 _ `gettext`: translate a single string
1254 - `ngettext`: translate a pluralizable string
1255 - `_`: alias for `gettext`
1256
1257 For example you can print a translated string easily this way::
1258
1259 {{ _('Hello World!') }}
1260
1261 To use placeholders you can use the `format` filter::
1262
1263 {{ _('Hello %(user)s!')|format(user=user.username) }}
1264
1265 For multiple placeholders always use keyword arguments to `format` as other
1266 languages may not use the words in the same order.
5d2733f @mitsuhiko void -> do
authored
1267
ffaa2e7 @mitsuhiko it's now possible to register extensions after an environment
authored
1268 .. versionchanged:: 2.5
1269
8a3d93b @mitsuhiko Fixed a typo in the docs
authored
1270 If newstyle gettext calls are activated (:ref:`newstyle-gettext`), using
ffaa2e7 @mitsuhiko it's now possible to register extensions after an environment
authored
1271 placeholders is a lot easier:
1272
1273 .. sourcecode:: html+jinja
1274
1275 {{ gettext('Hello World!') }}
1276 {{ gettext('Hello %(name)s!', name='World') }}
1277 {{ ngettext('%(num)d apple', '%(num)d apples', apples|count) }}
1278
522af5d @kschuetz recieves->receives
kschuetz authored
1279 Note that the `ngettext` function's format string automatically receives
ffaa2e7 @mitsuhiko it's now possible to register extensions after an environment
authored
1280 the count as `num` parameter additionally to the regular parameters.
1281
5d2733f @mitsuhiko void -> do
authored
1282
61a5a24 @mitsuhiko fixed a bug in error reporting and some small documentation updates
authored
1283 Expression Statement
1284 ~~~~~~~~~~~~~~~~~~~~
5d2733f @mitsuhiko void -> do
authored
1285
1286 If the expression-statement extension is loaded a tag called `do` is available
1287 that works exactly like the regular variable expression (``{{ ... }}``) just
e25f24d @mitsuhiko more thread safety in LRUCache
authored
1288 that it doesn't print anything. This can be used to modify lists::
5d2733f @mitsuhiko void -> do
authored
1289
1290 {% do navigation.append('a string') %}
3da9031 @mitsuhiko added loopcontrols extension and added unittests for it
authored
1291
1292
1293 Loop Controls
1294 ~~~~~~~~~~~~~
1295
1296 If the application enables the :ref:`loopcontrols-extension` it's possible to
1297 use `break` and `continue` in loops. When `break` is reached, the loop is
30b17d8 @kschuetz eached->reached
kschuetz authored
1298 terminated; if `continue` is reached the processing is stopped and continues
3da9031 @mitsuhiko added loopcontrols extension and added unittests for it
authored
1299 with the next iteration.
1300
1301 Here a loop that skips every second item::
1302
1303 {% for user in users %}
1304 {%- if loop.index is even %}{% continue %}{% endif %}
1305 ...
1306 {% endfor %}
1307
1308 Likewise a look that stops processing after the 10th iteration::
1309
1310 {% for user in users %}
1311 {%- if loop.index >= 10 %}{% break %}{% endif %}
1312 {%- endfor %}
9b4cc9f @mitsuhiko added with-statement extension.
authored
1313
1314
1315 With Statement
1316 ~~~~~~~~~~~~~~
1317
1318 .. versionadded:: 2.3
1319
1320 If the application enables the :ref:`with-extension` it is possible to
1321 use the `with` keyword in templates. This makes it possible to create
1322 a new inner scope. Variables set within this scope are not visible
1323 outside of the scope.
1324
1325 With in a nutshell::
1326
1327 {% with %}
1328 {% set foo = 42 %}
1329 {{ foo }} foo is 42 here
1330 {% endwith %}
1331 foo is not visible here any longer
1332
1333 Because it is common to set variables at the beginning of the scope
1334 you can do that within the with statement. The following two examples
1335 are equivalent::
1336
1337 {% with foo = 42 %}
1338 {{ foo }}
1339 {% endwith %}
1340
1341 {% with %}
1342 {% set foo = 42 %}
1343 {{ foo }}
1344 {% endwith %}
fe150f3 @mitsuhiko Documented autoescaping behavior and eval contexts.
authored
1345
752ba7f @mitsuhiko Added missing reference.
authored
1346 .. _autoescape-overrides:
fe150f3 @mitsuhiko Documented autoescaping behavior and eval contexts.
authored
1347
1348 Autoescape Extension
1349 --------------------
1350
1351 .. versionadded:: 2.4
1352
1353 If the application enables the :ref:`autoescape-extension` one can
1354 activate and deactivate the autoescaping from within the templates.
1355
1356 Example::
1357
1358 {% autoescape true %}
1359 Autoescaping is active within this block
1360 {% endautoescape %}
1361
1362 {% autoescape false %}
1363 Autoescaping is inactive within this block
1364 {% endautoescape %}
1365
1366 After the `endautoescape` the behavior is reverted to what it was before.
Something went wrong with that request. Please try again.