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     # endif
 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.
 285
 286 The filename of the template depends on the template loader.  For example the
 287 :class:`FileSystemLoader` allows you to access other templates by giving the
 288 filename.  You can access templates in subdirectories with an slash::
 289
 290     {% extends "layout/default.html" %}
 291
 292 But this behavior can depend on the application embedding Jinja.  Note that
 293 since the child template doesn't define the ``footer`` block, the value from
 294 the parent template is used instead.
 295
 296 You can't define multiple ``{% block %}`` tags with the same name in the
 297 same template.  This limitation exists because a block tag works in "both"
 298 directions.  That is, a block tag doesn't just provide a hole to fill - it
 299 also defines the content that fills the hole in the *parent*.  If there
 300 were two similarly-named ``{% block %}`` tags in a template, that template's
 301 parent wouldn't know which one of the blocks' content to use.
 302
 303 If you want to print a block multiple times you can however use the special
 304 `self` variable and call the block with that name::
 305
 306     <title>{% block title %}{% endblock %}</title>
 307     <h1>{{ self.title() }}</h1>
 308     {% block body %}{% endblock %}
 309
 310
 311 Unlike Python Jinja does not support multiple inheritance.  So you can only have
 312 one extends tag called per rendering.
 313
 314
 315 Super Blocks
 316 ~~~~~~~~~~~~
 317
 318 It's possible to render the contents of the parent block by calling `super`.
 319 This gives back the results of the parent block::
 320
 321     {% block sidebar %}
 322         <h3>Table Of Contents</h3>
 323         ...
 324         {{ super() }}
 325     {% endblock %}
 326
 327
 328 HTML Escaping
 329 -------------
 330
 331 When generating HTML from templates, there's always a risk that a variable will
 332 include characters that affect the resulting HTML.  There are two approaches:
 333 manually escaping each variable or automatically escaping everything by default.
 334
 335 Jinja supports both, but what is used depends on the application configuration.
 336 The default configuaration is no automatic escaping for various reasons:
 337
 338 -   escaping everything except of safe values will also mean that Jinja is
 339     escaping variables known to not include HTML such as numbers which is
 340     a huge performance hit.
 341
 342 -   The information about the safety of a variable is very fragile.  It could
 343     happen that by coercing safe and unsafe values the return value is double
 344     escaped HTML.
 345
 346 Working with Manual Escaping
 347 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 348
 349 If manual escaping is enabled it's **your** responsibility to escape
 350 variables if needed.  What to escape?  If you have a variable that *may*
 351 include any of the following chars (``>``, ``<``, ``&``, or ``"``) you
 352 **have to** escape it unless the variable contains well-formed and trusted
 353 HTML.  Escaping works by piping the variable through the ``|e`` filter:
 354 ``{{ user.username|e }}``.
 355
 356 Working with Automatic Escaping
 357 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 358
 359 When automatic escaping is enabled everything is escaped by default except
 360 for values explicitly marked as safe.  Those can either be marked by the
 361 application or in the template by using the `|safe` filter.  The main
 362 problem with this approach is that Python itself doesn't have the concept
 363 of tainted values so the information if a value is safe or unsafe can get
 364 lost.  If the information is lost escaping will take place which means that
 365 you could end up with double escaped contents.
 366
 367 Double escaping is easy to avoid however, just rely on the tools Jinja2
 368 provides and don't use builtin Python constructs such as the string modulo
 369 operator.
 370
 371 Functions returning template data (macros, `super`, `self.BLOCKNAME`) return
 372 safe markup always.
 373
 374 String literals in templates with automatic escaping are considered unsafe
 375 too.  The reason for this is that the safe string is an extension to Python
 376 and not every library will work properly with it.
 377
 378
 379 List of Control Structures
 380 --------------------------
 381
 382 A control structure refers to all those things that control the flow of a
 383 program - conditionals (i.e. if/elif/else), for-loops, as well as things like
 384 macros and blocks.  Control structures appear inside ``{% ... %}`` blocks
 385 in the default syntax.
 386
 387 For
 388 ~~~
 389
 390 Loop over each item in a sequence.  For example, to display a list of users
 391 provided in a variable called `users`::
 392
 393     <h1>Members</h1>
 394     <ul>
 395     {% for user in users %}
 396       <li>{{ user.username|e }}</li>
 397     {% endfor %}
 398     </ul>
 399
 400 Inside of a for loop block you can access some special variables:
 401
 402 +-----------------------+---------------------------------------------------+
 403 | Variable              | Description                                       |
 404 +=======================+===================================================+
 405 | `loop.index`          | The current iteration of the loop. (1 indexed)    |
 406 +-----------------------+---------------------------------------------------+
 407 | `loop.index0`         | The current iteration of the loop. (0 indexed)    |
 408 +-----------------------+---------------------------------------------------+
 409 | `loop.revindex`       | The number of iterations from the end of the loop |
 410 |                       | (1 indexed)                                       |
 411 +-----------------------+---------------------------------------------------+
 412 | `loop.revindex0`      | The number of iterations from the end of the loop |
 413 |                       | (0 indexed)                                       |
 414 +-----------------------+---------------------------------------------------+
 415 | `loop.first`          | True if first iteration.                          |
 416 +-----------------------+---------------------------------------------------+
 417 | `loop.last`           | True if last iteration.                           |
 418 +-----------------------+---------------------------------------------------+
 419 | `loop.length`         | The number of items in the sequence.              |
 420 +-----------------------+---------------------------------------------------+
 421 | `loop.cycle`          | A helper function to cycle between a list of      |
 422 |                       | sequences.  See the explanation below.            |
 423 +-----------------------+---------------------------------------------------+
 424
 425 Within a for-loop, it's possible to cycle among a list of strings/variables
 426 each time through the loop by using the special `loop.cycle` helper::
 427
 428     {% for row in rows %}
 429         <li class="{{ loop.cycle('odd', 'even') }}">{{ row }}</li>
 430     {% endfor %}
 431
 432 .. _loop-filtering:
 433
 434 Unlike in Python it's not possible to `break` or `continue` in a loop.  You
 435 can however filter the sequence during iteration which allows you to skip
 436 items.  The following example skips all the users which are hidden::
 437
 438     {% for user in users if not user.hidden %}
 439         <li>{{ user.username|e }}</li>
 440     {% endfor %}
 441
 442 The advantage is that the special `loop` variable will count correctly thus
 443 not counting the users not iterated over.
 444
 445 If no iteration took place because the sequence was empty or the filtering
 446 removed all the items from the sequence you can render a replacement block
 447 by using `else`::
 448
 449     <ul>
 450     {% for user in users %}
 451         <li>{{ user.username|e }}</li>
 452     {% else %}
 453         <li><em>no users found</em></li>
 454     {% endif %}
 455     </ul>
 456
 457
 458 If
 459 ~~
 460
 461 The `if` statement in Jinja is comparable with the if statements of Python.
 462 In the simplest form you can use it to test if a variable is defined, not
 463 empty or not false::
 464
 465     {% if users %}
 466     <ul>
 467     {% for user in users %}
 468         <li>{{ user.username|e }}</li>
 469     {% endfor %}
 470     </ul>
 471     {% endif %}
 472
 473 For multiple branches `elif` and `else` can be used like in Python.  You can
 474 use more complex :ref:`expressions` there too::
 475
 476     {% if kenny.sick %}
 477         Kenny is sick.
 478     {% elif kenny.dead %}
 479         You killed Kenny!  You bastard!!!
 480     {% else %}
 481         Kenny looks okay --- so far
 482     {% endif %}
 483
 484 If can also be used as :ref:`inline expression <if-expression>` and for
 485 :ref:`loop filtering <loop-filtering>`.
 486
 487
 488 Macros
 489 ~~~~~~
 490
 491 Macros are comparable with functions in regular programming languages.  They
 492 are useful to put often used idioms into reusable functions to not repeat
 493 yourself.
 494
 495 Macros can be defined in helper templates which then are :ref:`imported
 496 <import>` or directly in the template where they are used.  There is one big
 497 difference between those two possibilities.  A macro that is defined in the
 498 template where it's also used has access to the context passed to the template.
 499 A macro defined in another template and then imported can only access variables
 500 defined there or in the global context.
 501
 502 Here a small example of a macro that renders a form element::
 503
 504     {% macro input(name, value='', type='text', size=20) -%}
 505         <input type="{{ type }}" name="{{ name }}" value="{{
 506             value|e }}" size="{{ size }}">
 507     {%- endmacro %}
 508
 509 The macro can then be called like a function in the namespace::
 510
 511     <p>{{ input('username') }}</p>
 512     <p>{{ input('password', type='password') }}</p>
 513
 514 If the macro was defined in a different template you have to
 515 :ref:`import <import>` it first.
 516
 517 Inside macros you have access to three special variables:
 518
 519 `varargs`
 520     If more positional arguments are passed to the macro than accepted by the
 521     macro they end up in the special `varargs` variable as list of values.
 522
 523 `kwargs`
 524     Like `varargs` but for keyword arguments.  All unconsumed keyword
 525     arguments are stored in this special variable.
 526
 527 `caller`
 528     If the macro was called from a :ref:`call<call>` tag the caller is stored
 529     in this variable as macro which can be called.
 530
 531 Macros also expose some of their internal details.  The following attributes
 532 are available on a macro object:
 533
 534 `name`
 535     The name of the macro.  ``{{ input.name }}`` will print ``input``.
 536
 537 `arguments`
 538     A tuple of the names of arguments the macro accepts.
 539
 540 `defaults`
 541     A tuple of default values.
 542
 543 `catch_kwargs`
 544     This is `true` if the macro accepts extra keyword arguments (ie: accesses
 545     the special `kwargs` variable).
 546
 547 `catch_varargs`
 548     This is `true` if the macro accepts extra positional arguments (ie:
 549     accesses the special `varargs` variable).
 550
 551 `caller`
 552     This is `true` if the macro accesses the special `caller` variable and may
 553     be called from a :ref:`call<call>` tag.
 554
 555
 556 .. _call:
 557
 558 Call
 559 ~~~~
 560
 561 In some cases it can be useful to pass a macro to another macro.  For this
 562 purpose you can use the special `call` block.  The following example shows
 563 a macro that takes advantage of the call functionality and how it can be
 564 used::
 565
 566     {% macro render_dialog(title, class='dialog') -%}
 567         <div class="{{ class }}">
 568             <h2>{{ title }}</h2>
 569             <div class="contents">
 570                 {{ caller() }}
 571             </div>
 572         </div>
 573     {%- endmacro %}
 574
 575     {% call render_dialog('Hello World') %}
 576         This is a simple dialog rendered by using a macro and
 577         a call block.
 578     {% endcall %}
 579
 580 It's also possible to pass arguments back to the call block.  This makes it
 581 useful as replacement for loops.  It is however not possible to call a
 582 call block with another call block.
 583
 584 Here an example of how a call block can be used with arguments::
 585
 586     {% macro dump_users(users) -%}
 587         <ul>
 588         {%- for user in users %}
 589             <li><p>{{ user.username|e }}</p>{{ caller(user) }}</li>
 590         {%- endfor %}
 591         </ul>
 592     {%- endmacro %}
 593
 594     {% call(user) dump_users(list_of_user) %}
 595         <dl>
 596             <dl>Realname</dl>
 597             <dd>{{ user.realname|e }}</dd>
 598             <dl>Description</dl>
 599             <dd>{{ user.description }}</dd>
 600         </dl>
 601     {% endcall %}
 602
 603
 604 Assignments
 605 ~~~~~~~~~~~
 606
 607 Inside code blocks you can also assign values to variables.  Assignments at
 608 top level (outside of blocks, macros or loops) are exported from the template
 609 like top level macros and can be imported by other templates.
 610
 611 Assignments are just written in code blocks like any other statement just
 612 without explicit keyword::
 613
 614     {% navigation = [('index.html', 'Index'), ('about.html', 'About')] %}
 615
 616
 617 Extends
 618 ~~~~~~~
 619
 620 The `extends` tag can be used to extend a template from another one.  You
 621 can have multiple of them in a file but only one of them may be executed
 622 at the time.  There is no support for multiple inheritance.  See the section
 623 about :ref:`template-inheritance` above.
 624
 625
 626 Block
 627 ~~~~~
 628
 629 Blocks are used for inheritance and act as placeholders and replacements
 630 at the same time.  They are documented in detail as part of the section
 631 about :ref:`template-inheritance`.
 632
 633
 634 Include
 635 ~~~~~~~
 636
 637 The `include` statement is useful to include a template and return the
 638 rendered contents of that file into the current namespace::
 639
 640     {% include 'header.html' %}
 641         Body
 642     {% include 'footer.html' %}
 643
 644 Included templates have access to the variables of the active context by
 645 default.  For more details about context behavior of imports and includes
 646 see :ref:`import-visibility`.
 647
 648 .. _import:
 649
 650 Import
 651 ~~~~~~
 652
 653 Jinja2 supports putting often used code into macros.  These macros can go into
 654 different templates and get imported from there.  This works similar to the
 655 import statements in Python.  It's important to know that imports are cached
 656 and imported templates don't have access to the current template variables,
 657 just the globals by defualt.  For more details about context behavior of
 658 imports and includes see :ref:`import-visibility`.
 659
 660 There are two ways to import templates.  You can import the complete template
 661 into a variable or request specific macros / exported variables from it.
 662
 663 Imagine we have a helper module that renders forms (called `forms.html`)::
 664
 665     {% macro input(name, value='', type='text') -%}
 666         <input type="{{ type }}" value="{{ value|e }}" name="{{ name }}">
 667     {%- endmacro %}
 668
 669     {%- macro textarea(name, value='', rows=10, cols=40) -%}
 670         <textarea name="{{ name }}" rows="{{ rows }}" cols="{{ cols
 671             }}">{{ value|e }}</textarea>
 672     {%- endmacro %}
 673
 674 The easiest and most flexible is importing the whole module into a variable.
 675 That way you can access the attributes::
 676
 677     {% import 'forms.html' as forms %}
 678     <dl>
 679         <dt>Username</dt>
 680         <dd>{{ forms.input('username') }}</dd>
 681         <dt>Password</dt>
 682         <dd>{{ forms.input('password', type='password') }}</dd>
 683     </dl>
 684     <p>{{ forms.textarea('comment') }}</p>
 685
 686
 687 Alternatively you can import names from the template into the current
 688 namespace::
 689
 690     {% from 'forms.html' import input as input_field, textarea %}
 691     <dl>
 692         <dt>Username</dt>
 693         <dd>{{ input_field('username') }}</dd>
 694         <dt>Password</dt>
 695         <dd>{{ input_field('password', type='password') }}</dd>
 696     </dl>
 697     <p>{{ textarea('comment') }}</p>
 698
 699
 700 .. _import-visibility:
 701
 702 Import Context Behavior
 703 -----------------------
 704
 705 Per default included templates are passed the current context and imported
 706 templates not.  The reason for this is that imports unlike includes are
 707 cached as imports are often used just as a module that holds macros.
 708
 709 This however can be changed of course explicitly.  By adding `with context`
 710 or `without context` to the import/include directive the current context
 711 can be passed to the template and caching is disabled automatically.
 712
 713 Here two examples::
 714
 715     {% from 'forms.html' import input with context %}
 716     {% include 'header.html' without context %}
 717
 718
 719 .. _expressions:
 720
 721 Expressions
 722 -----------
 723
 724 Jinja allows basic expressions everywhere.  These work very similar to regular
 725 Python and even if you're not working with Python you should feel comfortable
 726 with it.
 727
 728 Literals
 729 ~~~~~~~~
 730
 731 The simplest form of expressions are literals.  Literals are representations
 732 for Python objects such as strings and numbers.  The following literals exist:
 733
 734 "Hello World":
 735     Everything between two double or single quotes is a string.  They are
 736     useful whenever you need a string in the template (for example as
 737     arguments to function calls, filters or just to extend or include a
 738     template).
 739
 740 42 / 42.23:
 741     Integers and floating point numbers are created by just writing the
 742     number down.  If a dot is present the number is a float, otherwise an
 743     integer.  Keep in mind that for Python ``42`` and ``42.0`` is something
 744     different.
 745
 746 ['list', 'of', 'objects']:
 747     Everything between two brackets is a list.  Lists are useful to store
 748     sequential data in or to iterate over them.  For example you can easily
 749     create a list of links using lists and tuples with a for loop::
 750
 751         <ul>
 752         {% for href, caption in [('index.html', 'Index'), ('about.html', 'About'),
 753                                  ('downloads.html', 'Downloads')] %}
 754             <li><a href="{{ href }}">{{ caption }}</a></li>
 755         {% endfor %}
 756         </ul>
 757
 758 ('tuple', 'of', 'values'):
 759     Tuples are like lists, just that you can't modify them.  If the tuple
 760     only has one item you have to end it with a comma.  Tuples are usually
 761     used to represent items of two or more elements.  See the example above
 762     for more details.
 763
 764 {'dict': 'of', 'key': 'and', 'value': 'pairs'}:
 765     A dict in Python is a structure that combines keys and values.  Keys must
 766     be unique and always have exactly one value.  Dicts are rarely used in
 767     templates, they are useful in some rare cases such as the :func:`xmlattr`
 768     filter.
 769
 770 true / false:
 771     true is always true and false is always false.  Keep in mind that those
 772     literals are lowercase!
 773
 774 Math
 775 ~~~~
 776
 777 Jinja allows you to calculate with values.  This is rarely useful in templates
 778 but exists for completeness sake.  The following operators are supported:
 779
 780 \+
 781     Adds two objects with each other.  Usually numbers but if both objects are
 782     strings or lists you can concatenate them this way.  This however is not
 783     the preferred way to concatenate strings!  For string concatenation have
 784     a look at the ``~`` operator.  ``{{ 1 + 1 }}`` is ``2``.
 785
 786 \-
 787     Substract two numbers from each other.  ``{{ 3 - 2 }}`` is ``1``.
 788
 789 /
 790     Divide two numbers.  The return value will be a floating point number.
 791     ``{{ 1 / 2 }}`` is ``{{ 0.5 }}``.
 792
 793 //
 794     Divide two numbers and return the truncated integer result.
 795     ``{{ 20 / 7 }}`` is ``2``.
 796
 797 %
 798     Calculate the remainder of an integer division between the left and right
 799     operand.  ``{{ 11 % 7 }}`` is ``4``.
 800
 801 \*
 802     Multiply the left operand with the right one.  ``{{ 2 * 2 }}`` would
 803     return ``4``.  This can also be used to repeat string multiple times.
 804     ``{{ '=' * 80 }}`` would print a bar of 80 equal signs.
 805
 806 \**
 807     Raise the left operand to the power of the right operand.  ``{{ 2**3 }}``
 808     would return ``8``.
 809
 810 Logic
 811 ~~~~~
 812
 813 For `if` statements / `for` filtering or `if` expressions it can be useful to
 814 combine group multiple expressions:
 815
 816 and
 817     Return true if the left and the right operand is true.
 818
 819 or
 820     Return true if the left or the right operand is true.
 821
 822 not
 823     negate a statement (see below).
 824
 825 (expr)
 826     group an expression.
 827
 828 Note that there is no support for any bit operations or something similar.
 829
 830 -   special note regarding ``not``: The ``is`` and ``in`` operators support
 831     negation using an infix notation too: ``foo is not bar`` and
 832     ``foo not in bar`` instead of ``not foo is bar`` and ``not foo in bar``.
 833     All other expressions require a prefix notation: ``not (foo and bar).``
 834
 835
 836 Other Operators
 837 ~~~~~~~~~~~~~~~
 838
 839 The following operators are very useful but don't fit into any of the other
 840 two categories:
 841
 842 in
 843     Perform sequence / mapping containment test.  Returns true if the left
 844     operand is contained in the right.  ``{{ 1 in [1, 2, 3] }}`` would for
 845     example return true.
 846
 847 is
 848     Performs a :ref:`test <tests>`.
 849
 850 \|
 851     Applies a :ref:`filter <filters>`.
 852
 853 ~
 854     Converts all operands into strings and concatenates them.
 855     ``{{ "Hello " ~ name ~ "!" }}`` would return (assuming `name` is
 856     ``'John'``) ``Hello John!``.
 857
 858 ()
 859     Call a callable: ``{{ post.render() }}``.  Inside of the parentheses you
 860     can use arguments and keyword arguments like in python:
 861     ``{{ post.render(user, full=true) }}``.
 862
 863 . / []
 864     Get an attribute of an object.  (See :ref:`variables`)
 865
 866
 867 .. _if-expression:
 868
 869 If Expression
 870 ~~~~~~~~~~~~~
 871
 872 It is also possible to use inline `if` expressions.  These are useful in some
 873 situations.  For example you can use this to extend from one template if a
 874 variable is defined, otherwise from the default layout template::
 875
 876     {% extends layout_template if layout_template is defined else 'master.html' %}
 877
 878 The general syntax is ``<do something> if <something is true> else <do
 879 something else>``.
 880
 881
 882 .. _builtin-filters:
 883
 884 List of Builtin Filters
 885 -----------------------
 886
 887 .. jinjafilters::
 888
 889
 890 .. _builtin-tests:
 891
 892 List of Builtin Tests
 893 ---------------------
 894
 895 .. jinjatests::
 896
 897
 898 List of Global Functions
 899 ------------------------
 900
 901 The following functions are available in the global scope by default:
 902
 903 .. function:: range([start,] stop[, step])
 904
 905     Return a list containing an arithmetic progression of integers.
 906     range(i, j) returns [i, i+1, i+2, ..., j-1]; start (!) defaults to 0.
 907     When step is given, it specifies the increment (or decrement).
 908     For example, range(4) returns [0, 1, 2, 3].  The end point is omitted!
 909     These are exactly the valid indices for a list of 4 elements.
 910
 911     This is useful to repeat a template block multiple times for example
 912     to fill a list.  Imagine you have 7 users in the list but you want to
 913     render three empty items to enforce a height with CSS::
 914
 915         <ul>
 916         {% for user in users %}
 917             <li>{{ user.username }}</li>
 918         {% endfor %}
 919         {% for number in range(10 - users|count) %}
 920             <li class="empty"><span>...</span></li>
 921         {% endfor %}
 922         </ul>
 923
 924 .. function:: lipsum(n=5, html=True, min=20, max=100)
 925
 926     Generates some lorem ipsum for the template.  Per default five paragraphs
 927     with HTML are generated each paragraph between 20 and 100 words.  If html
 928     is disabled regular text is returned.  This is useful to generate simple
 929     contents for layout testing.
 930
 931 .. function:: dict(**items)
 932
 933     A convenient alternative to dict literals.  ``{'foo': 'bar'}`` is the same
 934     as ``dict(foo='bar')``.