]> git.immae.eu Git - github/wallabag/wallabag.git/blob - vendor/twig/twig/doc/templates.rst
gitignore vendor
[github/wallabag/wallabag.git] / vendor / twig / twig / doc / templates.rst
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 &copy; 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/