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.  Generally speaking a call block works
 592 exactly like an macro, just that it doesn't have a name.
 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 Macros and variables starting with one ore more underscores are private and
 710 cannot be imported.
 711
 712
 713 .. _import-visibility:
 714
 715 Import Context Behavior
 716 -----------------------
 717
 718 Per default included templates are passed the current context and imported
 719 templates not.  The reason for this is that imports unlike includes are
 720 cached as imports are often used just as a module that holds macros.
 721
 722 This however can be changed of course explicitly.  By adding `with context`
 723 or `without context` to the import/include directive the current context
 724 can be passed to the template and caching is disabled automatically.
 725
 726 Here two examples::
 727
 728     {% from 'forms.html' import input with context %}
 729     {% include 'header.html' without context %}
 730
 731
 732 .. _expressions:
 733
 734 Expressions
 735 -----------
 736
 737 Jinja allows basic expressions everywhere.  These work very similar to regular
 738 Python and even if you're not working with Python you should feel comfortable
 739 with it.
 740
 741 Literals
 742 ~~~~~~~~
 743
 744 The simplest form of expressions are literals.  Literals are representations
 745 for Python objects such as strings and numbers.  The following literals exist:
 746
 747 "Hello World":
 748     Everything between two double or single quotes is a string.  They are
 749     useful whenever you need a string in the template (for example as
 750     arguments to function calls, filters or just to extend or include a
 751     template).
 752
 753 42 / 42.23:
 754     Integers and floating point numbers are created by just writing the
 755     number down.  If a dot is present the number is a float, otherwise an
 756     integer.  Keep in mind that for Python ``42`` and ``42.0`` is something
 757     different.
 758
 759 ['list', 'of', 'objects']:
 760     Everything between two brackets is a list.  Lists are useful to store
 761     sequential data in or to iterate over them.  For example you can easily
 762     create a list of links using lists and tuples with a for loop::
 763
 764         <ul>
 765         {% for href, caption in [('index.html', 'Index'), ('about.html', 'About'),
 766                                  ('downloads.html', 'Downloads')] %}
 767             <li><a href="{{ href }}">{{ caption }}</a></li>
 768         {% endfor %}
 769         </ul>
 770
 771 ('tuple', 'of', 'values'):
 772     Tuples are like lists, just that you can't modify them.  If the tuple
 773     only has one item you have to end it with a comma.  Tuples are usually
 774     used to represent items of two or more elements.  See the example above
 775     for more details.
 776
 777 {'dict': 'of', 'key': 'and', 'value': 'pairs'}:
 778     A dict in Python is a structure that combines keys and values.  Keys must
 779     be unique and always have exactly one value.  Dicts are rarely used in
 780     templates, they are useful in some rare cases such as the :func:`xmlattr`
 781     filter.
 782
 783 true / false:
 784     true is always true and false is always false.  Keep in mind that those
 785     literals are lowercase!
 786
 787 Math
 788 ~~~~
 789
 790 Jinja allows you to calculate with values.  This is rarely useful in templates
 791 but exists for completeness sake.  The following operators are supported:
 792
 793 \+
 794     Adds two objects with each other.  Usually numbers but if both objects are
 795     strings or lists you can concatenate them this way.  This however is not
 796     the preferred way to concatenate strings!  For string concatenation have
 797     a look at the ``~`` operator.  ``{{ 1 + 1 }}`` is ``2``.
 798
 799 \-
 800     Substract two numbers from each other.  ``{{ 3 - 2 }}`` is ``1``.
 801
 802 /
 803     Divide two numbers.  The return value will be a floating point number.
 804     ``{{ 1 / 2 }}`` is ``{{ 0.5 }}``.
 805
 806 //
 807     Divide two numbers and return the truncated integer result.
 808     ``{{ 20 / 7 }}`` is ``2``.
 809
 810 %
 811     Calculate the remainder of an integer division between the left and right
 812     operand.  ``{{ 11 % 7 }}`` is ``4``.
 813
 814 \*
 815     Multiply the left operand with the right one.  ``{{ 2 * 2 }}`` would
 816     return ``4``.  This can also be used to repeat string multiple times.
 817     ``{{ '=' * 80 }}`` would print a bar of 80 equal signs.
 818
 819 \**
 820     Raise the left operand to the power of the right operand.  ``{{ 2**3 }}``
 821     would return ``8``.
 822
 823 Logic
 824 ~~~~~
 825
 826 For `if` statements / `for` filtering or `if` expressions it can be useful to
 827 combine group multiple expressions:
 828
 829 and
 830     Return true if the left and the right operand is true.
 831
 832 or
 833     Return true if the left or the right operand is true.
 834
 835 not
 836     negate a statement (see below).
 837
 838 (expr)
 839     group an expression.
 840
 841 Note that there is no support for any bit operations or something similar.
 842
 843 -   special note regarding ``not``: The ``is`` and ``in`` operators support
 844     negation using an infix notation too: ``foo is not bar`` and
 845     ``foo not in bar`` instead of ``not foo is bar`` and ``not foo in bar``.
 846     All other expressions require a prefix notation: ``not (foo and bar).``
 847
 848
 849 Other Operators
 850 ~~~~~~~~~~~~~~~
 851
 852 The following operators are very useful but don't fit into any of the other
 853 two categories:
 854
 855 in
 856     Perform sequence / mapping containment test.  Returns true if the left
 857     operand is contained in the right.  ``{{ 1 in [1, 2, 3] }}`` would for
 858     example return true.
 859
 860 is
 861     Performs a :ref:`test <tests>`.
 862
 863 \|
 864     Applies a :ref:`filter <filters>`.
 865
 866 ~
 867     Converts all operands into strings and concatenates them.
 868     ``{{ "Hello " ~ name ~ "!" }}`` would return (assuming `name` is
 869     ``'John'``) ``Hello John!``.
 870
 871 ()
 872     Call a callable: ``{{ post.render() }}``.  Inside of the parentheses you
 873     can use arguments and keyword arguments like in python:
 874     ``{{ post.render(user, full=true) }}``.
 875
 876 . / []
 877     Get an attribute of an object.  (See :ref:`variables`)
 878
 879
 880 .. _if-expression:
 881
 882 If Expression
 883 ~~~~~~~~~~~~~
 884
 885 It is also possible to use inline `if` expressions.  These are useful in some
 886 situations.  For example you can use this to extend from one template if a
 887 variable is defined, otherwise from the default layout template::
 888
 889     {% extends layout_template if layout_template is defined else 'master.html' %}
 890
 891 The general syntax is ``<do something> if <something is true> else <do
 892 something else>``.
 893
 894
 895 .. _builtin-filters:
 896
 897 List of Builtin Filters
 898 -----------------------
 899
 900 .. jinjafilters::
 901
 902
 903 .. _builtin-tests:
 904
 905 List of Builtin Tests
 906 ---------------------
 907
 908 .. jinjatests::
 909
 910
 911 List of Global Functions
 912 ------------------------
 913
 914 The following functions are available in the global scope by default:
 915
 916 .. function:: range([start,] stop[, step])
 917
 918     Return a list containing an arithmetic progression of integers.
 919     range(i, j) returns [i, i+1, i+2, ..., j-1]; start (!) defaults to 0.
 920     When step is given, it specifies the increment (or decrement).
 921     For example, range(4) returns [0, 1, 2, 3].  The end point is omitted!
 922     These are exactly the valid indices for a list of 4 elements.
 923
 924     This is useful to repeat a template block multiple times for example
 925     to fill a list.  Imagine you have 7 users in the list but you want to
 926     render three empty items to enforce a height with CSS::
 927
 928         <ul>
 929         {% for user in users %}
 930             <li>{{ user.username }}</li>
 931         {% endfor %}
 932         {% for number in range(10 - users|count) %}
 933             <li class="empty"><span>...</span></li>
 934         {% endfor %}
 935         </ul>
 936
 937 .. function:: lipsum(n=5, html=True, min=20, max=100)
 938
 939     Generates some lorem ipsum for the template.  Per default five paragraphs
 940     with HTML are generated each paragraph between 20 and 100 words.  If html
 941     is disabled regular text is returned.  This is useful to generate simple
 942     contents for layout testing.
 943
 944 .. function:: dict(\**items)
 945
 946     A convenient alternative to dict literals.  ``{'foo': 'bar'}`` is the same
 947     as ``dict(foo='bar')``.
 948
 949
 950 Extensions
 951 ----------
 952
 953 The following sections cover the built-in Jinja2 extensions that may be
 954 enabled by the application.  The application could also provide further
 955 extensions not covered by this documentation.  In that case there should
 956 be a separate document explaining the extensions.
 957
 958 .. _i18n-in-templates:
 959
 960 i18n
 961 ~~~~
 962
 963 If the i18n extension is enabled it's possible to mark parts in the template
 964 as translatable.  To mark a section as translatable you can use `trans`::
 965
 966     <p>{% trans %}Hello {{ user }}!{% endtrans %}</p>
 967
 968 To translate a template expression --- say, using template filters or just
 969 accessing an attribute of an object --- you need to bind the expression to a
 970 name for use within the translation block::
 971
 972     <p>{% trans user=user.username %}Hello {{ user }}!{% endtrans %}</p>
 973
 974 If you need to bind more than one expression inside a `trans` tag, separate
 975 the pieces with a comma (``,``)::
 976
 977     {% trans book_title=book.title, author=author.name %}
 978     This is {{ book_title }} by {{ author }}
 979     {% endtrans %}
 980
 981 Inside trans tags no statements are allowed, only variable tags are.
 982
 983 To pluralize, specify both the singular and plural forms with the `pluralize`
 984 tag, which appears between `trans` and `endtrans`::
 985
 986     {% trans count=list|length %}
 987     There is {{ count }} {{ name }} object.
 988     {% pluralize %}
 989     There are {{ count }} {{ name }} objects.
 990     {% endtrans %}
 991
 992 Per default the first variable in a block is used to determine the correct
 993 singular or plural form.  If that doesn't work out you can specify the name
 994 which should be used for pluralizing by adding it as parameter to `pluralize`::
 995
 996     {% trans ..., user_count=users|length %}...
 997     {% pluralize user_count %}...{% endtrans %}
 998
 999 It's also possible to translate strings in expressions.  For that purpose
1000 three functions exist:
1001
1002 _   `gettext`: translate a single string
1003 -   `ngettext`: translate a pluralizable string
1004 -   `_`: alias for `gettext`
1005
1006 For example you can print a translated string easily this way::
1007
1008     {{ _('Hello World!') }}
1009
1010 To use placeholders you can use the `format` filter::
1011
1012     {{ _('Hello %(user)s!')|format(user=user.username) }}
1013         or
1014     {{ _('Hello %s')|format(user.username) }}
1015
1016 For multiple placeholders always use keyword arguments to `format` as other
1017 languages may not use the words in the same order.
1018
1019
1020 do
1021 ~~
1022
1023 If the expression-statement extension is loaded a tag called `do` is available
1024 that works exactly like the regular variable expression (``{{ ... }}``) just
1025 that it doesn't print anything.  This can be used to modify lists::
1026
1027     {% do navigation.append('a string') %}
1028
1029
1030 Loop Controls
1031 ~~~~~~~~~~~~~
1032
1033 If the application enables the :ref:`loopcontrols-extension` it's possible to
1034 use `break` and `continue` in loops.  When `break` is reached, the loop is
1035 terminated, if `continue` is eached the processing is stopped and continues
1036 with the next iteration.
1037
1038 Here a loop that skips every second item::
1039
1040     {% for user in users %}
1041         {%- if loop.index is even %}{% continue %}{% endif %}
1042         ...
1043     {% endfor %}
1044
1045 Likewise a look that stops processing after the 10th iteration::
1046
1047     {% for user in users %}
1048         {%- if loop.index >= 10 %}{% break %}{% endif %}
1049     {%- endfor %}