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