1====================== 2Designer Documentation 3====================== 4 5This part of the Jinja documentaton is meant for template designers. 6 7Basics 8====== 9 10The Jinja template language is designed to strike a balance between content 11and application logic. Nevertheless you can use a python like statement 12language. You don't have to know how Python works to create Jinja templates, 13but if you know it you can use some additional statements you may know from 14Python. 15 16Here is a small example template: 17 18.. sourcecode:: html+jinja 19 20 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 21 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 22 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> 23 <head> 24 <title>My Webpage</title> 25 </head> 26 <body> 27 <ul id="navigation"> 28 {% for item in navigation %} 29 <li><a href="{{ item.href|e }}">{{ item.caption|e }}</a></li> 30 {% endfor %} 31 </ul> 32 33 <h1>My Webpage</h1> 34 {{ variable }} 35 </body> 36 </html> 37 38This covers the default settings. The application developer might have changed 39the syntax from ``{% foo %}`` to ``<% foo %>`` or something similar. This 40documentation just covers the default values. 41 42A variable looks like ``{{ foobar }}`` where foobar is the variable name. Inside 43of statements (``{% some content here %}``) variables are just normal names 44without the braces around it. In fact ``{{ foobar }}`` is just an alias for 45the statement ``{% print foobar %}``. 46 47Variables are coming from the context provided by the application. Normally there 48should be a documentation regarding the context contents but if you want to know 49the content of the current context, you can add this to your template: 50 51.. sourcecode:: html+jinja 52 53 <pre>{{ debug()|e }}</pre> 54 55A context isn't flat which means that each variable can has subvariables, as long 56as it is representable as python data structure. You can access attributes of 57a variable using the dot and bracket operators. The following examples show 58this: 59 60.. sourcecode:: jinja 61 62 {{ user.username }} 63 is the same as 64 {{ user['username'] }} 65 you can also use a variable to access an attribute: 66 {{ users[current_user].username }} 67 If you have numerical indices you have to use the [] syntax: 68 {{ users[0].username }} 69 70Filters 71======= 72 73In the examples above you might have noticed the pipe symbols. Pipe symbols tell 74the engine that it has to apply a filter on the variable. Here is a small example: 75 76.. sourcecode:: jinja 77 78 {{ variable|replace('foo', 'bar')|escape }} 79 80If you want, you can also put whitespace between the filters. 81 82This will look for a variable `variable`, pass it to the filter `replace` 83with the arguments ``'foo'`` and ``'bar'``, and pass the result to the filter 84`escape` that automatically XML-escapes the value. The `e` filter is an alias for 85`escape`. Here is the complete list of supported filters: 86 87[[list_of_filters]] 88 89.. admonition:: note 90 91 Filters have a pretty low priority. If you want to add fitered values 92 you have to put them into parentheses. The same applies if you want to access 93 attributes: 94 95 .. sourcecode:: jinja 96 97 correct: 98 {{ (foo|filter) + (bar|filter) }} 99 wrong: 100 {{ foo|filter + bar|filter }} 101 102 correct: 103 {{ (foo|filter).attribute }} 104 wrong: 105 {{ foo|filter.attribute }} 106 107Tests 108===== 109 110You can use the `is` operator to perform tests on a value: 111 112.. sourcecode:: jinja 113 114 {{ 42 is numeric }} -> true 115 {{ "foobar" is numeric }} -> false 116 {{ 'FOO' is upper }} -> true 117 118These tests are especially useful when used in `if` conditions. 119 120[[list_of_tests]] 121 122Global Functions 123================ 124 125Test functions and filter functions live in their own namespace. Global 126functions not. They behave like normal objects in the context. Beside the 127functions added by the application or framewhere there are two functions 128available per default: 129 130`range` 131 132 Works like the python `range function`_ just that it doesn't support 133 ranges greater than ``1000000``. 134 135`debug` 136 137 Function that outputs the contents of the context. 138 139Loops 140===== 141 142To iterate over a sequence, you can use the `for` loop. It basically looks like a 143normal Python `for` loop and works pretty much the same: 144 145.. sourcecode:: html+jinja 146 147 <h1>Members</h1> 148 <ul> 149 {% for user in users %} 150 <li>{{ loop.index }} / {{ loop.length }} - {{ user.username|escape }}</li> 151 {% else %} 152 <li><em>no users found</em></li> 153 {% endfor %} 154 </ul> 155 156*Important* Contrary to Python is the optional ``else`` block only 157executed if there was no iteration because the sequence was empty. 158 159Inside of a `for` loop block you can access some special variables: 160 161+----------------------+----------------------------------------+ 162| Variable | Description | 163+======================+========================================+ 164| `loop.index` | The current iteration of the loop. | 165+----------------------+----------------------------------------+ 166| `loop.index0` | The current iteration of the loop, | 167| | starting counting by 0. | 168+----------------------+----------------------------------------+ 169| `loop.revindex` | The number of iterations from the end | 170| | of the loop. | 171+----------------------+----------------------------------------+ 172| `loop.revindex0` | The number of iterations from the end | 173| | of the loop, starting counting by 0. | 174+----------------------+----------------------------------------+ 175| `loop.first` | True if first iteration. | 176+----------------------+----------------------------------------+ 177| `loop.last` | True if last iteration. | 178+----------------------+----------------------------------------+ 179| `loop.even` | True if current iteration is even. | 180+----------------------+----------------------------------------+ 181| `loop.odd` | True if current iteration is odd. | 182+----------------------+----------------------------------------+ 183| `loop.length` | Total number of items in the sequence. | 184+----------------------+----------------------------------------+ 185| `loop.parent` | The context of the parent loop. | 186+----------------------+----------------------------------------+ 187 188Loops also support recursion. Let's assume you have a sitemap where each item 189might have a number of child items. A template for that could look like this: 190 191.. sourcecode:: html+jinja 192 193 <h1>Sitemap 194 <ul id="sitemap"> 195 {% for item in sitemap recursive %} 196 <li><a href="{{ item.url|e }}">{{ item.title|e }}</a> 197 {% if item.children %}<ul>{{ loop(item.children) }}</ul>{% endif %}</li> 198 {% endfor %} 199 </ul> 200 201What happens here? Basically the first thing that is different to a normal 202loop is the additional ``recursive`` modifier in the `for`-loop declaration. 203It tells the template engine that we want recursion. If recursion is enabled 204the special `loop` variable is callable. If you call it with a sequence it will 205automatically render the loop at that position with the new sequence as argument. 206 207Cycling 208======= 209 210Sometimes you might want to have different text snippets for each row in a list, 211for example to have alternating row colors. You can easily do this by using the 212``{% cycle %}`` tag: 213 214.. sourcecode:: html+jinja 215 216 <ul id="messages"> 217 {% for message in messages %} 218 <li class="{% cycle 'row1', 'row2' %}">{{ message|e }}</li> 219 {% endfor %} 220 </ul> 221 222Each time Jinja encounters a `cycle` tag it will cycle through the list 223of given items and return the next one. If you pass it one item jinja assumes 224that this item is a sequence from the context and uses this: 225 226.. sourcecode:: html+jinja 227 228 <li style="color: {% cycle rowcolors %}">...</li> 229 230Conditions 231========== 232 233Jinja supports Python-like `if` / `elif` / `else` constructs: 234 235.. sourcecode:: jinja 236 237 {% if user.active %} 238 user {{ user.name|e }} is active. 239 {% elif user.deleted %} 240 user {{ user.name|e }} was deleted some time ago. 241 {% else %} 242 i don't know what's wrong with {{ user.username|e }} 243 {% endif %} 244 245If the user is active the first block is rendered. If not and the user was 246deleted the second one, in all other cases the third one. 247 248You can also use comparison operators: 249 250.. sourcecode:: html+jinja 251 252 {% if amount < 0 %} 253 <span style="color: red">{{ amount }}</span> 254 {% else %} 255 <span style="color: black">{{ amount }}</span> 256 {% endif %} 257 258.. admonition:: Note 259 260 Of course you can use `or` / `and` and parentheses to create more complex 261 conditions, but usually the logic is already handled in the application and 262 you don't have to create such complex constructs in the template code. However 263 in some situations it might be a good thing to have the abilities to create 264 them. 265 266Operators 267========= 268 269Inside ``{{ variable }}`` blocks, `if` conditions and many other parts you can 270can use expressions. In expressions you can use any of the following operators: 271 272 ======= =================================================================== 273 ``+`` add the right operand to the left one. 274 ``{{ 1 + 2 }}`` would return ``3``. 275 ``-`` subtract the right operand from the left one. 276 ``{{ 1 - 1 }}`` would return ``0``. 277 ``/`` divide the left operand by the right one. 278 ``{{ 1 / 2 }}`` would return ``0.5``. 279 ``*`` multiply the left operand with the right one. 280 ``{{ 2 * 2 }}`` would return ``4``. 281 ``**`` raise the left operand to the power of the right 282 operand. ``{{ 2**3 }}`` would return ``8``. 283 ``in`` perform sequence membership test. ``{{ 1 in [1,2,3] }}`` would 284 return true. 285 ``is`` perform a test on the value. See the section about 286 tests for more information. 287 ``|`` apply a filter on the value. See the section about 288 filters for more information. 289 ``and`` return true if the left and the right operand is true. 290 ``or`` return true if the left or the right operand is true. 291 ``not`` negate a statement (see below) 292 ``()`` call a callable: ``{{ user.get_username() }}``. Inside of the 293 parentheses you can use variables: ``{{ user.get(username) }}``. 294 ======= =================================================================== 295 296Note that there is no support for any bit operations or something similar. 297 298* special note regarding `not`: The `is` and `in` operators support negation 299 using an infix notation too: ``foo is not bar`` and ``foo not in bar`` 300 instead of ``not foo is bar`` and ``not foo in bar``. All other expressions 301 require a prefix notation: ``not (foo and bar)``. 302 303Boolean Values 304============== 305 306In If-Conditions Jinja performs a boolean check. All empty values (eg: empty 307lists ``[]``, empty dicts ``{}`` etc) evaluate to `false`. Numbers that are 308equal to `0`/`0.00` are considered `false` too. The boolean value of other 309objects depends on the behavior the application developer gave it. Usually 310items are `true`. 311 312Here some examples that should explain it: 313 314.. sourcecode:: jinja 315 316 {% if [] %} 317 will always be false because it's an empty list 318 319 {% if {} %} 320 false too. 321 322 {% if ['foo'] %} 323 this is true. Because the list is not empty. 324 325 {% if "foobar" %} 326 this is also true because the string is not empty. 327 328Slicing 329======= 330 331Some objects support slicing operations. For example lists: 332 333.. sourcecode:: jinja 334 335 {% for item in items[:5] %} 336 This will only iterate over the first 5 items of the list 337 338 {% for item in items[5:10] %} 339 This will only iterate from item 5 to 10. 340 341 {% for item in items[:10:2] %} 342 This will only yield items from start to ten and only returing 343 even items. 344 345For more informations about slicing have a look at the `slicing chapter`_ 346in the "Dive into Python" e-book. 347 348Macros 349====== 350 351If you want to use a partial template in more than one place, you might want to 352create a macro from it: 353 354.. sourcecode:: html+jinja 355 356 {% macro show_user user %} 357 <h1>{{ user.name|e }}</h1> 358 <div class="test"> 359 {{ user.description }} 360 </div> 361 {% endmacro %} 362 363Now you can use it from everywhere in the code by passing it an item: 364 365.. sourcecode:: jinja 366 367 {% for user in users %} 368 {{ show_user(user) }} 369 {% endfor %} 370 371You can also specify more than one value: 372 373.. sourcecode:: html+jinja 374 375 {% macro show_dialog title, text %} 376 <div class="dialog"> 377 <h1>{{ title|e }}</h1> 378 <div class="test">{{ text|e }}</div> 379 </div> 380 {% endmacro %} 381 382 {{ show_dialog('Warning', 'something went wrong i guess') }} 383 384Inheritance 385=========== 386 387The most powerful part of Jinja is template inheritance. Template inheritance 388allows you to build a base "skeleton" template that contains all the common 389elements of your site and defines **blocks** that child templates can override. 390 391Sounds complicated but is very basic. It's easiest to understand it by starting 392with an example. 393 394Base Template 395------------- 396 397This template, which we'll call ``base.html``, defines a simple HTML skeleton 398document that you might use for a simple two-column page. It's the job of 399"child" templates to fill the empty blocks with content: 400 401.. sourcecode:: html+jinja 402 403 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 404 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 405 <html xmlns="http://www.w3.org/1999/xhtml"> 406 <head> 407 <link rel="stylesheet" href="style.css" /> 408 <title>{% block title %}{% endblock %} - My Webpage</title> 409 {% block html_head %}{% endblock %} 410 </head> 411 <body> 412 <div id="content"> 413 {% block content %}{% endblock %} 414 </div> 415 416 <div id="footer"> 417 {% block footer %} 418 © Copyright 2006 by <a href="http://mydomain.tld">myself</a>. 419 {% endblock %} 420 </div> 421 </body> 422 423In this example, the ``{% block %}`` tags define four blocks that child templates 424can fill in. All the `block` tag does is to tell the template engine that a 425child template may override those portions of the template. 426 427Child Template 428-------------- 429 430A child template might look like this: 431 432.. sourcecode:: html+jinja 433 434 {% extends "base.html" %} 435 {% block title %}Index{% endblock %} 436 437 {% block html_head %} 438 <style type="text/css"> 439 .important { 440 color: #336699; 441 } 442 </style> 443 {% endblock %} 444 445 {% block content %} 446 <h1>Index</h1> 447 <p class="important"> 448 Welcome on my awsome homepage. 449 </p> 450 {% endblock %} 451 452The ``{% extends %}`` tag is the key here. It tells the template engine that 453this template "extends" another template. When the template system evaluates 454this template, first it locates the parent. 455 456The filename of the template depends on the template loader. For example the 457``FileSystemLoader`` allows you to access other templates by giving the 458filename. You can access templates in subdirectories with an slash: 459 460.. sourcecode:: jinja 461 462 {% extends "layout/default.html" %} 463 464But this behavior can depend on the application using Jinja. 465 466Note that since the child template didn't define the ``footer`` block, the 467value from the parent template is used instead. 468 469.. admonition:: Note 470 471 You can't define multiple ``{% block %}`` tags with the same name in the 472 same template. This limitation exists because a block tag works in "both" 473 directions. That is, a block tag doesn't just provide a hole to fill - it 474 also defines the content that fills the hole in the *parent*. If there were 475 two similarly-named ``{% block %}`` tags in a template, that template's 476 parent wouldn't know which one of the blocks' content to use. 477 478Template Inclusion 479================== 480 481You can load another template at a given position using ``{% include %}``. 482Usually it's a better idea to use inheritance but if you for example want to 483load macros, `include` works better than `extends`: 484 485.. sourcecode:: jinja 486 487 {% include "myhelpers.html" %} 488 {{ my_helper("foo") }} 489 490If you define a macro called ``my_helper`` in ``myhelpers.html``, you can now 491use it from the template as shown above. 492 493Filtering Blocks 494================ 495 496Sometimes it could be a good idea to filter a complete block of text. For 497example, if you want to escape some html code: 498 499.. sourcecode:: jinja 500 501 {% filter escape %} 502 <html> 503 <code>goes here</code> 504 </html> 505 {% endfilter %} 506 507Of course you can chain filters too: 508 509.. sourcecode:: jinja 510 511 {% filter lower|escape %} 512 <B>SOME TEXT</B> 513 {% endfilter %} 514 515returns ``"<b>some text</b>"``. 516 517Defining Variables 518================== 519 520You can also define variables in the namespace using the ``{% set %}`` tag: 521 522.. sourcecode:: jinja 523 524 {% set foo = 'foobar' %} 525 {{ foo }} 526 527This should ouput ``foobar``. 528 529Scopes 530====== 531 532Jinja has multiple scopes. A scope is something like a new transparent foil on 533a stack of foils. You can only write to the outermost foil but read all of them 534since you can look through them. If you remove the top foil all data on that 535foil disappears. Some tags in Jinja add a new layer to the stack. Currently 536these are `block`, `for`, `macro` and `filter`. This means that variables and 537other elements defined inside a macro, loop or some of the other tags listed 538above will be only available in that block. Here an example: 539 540.. sourcecode:: jinja 541 542 {% macro angryhello name %} 543 {% set angryname = name|upper %} 544 Hello {{ name }}. Hello {{ name }}! 545 HELLO {{ angryname }}!!!!!!111 546 {% endmacro %} 547 548The variable ``angryname`` just exists inside the macro, not outside it. 549 550Defined macros appear on the context as variables. Because of this, they are 551affected by the scoping too. A macro defined inside of a macro is just available 552in those two macros (the macro itself and the macro it's defined in). For `set` 553and `macro` two additional rules exist: If a macro is defined in an extended 554template but outside of a visible block (thus outside of any block) will be 555available in all blocks below. This allows you to use `include` statements to 556load often used macros at once. 557 558Undefined Variables 559=================== 560 561If you have already worked with python you probably know about the fact that 562undefined variables raise an exception. This is different in Jinja. There is a 563special value called `undefined` that represents values that do not exist. 564 565This special variable works complete different from any variables you maybe 566know. If you print it using ``{{ variable }}`` it will not appear because it's 567literally empty. If you try to iterate over it, it will work. But no items 568are returned. Comparing this value to any other value results in `false`. 569Even if you compare it to itself: 570 571.. sourcecode:: jinja 572 573 {{ undefined == undefined }} 574 will return false. Not even undefined is undefined :) 575 Use `is defined` / `is not defined`: 576 577 {{ undefined is not defined }} 578 will return true. 579 580There are also some additional rules regarding this special value. Any 581mathematical operators (``+``, ``-``, ``*``, ``/``) return the operand 582as result: 583 584.. sourcecode:: jinja 585 586 {{ undefined + "foo" }} 587 returns "foo" 588 589 {{ undefined - 42 }} 590 returns 42. Note: not -42! 591 592In any expression `undefined` evaluates to `false`. It has no length, all 593attribute calls return undefined, calling too: 594 595.. sourcecode:: jinja 596 597 {{ undefined.attribute().attribute_too[42] }} 598 still returns `undefined`. 599 600Escaping 601======== 602 603Sometimes you might want to add Jinja syntax elements into the template 604without executing them. In that case you have quite a few possibilities. 605 606For small parts this might be a good way: 607 608.. sourcecode:: jinja 609 610 {{ "{{ foo }} is variable syntax and {% foo %} is block syntax" }} 611 612When you have multiple elements you can use the ``raw`` block: 613 614.. sourcecode:: jinja 615 616 {% raw %} 617 Filtering blocks works like this in Jinja: 618 {% filter escape %} 619 <html> 620 <code>goes here</code> 621 </html> 622 {% endfilter %} 623 {% endraw %} 624 625Reserved Keywords 626================= 627 628Jinja has some keywords you cannot use a variable names. This limitation 629exists to make look coherent. Syntax highlighters won't mess things up and 630you will don't have unexpected output. 631 632The following keywords exist and cannot be used as identifiers: 633 634 `and`, `block`, `cycle`, `elif`, `else`, `endblock`, `endfilter`, 635 `endfor`, `endif`, `endmacro`, `endraw`, `endtrans`, `extends`, `filter`, 636 `for`, `if`, `in`, `include`, `is`, `macro`, `not`, `or`, `pluralize`, 637 `raw`, `recursive`, `set`, `trans` 638 639If you want to use such a name you have to prefix or suffix it or use 640alternative names: 641 642.. sourcecode:: jinja 643 644 {% for macro_ in macros %} 645 {{ macro_('foo') }} 646 {% endfor %} 647 648If future Jinja releases add new keywords those will be "light" keywords which 649means that they won't raise an error for several releases but yield warnings 650on the application side. But it's very unlikely that new keywords will be 651added. 652 653Internationalization 654==================== 655 656If the application is configured for i18n, you can define translatable blocks 657for translators using the `trans` tag or the special underscore function: 658 659.. sourcecode:: jinja 660 661 {% trans %} 662 this is a translatable block 663 {% endtrans %} 664 665 {% trans "This is a translatable string" %} 666 667 {{ _("This is a translatable string") }} 668 669The latter one is useful if you want translatable arguments for filters etc. 670 671If you want to have plural forms too, use the `pluralize` block: 672 673.. sourcecode:: jinja 674 675 {% trans users=users %} 676 One user found. 677 {% pluralize %} 678 {{ users }} users found. 679 {% endtrans %} 680 681 {% trans first=(users|first).username|escape, user=users|length %} 682 one user {{ first }} found. 683 {% pluralize users %} 684 {{ users }} users found, the first one is called {{ first }}. 685 {% endtrans %} 686 687If you have multiple arguments, the first one is assumed to be the indicator (the 688number that is used to determine the correct singular or plural form. If you 689don't have the indicator variable on position 1 you have to tell the `pluralize` 690tag the correct variable name. 691 692Inside translatable blocks you cannot use blocks or expressions (however you can 693still use the ``raw`` block which will work as expected). The variable 694print syntax (``{{ variablename }}``) is the only way to insert the variables 695defined in the ``trans`` header. Filters must be applied in the header. 696 697.. admonition:: note 698 699 Please make sure that you always use pluralize blocks where required. 700 Many languages have more complex plural forms than the English language. 701 702 Never try to workaround that issue by using something like this: 703 704 .. sourcecode:: jinja 705 706 {% if count != 1 %} 707 {{ count }} users found. 708 {% else %} 709 one user found. 710 {% endif %} 711 712.. _slicing chapter: http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice 713.. _range function: http://docs.python.org/tut/node6.html#SECTION006300000000000000000 714