docs/templates.rst

   1 Template Designer Documentation
   2 ===============================
   3
   4 .. highlight:: html+jinja
   5
   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
  25 the details later in that document::
  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
  47 There are two kinds of delimiers. ``{% ... %}`` and ``{{ ... }}``.  The first
  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
  51 .. _variables:
  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
  62 so-called "subscribe" syntax (``[]``) can be used.  The following lines do
  63 the same::
  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
  77 .. _filters:
  78
  79 Filters
  80 -------
  81
  82 Variables can by modified by **filters**.  Filters are separated from the
  83 variable by a pipe symbol (``|``) and may have optional arguments in
  84 parentheses.  Multiple filters can be chained.  The output of one filter is
  85 applied to the next.
  86
  87 ``{{ name|striptags|title }}`` for example will remove all HTML Tags from the
  88 `name` and title-cases it.  Filters that accept arguments have parentheses
  89 around the arguments, like a function call.  This example will join a list
  90 by spaces:  ``{{ list|join(', ') }}``.
  91
  92 The :ref:`builtin-filters` below describes all the builtin filters.
  93
  94 .. _tests:
  95
  96 Tests
  97 -----
  98
  99 Beside filters there are also so called "tests" available.  Tests can be used
 100 to test a variable against a common expression.  To test a variable or
 101 expression you add `is` plus the name of the test after the variable.  For
 102 example to find out if a variable is defined you can do ``name is defined``
 103 which will then return true or false depending on if `name` is defined.
 104
 105 Tests can accept arguments too.  If the test only takes one argument you can
 106 leave out the parentheses to group them.  For example the following two
 107 expressions do the same::
 108
 109     {% if loop.index is divisibleby 3 %}
 110     {% if loop.index is divisibleby(3) %}
 111
 112 The :ref:`builtin-tests` below describes all the builtin tests.
 113
 114
 115 Comments
 116 --------
 117
 118 To comment-out part of a line in a template, use the comment syntax which is
 119 by default set to ``{# ... #}``.  This is useful to comment out parts of the
 120 template for debugging or to add information for other template designers or
 121 yourself::
 122
 123     {# note: disabled template because we no longer user this
 124         {% for user in users %}
 125             ...
 126         {% endfor %}
 127     #}
 128
 129
 130 Whitespace Control
 131 ------------------
 132
 133 In the default configuration whitespace is not further modified by the
 134 template engine, so each whitespace (spaces, tabs, newlines etc.) is returned
 135 unchanged.  If the application configures Jinja to `trim_blocks` the first
 136 newline after a a template tag is removed automatically (like in PHP).
 137
 138 But you can also strip whitespace in templates by hand.  If you put an minus
 139 sign (``-``) to the start or end of an block (for example a for tag), a
 140 comment or variable expression you can remove the whitespaces after or before
 141 that block::
 142
 143     {% for item in seq -%}
 144         {{ item }}
 145     {%- endfor %}
 146
 147 This will yield all elements without whitespace between them.  If `seq` was
 148 a list of numbers from ``1`` to ``9`` the output would be ``123456789``.
 149
 150 Note that you must not use a whitespace between the tag and the minus sign:
 151
 152     valid:
 153         {%- if foo -%}...{% endif %}
 154
 155     invalid:
 156
 157         {% - if foo - %}...{% endif %}
 158
 159 If :ref:`line-statements` are enabled they strip leading whitespace
 160 automatically up to the beginning of the line.
 161
 162
 163 Escaping
 164 --------
 165
 166 It is sometimes desirable or even necessary to have Jinja ignore parts it
 167 would otherwise handle as variables or blocks.  For example if the default
 168 syntax is used and you want to use ``{{`` as raw string in the template and
 169 not start a variable you have to use a trick.
 170
 171 The easiest way is to output the variable delimiter (``{{``) by using a
 172 variable expression::
 173
 174     {{ '{{' }}
 175
 176 For bigger sections it makes sense to mark a block `raw`.  For example to
 177 put Jinja syntax as example into a template you can use this snippet::
 178
 179     {% raw %}
 180         <ul>
 181         {% for item in seq %}
 182             <li>{{ item }}</li>
 183         {% endfor %}
 184         </ul>
 185     {% endraw %}
 186
 187
 188 .. _line-statements:
 189
 190 Line Statements
 191 ---------------
 192
 193 If line statements are enabled by the application it's possible to mark a
 194 line as a statement.  For example if the line statement prefix is configured
 195 to ``#`` the following two examples are equivalent::
 196
 197     <ul>
 198     # for item in seq
 199         <li>{{ item }}</li>
 200     # endfor
 201     </ul>
 202
 203     <ul>
 204     {% for item in seq %}
 205         <li>{{ item }}</li>
 206     {% endfor %}
 207     </ul>
 208
 209 The line statement prefix can appear anywhere on the line as long as no text
 210 precedes it.  For better readability statements that start a block (such as
 211 `for`, `if`, `elif` etc.) may end with a colon::
 212
 213     # for item in seq:
 214         ...
 215     # endfor
 216
 217
 218 .. _template-inheritance:
 219
 220 Template Inheritance
 221 --------------------
 222
 223 The most powerful part of Jinja is template inheritance. Template inheritance
 224 allows you to build a base "skeleton" template that contains all the common
 225 elements of your site and defines **blocks** that child templates can override.
 226
 227 Sounds complicated but is very basic. It's easiest to understand it by starting
 228 with an example.
 229
 230
 231 Base Template
 232 ~~~~~~~~~~~~~
 233
 234 This template, which we'll call ``base.html``, defines a simple HTML skeleton
 235 document that you might use for a simple two-column page. It's the job of
 236 "child" templates to fill the empty blocks with content::
 237
 238     <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
 239     <html lang="en">
 240     <html xmlns="http://www.w3.org/1999/xhtml">
 241     <head>
 242         {% block head %}
 243         <link rel="stylesheet" href="style.css" />
 244         <title>{% block title %}{% endblock %} - My Webpage</title>
 245         {% endblock %}
 246     </head>
 247     <body>
 248         <div id="content">{% block content %}{% endblock %}</div>
 249         <div id="footer">
 250             {% block footer %}
 251             &copy; Copyright 2008 by <a href="http://domain.invalid/">you</a>.
 252             {% endblock %}
 253         </div>
 254     </body>
 255
 256 In this example, the ``{% block %}`` tags define four blocks that child templates
 257 can fill in. All the `block` tag does is to tell the template engine that a
 258 child template may override those portions of the template.
 259
 260 Child Template
 261 ~~~~~~~~~~~~~~
 262
 263 A child template might look like this::
 264
 265     {% extends "base.html" %}
 266     {% block title %}Index{% endblock %}
 267     {% block head %}
 268         {{ super() }}
 269         <style type="text/css">
 270             .important { color: #336699; }
 271         </style>
 272     {% endblock %}
 273     {% block content %}
 274         <h1>Index</h1>
 275         <p class="important">
 276           Welcome on my awsome homepage.
 277         </p>
 278     {% endblock %}
 279
 280 The ``{% extends %}`` tag is the key here. It tells the template engine that
 281 this template "extends" another template.  When the template system evaluates
 282 this template, first it locates the parent.  The extends tag should be the
 283 first tag in the template.  Everything before it is printed out normally and
 284 may cause confusion.  For details about this behavior and how to take
 285 advantage of it, see :ref:`null-master-fallback`.
 286
 287 The filename of the template depends on the template loader.  For example the
 288 :class:`FileSystemLoader` allows you to access other templates by giving the
 289 filename.  You can access templates in subdirectories with an slash::
 290
 291     {% extends "layout/default.html" %}
 292
 293 But this behavior can depend on the application embedding Jinja.  Note that
 294 since the child template doesn't define the ``footer`` block, the value from
 295 the parent template is used instead.
 296
 297 You can't define multiple ``{% block %}`` tags with the same name in the
 298 same template.  This limitation exists because a block tag works in "both"
 299 directions.  That is, a block tag doesn't just provide a hole to fill - it
 300 also defines the content that fills the hole in the *parent*.  If there
 301 were two similarly-named ``{% block %}`` tags in a template, that template's
 302 parent wouldn't know which one of the blocks' content to use.
 303
 304 If you want to print a block multiple times you can however use the special
 305 `self` variable and call the block with that name::
 306
 307     <title>{% block title %}{% endblock %}</title>
 308     <h1>{{ self.title() }}</h1>
 309     {% block body %}{% endblock %}
 310
 311
 312 Unlike Python Jinja does not support multiple inheritance.  So you can only have
 313 one extends tag called per rendering.
 314
 315
 316 Super Blocks
 317 ~~~~~~~~~~~~
 318
 319 It's possible to render the contents of the parent block by calling `super`.
 320 This gives back the results of the parent block::
 321
 322     {% block sidebar %}
 323         <h3>Table Of Contents</h3>
 324         ...
 325         {{ super() }}
 326     {% endblock %}
 327
 328
 329 HTML Escaping
 330 -------------
 331
 332 When generating HTML from templates, there's always a risk that a variable will
 333 include characters that affect the resulting HTML.  There are two approaches:
 334 manually escaping each variable or automatically escaping everything by default.
 335
 336 Jinja supports both, but what is used depends on the application configuration.
 337 The default configuaration is no automatic escaping for various reasons:
 338
 339 -   escaping everything except of safe values will also mean that Jinja is
 340     escaping variables known to not include HTML such as numbers which is
 341     a huge performance hit.
 342
 343 -   The information about the safety of a variable is very fragile.  It could
 344     happen that by coercing safe and unsafe values the return value is double
 345     escaped HTML.
 346
 347 Working with Manual Escaping
 348 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 349
 350 If manual escaping is enabled it's **your** responsibility to escape
 351 variables if needed.  What to escape?  If you have a variable that *may*
 352 include any of the following chars (``>``, ``<``, ``&``, or ``"``) you
 353 **have to** escape it unless the variable contains well-formed and trusted
 354 HTML.  Escaping works by piping the variable through the ``|e`` filter:
 355 ``{{ user.username|e }}``.
 356
 357 Working with Automatic Escaping
 358 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 359
 360 When automatic escaping is enabled everything is escaped by default except
 361 for values explicitly marked as safe.  Those can either be marked by the
 362 application or in the template by using the `|safe` filter.  The main
 363 problem with this approach is that Python itself doesn't have the concept
 364 of tainted values so the information if a value is safe or unsafe can get
 365 lost.  If the information is lost escaping will take place which means that
 366 you could end up with double escaped contents.
 367
 368 Double escaping is easy to avoid however, just rely on the tools Jinja2
 369 provides and don't use builtin Python constructs such as the string modulo
 370 operator.
 371
 372 Functions returning template data (macros, `super`, `self.BLOCKNAME`) return
 373 safe markup always.
 374
 375 String literals in templates with automatic escaping are considered unsafe
 376 too.  The reason for this is that the safe string is an extension to Python
 377 and not every library will work properly with it.
 378
 379
 380 List of Control Structures
 381 --------------------------
 382
 383 A control structure refers to all those things that control the flow of a
 384 program - conditionals (i.e. if/elif/else), for-loops, as well as things like
 385 macros and blocks.  Control structures appear inside ``{% ... %}`` blocks
 386 in the default syntax.
 387
 388 For
 389 ~~~
 390
 391 Loop over each item in a sequence.  For example, to display a list of users
 392 provided in a variable called `users`::
 393
 394     <h1>Members</h1>
 395     <ul>
 396     {% for user in users %}
 397       <li>{{ user.username|e }}</li>
 398     {% endfor %}
 399     </ul>
 400
 401 Inside of a for loop block you can access some special variables:
 402
 403 +-----------------------+---------------------------------------------------+
 404 | Variable              | Description                                       |
 405 +=======================+===================================================+
 406 | `loop.index`          | The current iteration of the loop. (1 indexed)    |
 407 +-----------------------+---------------------------------------------------+
 408 | `loop.index0`         | The current iteration of the loop. (0 indexed)    |
 409 +-----------------------+---------------------------------------------------+
 410 | `loop.revindex`       | The number of iterations from the end of the loop |
 411 |                       | (1 indexed)                                       |
 412 +-----------------------+---------------------------------------------------+
 413 | `loop.revindex0`      | The number of iterations from the end of the loop |
 414 |                       | (0 indexed)                                       |
 415 +-----------------------+---------------------------------------------------+
 416 | `loop.first`          | True if first iteration.                          |
 417 +-----------------------+---------------------------------------------------+
 418 | `loop.last`           | True if last iteration.                           |
 419 +-----------------------+---------------------------------------------------+
 420 | `loop.length`         | The number of items in the sequence.              |
 421 +-----------------------+---------------------------------------------------+
 422 | `loop.cycle`          | A helper function to cycle between a list of      |
 423 |                       | sequences.  See the explanation below.            |
 424 +-----------------------+---------------------------------------------------+
 425
 426 Within a for-loop, it's possible to cycle among a list of strings/variables
 427 each time through the loop by using the special `loop.cycle` helper::
 428
 429     {% for row in rows %}
 430         <li class="{{ loop.cycle('odd', 'even') }}">{{ row }}</li>
 431     {% endfor %}
 432
 433 .. _loop-filtering:
 434
 435 Unlike in Python it's not possible to `break` or `continue` in a loop.  You
 436 can however filter the sequence during iteration which allows you to skip
 437 items.  The following example skips all the users which are hidden::
 438
 439     {% for user in users if not user.hidden %}
 440         <li>{{ user.username|e }}</li>
 441     {% endfor %}
 442
 443 The advantage is that the special `loop` variable will count correctly thus
 444 not counting the users not iterated over.
 445
 446 If no iteration took place because the sequence was empty or the filtering
 447 removed all the items from the sequence you can render a replacement block
 448 by using `else`::
 449
 450     <ul>
 451     {% for user in users %}
 452         <li>{{ user.username|e }}</li>
 453     {% else %}
 454         <li><em>no users found</em></li>
 455     {% endif %}
 456     </ul>
 457
 458 It is also possible to use loops recursively.  This is useful if you are
 459 dealing with recursive data such as sitemaps.  To use loops recursively you
 460 basically have to add the `recursive` modifier to the loop definition and
 461 call the `loop` variable with the new iterable where you want to recurse.
 462
 463 The following example implements a sitemap with recursive loops::
 464
 465     <ul class="sitemap">
 466     {%- for item in sitemap recursive %}
 467         <li><a href="{{ item.href|e }}">{{ item.title }}</a>
 468         {%- if item.children -%}
 469             <ul class="submenu">{{ loop(item.children) }}</ul>
 470         {%- endif %}</li>
 471     {%- endfor %}
 472     </ul>
 473
 474
 475 If
 476 ~~
 477
 478 The `if` statement in Jinja is comparable with the if statements of Python.
 479 In the simplest form you can use it to test if a variable is defined, not
 480 empty or not false::
 481
 482     {% if users %}
 483     <ul>
 484     {% for user in users %}
 485         <li>{{ user.username|e }}</li>
 486     {% endfor %}
 487     </ul>
 488     {% endif %}
 489
 490 For multiple branches `elif` and `else` can be used like in Python.  You can
 491 use more complex :ref:`expressions` there too::
 492
 493     {% if kenny.sick %}
 494         Kenny is sick.
 495     {% elif kenny.dead %}
 496         You killed Kenny!  You bastard!!!
 497     {% else %}
 498         Kenny looks okay --- so far
 499     {% endif %}
 500
 501 If can also be used as :ref:`inline expression <if-expression>` and for
 502 :ref:`loop filtering <loop-filtering>`.
 503
 504
 505 Macros
 506 ~~~~~~
 507
 508 Macros are comparable with functions in regular programming languages.  They
 509 are useful to put often used idioms into reusable functions to not repeat
 510 yourself.
 511
 512 Here a small example of a macro that renders a form element::
 513
 514     {% macro input(name, value='', type='text', size=20) -%}
 515         <input type="{{ type }}" name="{{ name }}" value="{{
 516             value|e }}" size="{{ size }}">
 517     {%- endmacro %}
 518
 519 The macro can then be called like a function in the namespace::
 520
 521     <p>{{ input('username') }}</p>
 522     <p>{{ input('password', type='password') }}</p>
 523
 524 If the macro was defined in a different template you have to
 525 :ref:`import <import>` it first.
 526
 527 Inside macros you have access to three special variables:
 528
 529 `varargs`
 530     If more positional arguments are passed to the macro than accepted by the
 531     macro they end up in the special `varargs` variable as list of values.
 532
 533 `kwargs`
 534     Like `varargs` but for keyword arguments.  All unconsumed keyword
 535     arguments are stored in this special variable.
 536
 537 `caller`
 538     If the macro was called from a :ref:`call<call>` tag the caller is stored
 539     in this variable as macro which can be called.
 540
 541 Macros also expose some of their internal details.  The following attributes
 542 are available on a macro object:
 543
 544 `name`
 545     The name of the macro.  ``{{ input.name }}`` will print ``input``.
 546
 547 `arguments`
 548     A tuple of the names of arguments the macro accepts.
 549
 550 `defaults`
 551     A tuple of default values.
 552
 553 `catch_kwargs`
 554     This is `true` if the macro accepts extra keyword arguments (ie: accesses
 555     the special `kwargs` variable).
 556
 557 `catch_varargs`
 558     This is `true` if the macro accepts extra positional arguments (ie:
 559     accesses the special `varargs` variable).
 560
 561 `caller`
 562     This is `true` if the macro accesses the special `caller` variable and may
 563     be called from a :ref:`call<call>` tag.
 564
 565
 566 .. _call:
 567
 568 Call
 569 ~~~~
 570
 571 In some cases it can be useful to pass a macro to another macro.  For this
 572 purpose you can use the special `call` block.  The following example shows
 573 a macro that takes advantage of the call functionality and how it can be
 574 used::
 575
 576     {% macro render_dialog(title, class='dialog') -%}
 577         <div class="{{ class }}">
 578             <h2>{{ title }}</h2>
 579             <div class="contents">
 580                 {{ caller() }}
 581             </div>
 582         </div>
 583     {%- endmacro %}
 584
 585     {% call render_dialog('Hello World') %}
 586         This is a simple dialog rendered by using a macro and
 587         a call block.
 588     {% endcall %}
 589
 590 It's also possible to pass arguments back to the call block.  This makes it
 591 useful as replacement for loops.  It is however not possible to call a
 592 call block with another call block.
 593
 594 Here an example of how a call block can be used with arguments::
 595
 596     {% macro dump_users(users) -%}
 597         <ul>
 598         {%- for user in users %}
 599             <li><p>{{ user.username|e }}</p>{{ caller(user) }}</li>
 600         {%- endfor %}
 601         </ul>
 602     {%- endmacro %}
 603
 604     {% call(user) dump_users(list_of_user) %}
 605         <dl>
 606             <dl>Realname</dl>
 607             <dd>{{ user.realname|e }}</dd>
 608             <dl>Description</dl>
 609             <dd>{{ user.description }}</dd>
 610         </dl>
 611     {% endcall %}
 612
 613
 614 Assignments
 615 ~~~~~~~~~~~
 616
 617 Inside code blocks you can also assign values to variables.  Assignments at
 618 top level (outside of blocks, macros or loops) are exported from the template
 619 like top level macros and can be imported by other templates.
 620
 621 Assignments use the `set` tag and can have multiple targets::
 622
 623     {% set navigation = [('index.html', 'Index'), ('about.html', 'About')] %}
 624     {% set key, value = call_something() %}
 625
 626
 627 Extends
 628 ~~~~~~~
 629
 630 The `extends` tag can be used to extend a template from another one.  You
 631 can have multiple of them in a file but only one of them may be executed
 632 at the time.  There is no support for multiple inheritance.  See the section
 633 about :ref:`template-inheritance` above.
 634
 635
 636 Block
 637 ~~~~~
 638
 639 Blocks are used for inheritance and act as placeholders and replacements
 640 at the same time.  They are documented in detail as part of the section
 641 about :ref:`template-inheritance`.
 642
 643
 644 Include
 645 ~~~~~~~
 646
 647 The `include` statement is useful to include a template and return the
 648 rendered contents of that file into the current namespace::
 649
 650     {% include 'header.html' %}
 651         Body
 652     {% include 'footer.html' %}
 653
 654 Included templates have access to the variables of the active context by
 655 default.  For more details about context behavior of imports and includes
 656 see :ref:`import-visibility`.
 657
 658 .. _import:
 659
 660 Import
 661 ~~~~~~
 662
 663 Jinja2 supports putting often used code into macros.  These macros can go into
 664 different templates and get imported from there.  This works similar to the
 665 import statements in Python.  It's important to know that imports are cached
 666 and imported templates don't have access to the current template variables,
 667 just the globals by defualt.  For more details about context behavior of
 668 imports and includes see :ref:`import-visibility`.
 669
 670 There are two ways to import templates.  You can import the complete template
 671 into a variable or request specific macros / exported variables from it.
 672
 673 Imagine we have a helper module that renders forms (called `forms.html`)::
 674
 675     {% macro input(name, value='', type='text') -%}
 676         <input type="{{ type }}" value="{{ value|e }}" name="{{ name }}">
 677     {%- endmacro %}
 678
 679     {%- macro textarea(name, value='', rows=10, cols=40) -%}
 680         <textarea name="{{ name }}" rows="{{ rows }}" cols="{{ cols
 681             }}">{{ value|e }}</textarea>
 682     {%- endmacro %}
 683
 684 The easiest and most flexible is importing the whole module into a variable.
 685 That way you can access the attributes::
 686
 687     {% import 'forms.html' as forms %}
 688     <dl>
 689         <dt>Username</dt>
 690         <dd>{{ forms.input('username') }}</dd>
 691         <dt>Password</dt>
 692         <dd>{{ forms.input('password', type='password') }}</dd>
 693     </dl>
 694     <p>{{ forms.textarea('comment') }}</p>
 695
 696
 697 Alternatively you can import names from the template into the current
 698 namespace::
 699
 700     {% from 'forms.html' import input as input_field, textarea %}
 701     <dl>
 702         <dt>Username</dt>
 703         <dd>{{ input_field('username') }}</dd>
 704         <dt>Password</dt>
 705         <dd>{{ input_field('password', type='password') }}</dd>
 706     </dl>
 707     <p>{{ textarea('comment') }}</p>
 708
 709
 710 .. _import-visibility:
 711
 712 Import Context Behavior
 713 -----------------------
 714
 715 Per default included templates are passed the current context and imported
 716 templates not.  The reason for this is that imports unlike includes are
 717 cached as imports are often used just as a module that holds macros.
 718
 719 This however can be changed of course explicitly.  By adding `with context`
 720 or `without context` to the import/include directive the current context
 721 can be passed to the template and caching is disabled automatically.
 722
 723 Here two examples::
 724
 725     {% from 'forms.html' import input with context %}
 726     {% include 'header.html' without context %}
 727
 728
 729 .. _expressions:
 730
 731 Expressions
 732 -----------
 733
 734 Jinja allows basic expressions everywhere.  These work very similar to regular
 735 Python and even if you're not working with Python you should feel comfortable
 736 with it.
 737
 738 Literals
 739 ~~~~~~~~
 740
 741 The simplest form of expressions are literals.  Literals are representations
 742 for Python objects such as strings and numbers.  The following literals exist:
 743
 744 "Hello World":
 745     Everything between two double or single quotes is a string.  They are
 746     useful whenever you need a string in the template (for example as
 747     arguments to function calls, filters or just to extend or include a
 748     template).
 749
 750 42 / 42.23:
 751     Integers and floating point numbers are created by just writing the
 752     number down.  If a dot is present the number is a float, otherwise an
 753     integer.  Keep in mind that for Python ``42`` and ``42.0`` is something
 754     different.
 755
 756 ['list', 'of', 'objects']:
 757     Everything between two brackets is a list.  Lists are useful to store
 758     sequential data in or to iterate over them.  For example you can easily
 759     create a list of links using lists and tuples with a for loop::
 760
 761         <ul>
 762         {% for href, caption in [('index.html', 'Index'), ('about.html', 'About'),
 763                                  ('downloads.html', 'Downloads')] %}
 764             <li><a href="{{ href }}">{{ caption }}</a></li>
 765         {% endfor %}
 766         </ul>
 767
 768 ('tuple', 'of', 'values'):
 769     Tuples are like lists, just that you can't modify them.  If the tuple
 770     only has one item you have to end it with a comma.  Tuples are usually
 771     used to represent items of two or more elements.  See the example above
 772     for more details.
 773
 774 {'dict': 'of', 'key': 'and', 'value': 'pairs'}:
 775     A dict in Python is a structure that combines keys and values.  Keys must
 776     be unique and always have exactly one value.  Dicts are rarely used in
 777     templates, they are useful in some rare cases such as the :func:`xmlattr`
 778     filter.
 779
 780 true / false:
 781     true is always true and false is always false.  Keep in mind that those
 782     literals are lowercase!
 783
 784 Math
 785 ~~~~
 786
 787 Jinja allows you to calculate with values.  This is rarely useful in templates
 788 but exists for completeness sake.  The following operators are supported:
 789
 790 \+
 791     Adds two objects with each other.  Usually numbers but if both objects are
 792     strings or lists you can concatenate them this way.  This however is not
 793     the preferred way to concatenate strings!  For string concatenation have
 794     a look at the ``~`` operator.  ``{{ 1 + 1 }}`` is ``2``.
 795
 796 \-
 797     Substract two numbers from each other.  ``{{ 3 - 2 }}`` is ``1``.
 798
 799 /
 800     Divide two numbers.  The return value will be a floating point number.
 801     ``{{ 1 / 2 }}`` is ``{{ 0.5 }}``.
 802
 803 //
 804     Divide two numbers and return the truncated integer result.
 805     ``{{ 20 / 7 }}`` is ``2``.
 806
 807 %
 808     Calculate the remainder of an integer division between the left and right
 809     operand.  ``{{ 11 % 7 }}`` is ``4``.
 810
 811 \*
 812     Multiply the left operand with the right one.  ``{{ 2 * 2 }}`` would
 813     return ``4``.  This can also be used to repeat string multiple times.
 814     ``{{ '=' * 80 }}`` would print a bar of 80 equal signs.
 815
 816 \**
 817     Raise the left operand to the power of the right operand.  ``{{ 2**3 }}``
 818     would return ``8``.
 819
 820 Logic
 821 ~~~~~
 822
 823 For `if` statements / `for` filtering or `if` expressions it can be useful to
 824 combine group multiple expressions:
 825
 826 and
 827     Return true if the left and the right operand is true.
 828
 829 or
 830     Return true if the left or the right operand is true.
 831
 832 not
 833     negate a statement (see below).
 834
 835 (expr)
 836     group an expression.
 837
 838 Note that there is no support for any bit operations or something similar.
 839
 840 -   special note regarding ``not``: The ``is`` and ``in`` operators support
 841     negation using an infix notation too: ``foo is not bar`` and
 842     ``foo not in bar`` instead of ``not foo is bar`` and ``not foo in bar``.
 843     All other expressions require a prefix notation: ``not (foo and bar).``
 844
 845
 846 Other Operators
 847 ~~~~~~~~~~~~~~~
 848
 849 The following operators are very useful but don't fit into any of the other
 850 two categories:
 851
 852 in
 853     Perform sequence / mapping containment test.  Returns true if the left
 854     operand is contained in the right.  ``{{ 1 in [1, 2, 3] }}`` would for
 855     example return true.
 856
 857 is
 858     Performs a :ref:`test <tests>`.
 859
 860 \|
 861     Applies a :ref:`filter <filters>`.
 862
 863 ~
 864     Converts all operands into strings and concatenates them.
 865     ``{{ "Hello " ~ name ~ "!" }}`` would return (assuming `name` is
 866     ``'John'``) ``Hello John!``.
 867
 868 ()
 869     Call a callable: ``{{ post.render() }}``.  Inside of the parentheses you
 870     can use arguments and keyword arguments like in python:
 871     ``{{ post.render(user, full=true) }}``.
 872
 873 . / []
 874     Get an attribute of an object.  (See :ref:`variables`)
 875
 876
 877 .. _if-expression:
 878
 879 If Expression
 880 ~~~~~~~~~~~~~
 881
 882 It is also possible to use inline `if` expressions.  These are useful in some
 883 situations.  For example you can use this to extend from one template if a
 884 variable is defined, otherwise from the default layout template::
 885
 886     {% extends layout_template if layout_template is defined else 'master.html' %}
 887
 888 The general syntax is ``<do something> if <something is true> else <do
 889 something else>``.
 890
 891
 892 .. _builtin-filters:
 893
 894 List of Builtin Filters
 895 -----------------------
 896
 897 .. jinjafilters::
 898
 899
 900 .. _builtin-tests:
 901
 902 List of Builtin Tests
 903 ---------------------
 904
 905 .. jinjatests::
 906
 907
 908 List of Global Functions
 909 ------------------------
 910
 911 The following functions are available in the global scope by default:
 912
 913 .. function:: range([start,] stop[, step])
 914
 915     Return a list containing an arithmetic progression of integers.
 916     range(i, j) returns [i, i+1, i+2, ..., j-1]; start (!) defaults to 0.
 917     When step is given, it specifies the increment (or decrement).
 918     For example, range(4) returns [0, 1, 2, 3].  The end point is omitted!
 919     These are exactly the valid indices for a list of 4 elements.
 920
 921     This is useful to repeat a template block multiple times for example
 922     to fill a list.  Imagine you have 7 users in the list but you want to
 923     render three empty items to enforce a height with CSS::
 924
 925         <ul>
 926         {% for user in users %}
 927             <li>{{ user.username }}</li>
 928         {% endfor %}
 929         {% for number in range(10 - users|count) %}
 930             <li class="empty"><span>...</span></li>
 931         {% endfor %}
 932         </ul>
 933
 934 .. function:: lipsum(n=5, html=True, min=20, max=100)
 935
 936     Generates some lorem ipsum for the template.  Per default five paragraphs
 937     with HTML are generated each paragraph between 20 and 100 words.  If html
 938     is disabled regular text is returned.  This is useful to generate simple
 939     contents for layout testing.
 940
 941 .. function:: dict(\**items)
 942
 943     A convenient alternative to dict literals.  ``{'foo': 'bar'}`` is the same
 944     as ``dict(foo='bar')``.
 945
 946
 947 Extensions
 948 ----------
 949
 950 The following sections cover the built-in Jinja2 extensions that may be
 951 enabled by the application.  The application could also provide further
 952 extensions not covered by this documentation.  In that case there should
 953 be a separate document explaining the extensions.
 954
 955 .. _i18n-in-templates:
 956
 957 i18n
 958 ~~~~
 959
 960 If the i18n extension is enabled it's possible to mark parts in the template
 961 as translatable.  To mark a section as translatable you can use `trans`::
 962
 963     <p>{% trans %}Hello {{ user }}!{% endtrans %}</p>
 964
 965 To translate a template expression --- say, using template filters or just
 966 accessing an attribute of an object --- you need to bind the expression to a
 967 name for use within the translation block::
 968
 969     <p>{% trans user=user.username %}Hello {{ user }}!{% endtrans %}</p>
 970
 971 If you need to bind more than one expression inside a `trans` tag, separate
 972 the pieces with a comma (``,``)::
 973
 974     {% trans book_title=book.title, author=author.name %}
 975     This is {{ book_title }} by {{ author }}
 976     {% endtrans %}
 977
 978 Inside trans tags no statements are allowed, only variable tags are.
 979
 980 To pluralize, specify both the singular and plural forms with the `pluralize`
 981 tag, which appears between `trans` and `endtrans`::
 982
 983     {% trans count=list|length %}
 984     There is {{ count }} {{ name }} object.
 985     {% pluralize %}
 986     There are {{ count }} {{ name }} objects.
 987     {% endtrans %}
 988
 989 Per default the first variable in a block is used to determine the correct
 990 singular or plural form.  If that doesn't work out you can specify the name
 991 which should be used for pluralizing by adding it as parameter to `pluralize`::
 992
 993     {% trans ..., user_count=users|length %}...
 994     {% pluralize user_count %}...{% endtrans %}
 995
 996 It's also possible to translate strings in expressions.  For that purpose
 997 three functions exist:
 998
 999 _   `gettext`: translate a single string
1000 -   `ngettext`: translate a pluralizable string
1001 -   `_`: alias for `gettext`
1002
1003 For example you can print a translated string easily this way::
1004
1005     {{ _('Hello World!') }}
1006
1007 To use placeholders you can use the `format` filter::
1008
1009     {{ _('Hello %(user)s!')|format(user=user.username) }}
1010         or
1011     {{ _('Hello %s')|format(user.username) }}
1012
1013 For multiple placeholders always use keyword arguments to `format` as other
1014 languages may not use the words in the same order.
1015
1016
1017 do
1018 ~~
1019
1020 If the expression-statement extension is loaded a tag called `do` is available
1021 that works exactly like the regular variable expression (``{{ ... }}``) just
1022 that it doesn't print anything.  This can be used to modify lists::
1023
1024     {% do navigation.append('a string') %}