diff options
Diffstat (limited to 'vendor/twig/twig/doc/templates.rst')
-rw-r--r-- | vendor/twig/twig/doc/templates.rst | 851 |
1 files changed, 0 insertions, 851 deletions
diff --git a/vendor/twig/twig/doc/templates.rst b/vendor/twig/twig/doc/templates.rst deleted file mode 100644 index 542b8aef..00000000 --- a/vendor/twig/twig/doc/templates.rst +++ /dev/null | |||
@@ -1,851 +0,0 @@ | |||
1 | Twig for Template Designers | ||
2 | =========================== | ||
3 | |||
4 | This document describes the syntax and semantics of the template engine and | ||
5 | will be most useful as reference to those creating Twig templates. | ||
6 | |||
7 | Synopsis | ||
8 | -------- | ||
9 | |||
10 | A template is simply a text file. It can generate any text-based format (HTML, | ||
11 | XML, CSV, LaTeX, etc.). It doesn't have a specific extension, ``.html`` or | ||
12 | ``.xml`` are just fine. | ||
13 | |||
14 | A template contains **variables** or **expressions**, which get replaced with | ||
15 | values when the template is evaluated, and **tags**, which control the logic | ||
16 | of the template. | ||
17 | |||
18 | Below is a minimal template that illustrates a few basics. We will cover the | ||
19 | details later on: | ||
20 | |||
21 | .. code-block:: html+jinja | ||
22 | |||
23 | <!DOCTYPE html> | ||
24 | <html> | ||
25 | <head> | ||
26 | <title>My Webpage</title> | ||
27 | </head> | ||
28 | <body> | ||
29 | <ul id="navigation"> | ||
30 | {% for item in navigation %} | ||
31 | <li><a href="{{ item.href }}">{{ item.caption }}</a></li> | ||
32 | {% endfor %} | ||
33 | </ul> | ||
34 | |||
35 | <h1>My Webpage</h1> | ||
36 | {{ a_variable }} | ||
37 | </body> | ||
38 | </html> | ||
39 | |||
40 | There are two kinds of delimiters: ``{% ... %}`` and ``{{ ... }}``. The first | ||
41 | one is used to execute statements such as for-loops, the latter prints the | ||
42 | result of an expression to the template. | ||
43 | |||
44 | IDEs Integration | ||
45 | ---------------- | ||
46 | |||
47 | Many IDEs support syntax highlighting and auto-completion for Twig: | ||
48 | |||
49 | * *Textmate* via the `Twig bundle`_ | ||
50 | * *Vim* via the `Jinja syntax plugin`_ | ||
51 | * *Netbeans* via the `Twig syntax plugin`_ (until 7.1, native as of 7.2) | ||
52 | * *PhpStorm* (native as of 2.1) | ||
53 | * *Eclipse* via the `Twig plugin`_ | ||
54 | * *Sublime Text* via the `Twig bundle`_ | ||
55 | * *GtkSourceView* via the `Twig language definition`_ (used by gedit and other projects) | ||
56 | * *Coda* and *SubEthaEdit* via the `Twig syntax mode`_ | ||
57 | * *Coda 2* via the `other Twig syntax mode`_ | ||
58 | * *Komodo* and *Komodo Edit* via the Twig highlight/syntax check mode | ||
59 | * *Notepad++* via the `Notepad++ Twig Highlighter`_ | ||
60 | * *Emacs* via `web-mode.el`_ | ||
61 | |||
62 | Variables | ||
63 | --------- | ||
64 | |||
65 | The application passes variables to the templates you can mess around in the | ||
66 | template. Variables may have attributes or elements on them you can access | ||
67 | too. How a variable looks like heavily depends on the application providing | ||
68 | those. | ||
69 | |||
70 | You can use a dot (``.``) to access attributes of a variable (methods or | ||
71 | properties of a PHP object, or items of a PHP array), or the so-called | ||
72 | "subscript" syntax (``[]``): | ||
73 | |||
74 | .. code-block:: jinja | ||
75 | |||
76 | {{ foo.bar }} | ||
77 | {{ foo['bar'] }} | ||
78 | |||
79 | When the attribute contains special characters (like ``-`` that would be | ||
80 | interpreted as the minus operator), use the ``attribute`` function instead to | ||
81 | access the variable attribute: | ||
82 | |||
83 | .. code-block:: jinja | ||
84 | |||
85 | {# equivalent to the non-working foo.data-foo #} | ||
86 | {{ attribute(foo, 'data-foo') }} | ||
87 | |||
88 | .. note:: | ||
89 | |||
90 | It's important to know that the curly braces are *not* part of the | ||
91 | variable but the print statement. If you access variables inside tags | ||
92 | don't put the braces around. | ||
93 | |||
94 | If a variable or attribute does not exist, you will get back a ``null`` value | ||
95 | when the ``strict_variables`` option is set to ``false``, otherwise Twig will | ||
96 | throw an error (see :ref:`environment options<environment_options>`). | ||
97 | |||
98 | .. sidebar:: Implementation | ||
99 | |||
100 | For convenience sake ``foo.bar`` does the following things on the PHP | ||
101 | layer: | ||
102 | |||
103 | * check if ``foo`` is an array and ``bar`` a valid element; | ||
104 | * if not, and if ``foo`` is an object, check that ``bar`` is a valid property; | ||
105 | * if not, and if ``foo`` is an object, check that ``bar`` is a valid method | ||
106 | (even if ``bar`` is the constructor - use ``__construct()`` instead); | ||
107 | * if not, and if ``foo`` is an object, check that ``getBar`` is a valid method; | ||
108 | * if not, and if ``foo`` is an object, check that ``isBar`` is a valid method; | ||
109 | * if not, return a ``null`` value. | ||
110 | |||
111 | ``foo['bar']`` on the other hand only works with PHP arrays: | ||
112 | |||
113 | * check if ``foo`` is an array and ``bar`` a valid element; | ||
114 | * if not, return a ``null`` value. | ||
115 | |||
116 | .. note:: | ||
117 | |||
118 | If you want to get a dynamic attribute on a variable, use the | ||
119 | :doc:`attribute<functions/attribute>` function instead. | ||
120 | |||
121 | Global Variables | ||
122 | ~~~~~~~~~~~~~~~~ | ||
123 | |||
124 | The following variables are always available in templates: | ||
125 | |||
126 | * ``_self``: references the current template; | ||
127 | * ``_context``: references the current context; | ||
128 | * ``_charset``: references the current charset. | ||
129 | |||
130 | Setting Variables | ||
131 | ~~~~~~~~~~~~~~~~~ | ||
132 | |||
133 | You can assign values to variables inside code blocks. Assignments use the | ||
134 | :doc:`set<tags/set>` tag: | ||
135 | |||
136 | .. code-block:: jinja | ||
137 | |||
138 | {% set foo = 'foo' %} | ||
139 | {% set foo = [1, 2] %} | ||
140 | {% set foo = {'foo': 'bar'} %} | ||
141 | |||
142 | Filters | ||
143 | ------- | ||
144 | |||
145 | Variables can be modified by **filters**. Filters are separated from the | ||
146 | variable by a pipe symbol (``|``) and may have optional arguments in | ||
147 | parentheses. Multiple filters can be chained. The output of one filter is | ||
148 | applied to the next. | ||
149 | |||
150 | The following example removes all HTML tags from the ``name`` and title-cases | ||
151 | it: | ||
152 | |||
153 | .. code-block:: jinja | ||
154 | |||
155 | {{ name|striptags|title }} | ||
156 | |||
157 | Filters that accept arguments have parentheses around the arguments. This | ||
158 | example will join a list by commas: | ||
159 | |||
160 | .. code-block:: jinja | ||
161 | |||
162 | {{ list|join(', ') }} | ||
163 | |||
164 | To apply a filter on a section of code, wrap it with the | ||
165 | :doc:`filter<tags/filter>` tag: | ||
166 | |||
167 | .. code-block:: jinja | ||
168 | |||
169 | {% filter upper %} | ||
170 | This text becomes uppercase | ||
171 | {% endfilter %} | ||
172 | |||
173 | Go to the :doc:`filters<filters/index>` page to learn more about the built-in | ||
174 | filters. | ||
175 | |||
176 | Functions | ||
177 | --------- | ||
178 | |||
179 | Functions can be called to generate content. Functions are called by their | ||
180 | name followed by parentheses (``()``) and may have arguments. | ||
181 | |||
182 | For instance, the ``range`` function returns a list containing an arithmetic | ||
183 | progression of integers: | ||
184 | |||
185 | .. code-block:: jinja | ||
186 | |||
187 | {% for i in range(0, 3) %} | ||
188 | {{ i }}, | ||
189 | {% endfor %} | ||
190 | |||
191 | Go to the :doc:`functions<functions/index>` page to learn more about the | ||
192 | built-in functions. | ||
193 | |||
194 | Named Arguments | ||
195 | --------------- | ||
196 | |||
197 | .. versionadded:: 1.12 | ||
198 | Support for named arguments was added in Twig 1.12. | ||
199 | |||
200 | Arguments for filters and functions can also be passed as *named arguments*: | ||
201 | |||
202 | .. code-block:: jinja | ||
203 | |||
204 | {% for i in range(low=1, high=10, step=2) %} | ||
205 | {{ i }}, | ||
206 | {% endfor %} | ||
207 | |||
208 | Using named arguments makes your templates more explicit about the meaning of | ||
209 | the values you pass as arguments: | ||
210 | |||
211 | .. code-block:: jinja | ||
212 | |||
213 | {{ data|convert_encoding('UTF-8', 'iso-2022-jp') }} | ||
214 | |||
215 | {# versus #} | ||
216 | |||
217 | {{ data|convert_encoding(from='iso-2022-jp', to='UTF-8') }} | ||
218 | |||
219 | Named arguments also allow you to skip some arguments for which you don't want | ||
220 | to change the default value: | ||
221 | |||
222 | .. code-block:: jinja | ||
223 | |||
224 | {# the first argument is the date format, which defaults to the global date format if null is passed #} | ||
225 | {{ "now"|date(null, "Europe/Paris") }} | ||
226 | |||
227 | {# or skip the format value by using a named argument for the timezone #} | ||
228 | {{ "now"|date(timezone="Europe/Paris") }} | ||
229 | |||
230 | You can also use both positional and named arguments in one call, in which | ||
231 | case positional arguments must always come before named arguments: | ||
232 | |||
233 | .. code-block:: jinja | ||
234 | |||
235 | {{ "now"|date('d/m/Y H:i', timezone="Europe/Paris") }} | ||
236 | |||
237 | .. tip:: | ||
238 | |||
239 | Each function and filter documentation page has a section where the names | ||
240 | of all arguments are listed when supported. | ||
241 | |||
242 | Control Structure | ||
243 | ----------------- | ||
244 | |||
245 | A control structure refers to all those things that control the flow of a | ||
246 | program - conditionals (i.e. ``if``/``elseif``/``else``), ``for``-loops, as | ||
247 | well as things like blocks. Control structures appear inside ``{% ... %}`` | ||
248 | blocks. | ||
249 | |||
250 | For example, to display a list of users provided in a variable called | ||
251 | ``users``, use the :doc:`for<tags/for>` tag: | ||
252 | |||
253 | .. code-block:: jinja | ||
254 | |||
255 | <h1>Members</h1> | ||
256 | <ul> | ||
257 | {% for user in users %} | ||
258 | <li>{{ user.username|e }}</li> | ||
259 | {% endfor %} | ||
260 | </ul> | ||
261 | |||
262 | The :doc:`if<tags/if>` tag can be used to test an expression: | ||
263 | |||
264 | .. code-block:: jinja | ||
265 | |||
266 | {% if users|length > 0 %} | ||
267 | <ul> | ||
268 | {% for user in users %} | ||
269 | <li>{{ user.username|e }}</li> | ||
270 | {% endfor %} | ||
271 | </ul> | ||
272 | {% endif %} | ||
273 | |||
274 | Go to the :doc:`tags<tags/index>` page to learn more about the built-in tags. | ||
275 | |||
276 | Comments | ||
277 | -------- | ||
278 | |||
279 | To comment-out part of a line in a template, use the comment syntax ``{# ... | ||
280 | #}``. This is useful for debugging or to add information for other template | ||
281 | designers or yourself: | ||
282 | |||
283 | .. code-block:: jinja | ||
284 | |||
285 | {# note: disabled template because we no longer use this | ||
286 | {% for user in users %} | ||
287 | ... | ||
288 | {% endfor %} | ||
289 | #} | ||
290 | |||
291 | Including other Templates | ||
292 | ------------------------- | ||
293 | |||
294 | The :doc:`include<tags/include>` tag is useful to include a template and | ||
295 | return the rendered content of that template into the current one: | ||
296 | |||
297 | .. code-block:: jinja | ||
298 | |||
299 | {% include 'sidebar.html' %} | ||
300 | |||
301 | Per default included templates are passed the current context. | ||
302 | |||
303 | The context that is passed to the included template includes variables defined | ||
304 | in the template: | ||
305 | |||
306 | .. code-block:: jinja | ||
307 | |||
308 | {% for box in boxes %} | ||
309 | {% include "render_box.html" %} | ||
310 | {% endfor %} | ||
311 | |||
312 | The included template ``render_box.html`` is able to access ``box``. | ||
313 | |||
314 | The filename of the template depends on the template loader. For instance, the | ||
315 | ``Twig_Loader_Filesystem`` allows you to access other templates by giving the | ||
316 | filename. You can access templates in subdirectories with a slash: | ||
317 | |||
318 | .. code-block:: jinja | ||
319 | |||
320 | {% include "sections/articles/sidebar.html" %} | ||
321 | |||
322 | This behavior depends on the application embedding Twig. | ||
323 | |||
324 | Template Inheritance | ||
325 | -------------------- | ||
326 | |||
327 | The most powerful part of Twig is template inheritance. Template inheritance | ||
328 | allows you to build a base "skeleton" template that contains all the common | ||
329 | elements of your site and defines **blocks** that child templates can | ||
330 | override. | ||
331 | |||
332 | Sounds complicated but is very basic. It's easier to understand it by | ||
333 | starting with an example. | ||
334 | |||
335 | Let's define a base template, ``base.html``, which defines a simple HTML | ||
336 | skeleton document that you might use for a simple two-column page: | ||
337 | |||
338 | .. code-block:: html+jinja | ||
339 | |||
340 | <!DOCTYPE html> | ||
341 | <html> | ||
342 | <head> | ||
343 | {% block head %} | ||
344 | <link rel="stylesheet" href="style.css" /> | ||
345 | <title>{% block title %}{% endblock %} - My Webpage</title> | ||
346 | {% endblock %} | ||
347 | </head> | ||
348 | <body> | ||
349 | <div id="content">{% block content %}{% endblock %}</div> | ||
350 | <div id="footer"> | ||
351 | {% block footer %} | ||
352 | © Copyright 2011 by <a href="http://domain.invalid/">you</a>. | ||
353 | {% endblock %} | ||
354 | </div> | ||
355 | </body> | ||
356 | </html> | ||
357 | |||
358 | In this example, the :doc:`block<tags/block>` tags define four blocks that | ||
359 | child templates can fill in. All the ``block`` tag does is to tell the | ||
360 | template engine that a child template may override those portions of the | ||
361 | template. | ||
362 | |||
363 | A child template might look like this: | ||
364 | |||
365 | .. code-block:: jinja | ||
366 | |||
367 | {% extends "base.html" %} | ||
368 | |||
369 | {% block title %}Index{% endblock %} | ||
370 | {% block head %} | ||
371 | {{ parent() }} | ||
372 | <style type="text/css"> | ||
373 | .important { color: #336699; } | ||
374 | </style> | ||
375 | {% endblock %} | ||
376 | {% block content %} | ||
377 | <h1>Index</h1> | ||
378 | <p class="important"> | ||
379 | Welcome to my awesome homepage. | ||
380 | </p> | ||
381 | {% endblock %} | ||
382 | |||
383 | The :doc:`extends<tags/extends>` tag is the key here. It tells the template | ||
384 | engine that this template "extends" another template. When the template system | ||
385 | evaluates this template, first it locates the parent. The extends tag should | ||
386 | be the first tag in the template. | ||
387 | |||
388 | Note that since the child template doesn't define the ``footer`` block, the | ||
389 | value from the parent template is used instead. | ||
390 | |||
391 | It's possible to render the contents of the parent block by using the | ||
392 | :doc:`parent<functions/parent>` function. This gives back the results of the | ||
393 | parent block: | ||
394 | |||
395 | .. code-block:: jinja | ||
396 | |||
397 | {% block sidebar %} | ||
398 | <h3>Table Of Contents</h3> | ||
399 | ... | ||
400 | {{ parent() }} | ||
401 | {% endblock %} | ||
402 | |||
403 | .. tip:: | ||
404 | |||
405 | The documentation page for the :doc:`extends<tags/extends>` tag describes | ||
406 | more advanced features like block nesting, scope, dynamic inheritance, and | ||
407 | conditional inheritance. | ||
408 | |||
409 | .. note:: | ||
410 | |||
411 | Twig also supports multiple inheritance with the so called horizontal reuse | ||
412 | with the help of the :doc:`use<tags/use>` tag. This is an advanced feature | ||
413 | hardly ever needed in regular templates. | ||
414 | |||
415 | HTML Escaping | ||
416 | ------------- | ||
417 | |||
418 | When generating HTML from templates, there's always a risk that a variable | ||
419 | will include characters that affect the resulting HTML. There are two | ||
420 | approaches: manually escaping each variable or automatically escaping | ||
421 | everything by default. | ||
422 | |||
423 | Twig supports both, automatic escaping is enabled by default. | ||
424 | |||
425 | .. note:: | ||
426 | |||
427 | Automatic escaping is only supported if the *escaper* extension has been | ||
428 | enabled (which is the default). | ||
429 | |||
430 | Working with Manual Escaping | ||
431 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
432 | |||
433 | If manual escaping is enabled, it is **your** responsibility to escape | ||
434 | variables if needed. What to escape? Any variable you don't trust. | ||
435 | |||
436 | Escaping works by piping the variable through the | ||
437 | :doc:`escape<filters/escape>` or ``e`` filter: | ||
438 | |||
439 | .. code-block:: jinja | ||
440 | |||
441 | {{ user.username|e }} | ||
442 | |||
443 | By default, the ``escape`` filter uses the ``html`` strategy, but depending on | ||
444 | the escaping context, you might want to explicitly use any other available | ||
445 | strategies: | ||
446 | |||
447 | .. code-block:: jinja | ||
448 | |||
449 | {{ user.username|e('js') }} | ||
450 | {{ user.username|e('css') }} | ||
451 | {{ user.username|e('url') }} | ||
452 | {{ user.username|e('html_attr') }} | ||
453 | |||
454 | Working with Automatic Escaping | ||
455 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
456 | |||
457 | Whether automatic escaping is enabled or not, you can mark a section of a | ||
458 | template to be escaped or not by using the :doc:`autoescape<tags/autoescape>` | ||
459 | tag: | ||
460 | |||
461 | .. code-block:: jinja | ||
462 | |||
463 | {% autoescape %} | ||
464 | Everything will be automatically escaped in this block (using the HTML strategy) | ||
465 | {% endautoescape %} | ||
466 | |||
467 | By default, auto-escaping uses the ``html`` escaping strategy. If you output | ||
468 | variables in other contexts, you need to explicitly escape them with the | ||
469 | appropriate escaping strategy: | ||
470 | |||
471 | .. code-block:: jinja | ||
472 | |||
473 | {% autoescape 'js' %} | ||
474 | Everything will be automatically escaped in this block (using the JS strategy) | ||
475 | {% endautoescape %} | ||
476 | |||
477 | Escaping | ||
478 | -------- | ||
479 | |||
480 | It is sometimes desirable or even necessary to have Twig ignore parts it would | ||
481 | otherwise handle as variables or blocks. For example if the default syntax is | ||
482 | used and you want to use ``{{`` as raw string in the template and not start a | ||
483 | variable you have to use a trick. | ||
484 | |||
485 | The easiest way is to output the variable delimiter (``{{``) by using a variable | ||
486 | expression: | ||
487 | |||
488 | .. code-block:: jinja | ||
489 | |||
490 | {{ '{{' }} | ||
491 | |||
492 | For bigger sections it makes sense to mark a block | ||
493 | :doc:`verbatim<tags/verbatim>`. | ||
494 | |||
495 | Macros | ||
496 | ------ | ||
497 | |||
498 | .. versionadded:: 1.12 | ||
499 | Support for default argument values was added in Twig 1.12. | ||
500 | |||
501 | Macros are comparable with functions in regular programming languages. They | ||
502 | are useful to reuse often used HTML fragments to not repeat yourself. | ||
503 | |||
504 | A macro is defined via the :doc:`macro<tags/macro>` tag. Here is a small example | ||
505 | (subsequently called ``forms.html``) of a macro that renders a form element: | ||
506 | |||
507 | .. code-block:: jinja | ||
508 | |||
509 | {% macro input(name, value, type, size) %} | ||
510 | <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" /> | ||
511 | {% endmacro %} | ||
512 | |||
513 | Macros can be defined in any template, and need to be "imported" via the | ||
514 | :doc:`import<tags/import>` tag before being used: | ||
515 | |||
516 | .. code-block:: jinja | ||
517 | |||
518 | {% import "forms.html" as forms %} | ||
519 | |||
520 | <p>{{ forms.input('username') }}</p> | ||
521 | |||
522 | Alternatively, you can import individual macro names from a template into the | ||
523 | current namespace via the :doc:`from<tags/from>` tag and optionally alias them: | ||
524 | |||
525 | .. code-block:: jinja | ||
526 | |||
527 | {% from 'forms.html' import input as input_field %} | ||
528 | |||
529 | <dl> | ||
530 | <dt>Username</dt> | ||
531 | <dd>{{ input_field('username') }}</dd> | ||
532 | <dt>Password</dt> | ||
533 | <dd>{{ input_field('password', '', 'password') }}</dd> | ||
534 | </dl> | ||
535 | |||
536 | A default value can also be defined for macro arguments when not provided in a | ||
537 | macro call: | ||
538 | |||
539 | .. code-block:: jinja | ||
540 | |||
541 | {% macro input(name, value = "", type = "text", size = 20) %} | ||
542 | <input type="{{ type }}" name="{{ name }}" value="{{ value|e }}" size="{{ size }}" /> | ||
543 | {% endmacro %} | ||
544 | |||
545 | .. _twig-expressions: | ||
546 | |||
547 | Expressions | ||
548 | ----------- | ||
549 | |||
550 | Twig allows expressions everywhere. These work very similar to regular PHP and | ||
551 | even if you're not working with PHP you should feel comfortable with it. | ||
552 | |||
553 | .. note:: | ||
554 | |||
555 | The operator precedence is as follows, with the lowest-precedence | ||
556 | operators listed first: ``b-and``, ``b-xor``, ``b-or``, ``or``, ``and``, | ||
557 | ``==``, ``!=``, ``<``, ``>``, ``>=``, ``<=``, ``in``, ``..``, ``+``, | ||
558 | ``-``, ``~``, ``*``, ``/``, ``//``, ``%``, ``is``, ``**``, ``|``, ``[]``, | ||
559 | and ``.``: | ||
560 | |||
561 | .. code-block:: jinja | ||
562 | |||
563 | {% set greeting = 'Hello' %} | ||
564 | {% set name = 'Fabien' %} | ||
565 | |||
566 | {{ greeting ~ name|lower }} {# Hello fabien #} | ||
567 | |||
568 | {# use parenthesis to change precedence #} | ||
569 | {{ (greeting ~ name)|lower }} {# hello fabien #} | ||
570 | |||
571 | Literals | ||
572 | ~~~~~~~~ | ||
573 | |||
574 | .. versionadded:: 1.5 | ||
575 | Support for hash keys as names and expressions was added in Twig 1.5. | ||
576 | |||
577 | The simplest form of expressions are literals. Literals are representations | ||
578 | for PHP types such as strings, numbers, and arrays. The following literals | ||
579 | exist: | ||
580 | |||
581 | * ``"Hello World"``: Everything between two double or single quotes is a | ||
582 | string. They are useful whenever you need a string in the template (for | ||
583 | example as arguments to function calls, filters or just to extend or include | ||
584 | a template). A string can contain a delimiter if it is preceded by a | ||
585 | backslash (``\``) -- like in ``'It\'s good'``. | ||
586 | |||
587 | * ``42`` / ``42.23``: Integers and floating point numbers are created by just | ||
588 | writing the number down. If a dot is present the number is a float, | ||
589 | otherwise an integer. | ||
590 | |||
591 | * ``["foo", "bar"]``: Arrays are defined by a sequence of expressions | ||
592 | separated by a comma (``,``) and wrapped with squared brackets (``[]``). | ||
593 | |||
594 | * ``{"foo": "bar"}``: Hashes are defined by a list of keys and values | ||
595 | separated by a comma (``,``) and wrapped with curly braces (``{}``): | ||
596 | |||
597 | .. code-block:: jinja | ||
598 | |||
599 | {# keys as string #} | ||
600 | { 'foo': 'foo', 'bar': 'bar' } | ||
601 | |||
602 | {# keys as names (equivalent to the previous hash) -- as of Twig 1.5 #} | ||
603 | { foo: 'foo', bar: 'bar' } | ||
604 | |||
605 | {# keys as integer #} | ||
606 | { 2: 'foo', 4: 'bar' } | ||
607 | |||
608 | {# keys as expressions (the expression must be enclosed into parentheses) -- as of Twig 1.5 #} | ||
609 | { (1 + 1): 'foo', (a ~ 'b'): 'bar' } | ||
610 | |||
611 | * ``true`` / ``false``: ``true`` represents the true value, ``false`` | ||
612 | represents the false value. | ||
613 | |||
614 | * ``null``: ``null`` represents no specific value. This is the value returned | ||
615 | when a variable does not exist. ``none`` is an alias for ``null``. | ||
616 | |||
617 | Arrays and hashes can be nested: | ||
618 | |||
619 | .. code-block:: jinja | ||
620 | |||
621 | {% set foo = [1, {"foo": "bar"}] %} | ||
622 | |||
623 | .. tip:: | ||
624 | |||
625 | Using double-quoted or single-quoted strings has no impact on performance | ||
626 | but string interpolation is only supported in double-quoted strings. | ||
627 | |||
628 | Math | ||
629 | ~~~~ | ||
630 | |||
631 | Twig allows you to calculate with values. This is rarely useful in templates | ||
632 | but exists for completeness' sake. The following operators are supported: | ||
633 | |||
634 | * ``+``: Adds two objects together (the operands are casted to numbers). ``{{ | ||
635 | 1 + 1 }}`` is ``2``. | ||
636 | |||
637 | * ``-``: Subtracts the second number from the first one. ``{{ 3 - 2 }}`` is | ||
638 | ``1``. | ||
639 | |||
640 | * ``/``: Divides two numbers. The returned value will be a floating point | ||
641 | number. ``{{ 1 / 2 }}`` is ``{{ 0.5 }}``. | ||
642 | |||
643 | * ``%``: Calculates the remainder of an integer division. ``{{ 11 % 7 }}`` is | ||
644 | ``4``. | ||
645 | |||
646 | * ``//``: Divides two numbers and returns the truncated integer result. ``{{ | ||
647 | 20 // 7 }}`` is ``2``. | ||
648 | |||
649 | * ``*``: Multiplies the left operand with the right one. ``{{ 2 * 2 }}`` would | ||
650 | return ``4``. | ||
651 | |||
652 | * ``**``: Raises the left operand to the power of the right operand. ``{{ 2 ** | ||
653 | 3 }}`` would return ``8``. | ||
654 | |||
655 | Logic | ||
656 | ~~~~~ | ||
657 | |||
658 | You can combine multiple expressions with the following operators: | ||
659 | |||
660 | * ``and``: Returns true if the left and the right operands are both true. | ||
661 | |||
662 | * ``or``: Returns true if the left or the right operand is true. | ||
663 | |||
664 | * ``not``: Negates a statement. | ||
665 | |||
666 | * ``(expr)``: Groups an expression. | ||
667 | |||
668 | .. note:: | ||
669 | |||
670 | Twig also support bitwise operators (``b-and``, ``b-xor``, and ``b-or``). | ||
671 | |||
672 | Comparisons | ||
673 | ~~~~~~~~~~~ | ||
674 | |||
675 | The following comparison operators are supported in any expression: ``==``, | ||
676 | ``!=``, ``<``, ``>``, ``>=``, and ``<=``. | ||
677 | |||
678 | Containment Operator | ||
679 | ~~~~~~~~~~~~~~~~~~~~ | ||
680 | |||
681 | The ``in`` operator performs containment test. | ||
682 | |||
683 | It returns ``true`` if the left operand is contained in the right: | ||
684 | |||
685 | .. code-block:: jinja | ||
686 | |||
687 | {# returns true #} | ||
688 | |||
689 | {{ 1 in [1, 2, 3] }} | ||
690 | |||
691 | {{ 'cd' in 'abcde' }} | ||
692 | |||
693 | .. tip:: | ||
694 | |||
695 | You can use this filter to perform a containment test on strings, arrays, | ||
696 | or objects implementing the ``Traversable`` interface. | ||
697 | |||
698 | To perform a negative test, use the ``not in`` operator: | ||
699 | |||
700 | .. code-block:: jinja | ||
701 | |||
702 | {% if 1 not in [1, 2, 3] %} | ||
703 | |||
704 | {# is equivalent to #} | ||
705 | {% if not (1 in [1, 2, 3]) %} | ||
706 | |||
707 | Test Operator | ||
708 | ~~~~~~~~~~~~~ | ||
709 | |||
710 | The ``is`` operator performs tests. Tests can be used to test a variable against | ||
711 | a common expression. The right operand is name of the test: | ||
712 | |||
713 | .. code-block:: jinja | ||
714 | |||
715 | {# find out if a variable is odd #} | ||
716 | |||
717 | {{ name is odd }} | ||
718 | |||
719 | Tests can accept arguments too: | ||
720 | |||
721 | .. code-block:: jinja | ||
722 | |||
723 | {% if loop.index is divisibleby(3) %} | ||
724 | |||
725 | Tests can be negated by using the ``is not`` operator: | ||
726 | |||
727 | .. code-block:: jinja | ||
728 | |||
729 | {% if loop.index is not divisibleby(3) %} | ||
730 | |||
731 | {# is equivalent to #} | ||
732 | {% if not (loop.index is divisibleby(3)) %} | ||
733 | |||
734 | Go to the :doc:`tests<tests/index>` page to learn more about the built-in | ||
735 | tests. | ||
736 | |||
737 | Other Operators | ||
738 | ~~~~~~~~~~~~~~~ | ||
739 | |||
740 | .. versionadded:: 1.12.0 | ||
741 | Support for the extended ternary operator was added in Twig 1.12.0. | ||
742 | |||
743 | The following operators are very useful but don't fit into any of the other | ||
744 | categories: | ||
745 | |||
746 | * ``..``: Creates a sequence based on the operand before and after the | ||
747 | operator (this is just syntactic sugar for the :doc:`range<functions/range>` | ||
748 | function). | ||
749 | |||
750 | * ``|``: Applies a filter. | ||
751 | |||
752 | * ``~``: Converts all operands into strings and concatenates them. ``{{ "Hello | ||
753 | " ~ name ~ "!" }}`` would return (assuming ``name`` is ``'John'``) ``Hello | ||
754 | John!``. | ||
755 | |||
756 | * ``.``, ``[]``: Gets an attribute of an object. | ||
757 | |||
758 | * ``?:``: The ternary operator: | ||
759 | |||
760 | .. code-block:: jinja | ||
761 | |||
762 | {{ foo ? 'yes' : 'no' }} | ||
763 | |||
764 | {# as of Twig 1.12.0 #} | ||
765 | {{ foo ?: 'no' }} == {{ foo ? foo : 'no' }} | ||
766 | {{ foo ? 'yes' }} == {{ foo ? 'yes' : '' }} | ||
767 | |||
768 | String Interpolation | ||
769 | ~~~~~~~~~~~~~~~~~~~~ | ||
770 | |||
771 | .. versionadded:: 1.5 | ||
772 | String interpolation was added in Twig 1.5. | ||
773 | |||
774 | String interpolation (`#{expression}`) allows any valid expression to appear | ||
775 | within a *double-quoted string*. The result of evaluating that expression is | ||
776 | inserted into the string: | ||
777 | |||
778 | .. code-block:: jinja | ||
779 | |||
780 | {{ "foo #{bar} baz" }} | ||
781 | {{ "foo #{1 + 2} baz" }} | ||
782 | |||
783 | Whitespace Control | ||
784 | ------------------ | ||
785 | |||
786 | .. versionadded:: 1.1 | ||
787 | Tag level whitespace control was added in Twig 1.1. | ||
788 | |||
789 | The first newline after a template tag is removed automatically (like in PHP.) | ||
790 | Whitespace is not further modified by the template engine, so each whitespace | ||
791 | (spaces, tabs, newlines etc.) is returned unchanged. | ||
792 | |||
793 | Use the ``spaceless`` tag to remove whitespace *between HTML tags*: | ||
794 | |||
795 | .. code-block:: jinja | ||
796 | |||
797 | {% spaceless %} | ||
798 | <div> | ||
799 | <strong>foo bar</strong> | ||
800 | </div> | ||
801 | {% endspaceless %} | ||
802 | |||
803 | {# output will be <div><strong>foo bar</strong></div> #} | ||
804 | |||
805 | In addition to the spaceless tag you can also control whitespace on a per tag | ||
806 | level. By using the whitespace control modifier on your tags, you can trim | ||
807 | leading and or trailing whitespace: | ||
808 | |||
809 | .. code-block:: jinja | ||
810 | |||
811 | {% set value = 'no spaces' %} | ||
812 | {#- No leading/trailing whitespace -#} | ||
813 | {%- if true -%} | ||
814 | {{- value -}} | ||
815 | {%- endif -%} | ||
816 | |||
817 | {# output 'no spaces' #} | ||
818 | |||
819 | The above sample shows the default whitespace control modifier, and how you can | ||
820 | use it to remove whitespace around tags. Trimming space will consume all whitespace | ||
821 | for that side of the tag. It is possible to use whitespace trimming on one side | ||
822 | of a tag: | ||
823 | |||
824 | .. code-block:: jinja | ||
825 | |||
826 | {% set value = 'no spaces' %} | ||
827 | <li> {{- value }} </li> | ||
828 | |||
829 | {# outputs '<li>no spaces </li>' #} | ||
830 | |||
831 | Extensions | ||
832 | ---------- | ||
833 | |||
834 | Twig can be easily extended. | ||
835 | |||
836 | If you are looking for new tags, filters, or functions, have a look at the Twig official | ||
837 | `extension repository`_. | ||
838 | |||
839 | If you want to create your own, read the :ref:`Creating an | ||
840 | Extension<creating_extensions>` chapter. | ||
841 | |||
842 | .. _`Twig bundle`: https://github.com/Anomareh/PHP-Twig.tmbundle | ||
843 | .. _`Jinja syntax plugin`: http://jinja.pocoo.org/2/documentation/integration | ||
844 | .. _`Twig syntax plugin`: http://plugins.netbeans.org/plugin/37069/php-twig | ||
845 | .. _`Twig plugin`: https://github.com/pulse00/Twig-Eclipse-Plugin | ||
846 | .. _`Twig language definition`: https://github.com/gabrielcorpse/gedit-twig-template-language | ||
847 | .. _`extension repository`: http://github.com/fabpot/Twig-extensions | ||
848 | .. _`Twig syntax mode`: https://github.com/bobthecow/Twig-HTML.mode | ||
849 | .. _`other Twig syntax mode`: https://github.com/muxx/Twig-HTML.mode | ||
850 | .. _`Notepad++ Twig Highlighter`: https://github.com/Banane9/notepadplusplus-twig | ||
851 | .. _`web-mode.el`: http://web-mode.org/ | ||