Tags

verbatim

The verbatim tag marks sections as being raw text that should not be parsed. For example to put Twig syntax as example into a template you can use this snippet:

{% verbatim %}
    <ul>
    {% for item in seq %}
        <li>{{ item }}</li>
    {% endfor %}
    </ul>
{% endverbatim %}

The verbatim tag works in the exact same way as the old raw tag, but was renamed to avoid confusion with the raw filter.

use

Template inheritance is one of the most powerful Twig's feature but it is limited to single inheritance; a template can only extend one other template. This limitation makes template inheritance simple to understand and easy to debug:

{% extends "base.html" %}

{% block title %}{% endblock %}
{% block content %}{% endblock %}

Horizontal reuse is a way to achieve the same goal as multiple inheritance, but without the associated complexity:

{% extends "base.html" %}

{% use "blocks.html" %}

{% block title %}{% endblock %}
{% block content %}{% endblock %}

The use statement tells Twig to import the blocks defined in blocks.html into the current template (it's like macros, but for blocks):

{# blocks.html #}

{% block sidebar %}{% endblock %}

In this example, the use statement imports the sidebar block into the main template. The code is mostly equivalent to the following one (the imported blocks are not outputted automatically):

{% extends "base.html" %}

{% block sidebar %}{% endblock %}
{% block title %}{% endblock %}
{% block content %}{% endblock %}

The use tag only imports a template if it does not extend another template, if it does not define macros, and if the body is empty. But it can use other templates.
Because use statements are resolved independently of the context passed to the template, the template reference cannot be an expression.

The main template can also override any imported block. If the template already defines the sidebar block, then the one defined in blocks.html is ignored. To avoid name conflicts, you can rename imported blocks:

{% extends "base.html" %}

{% use "blocks.html" with sidebar as base_sidebar, title as base_title %}

{% block sidebar %}{% endblock %}
{% block title %}{% endblock %}
{% block content %}{% endblock %}

The parent() function automatically determines the correct inheritance tree, so it can be used when overriding a block defined in an imported template:

{% extends "base.html" %}

{% use "blocks.html" %}

{% block sidebar %}
    {{ parent() }}
{% endblock %}

{% block title %}{% endblock %}
{% block content %}{% endblock %}

In this example, parent() will correctly call the sidebar block from the blocks.html template.

spaceless

Use the spaceless tag to remove whitespace between HTML tags, not whitespace within HTML tags or whitespace in plain text:

{% spaceless %}
    <div>
        <strong>foo</strong>
    </div>
{% endspaceless %}

{# output will be <div><strong>foo</strong></div> #}

This tag is not meant to "optimize" the size of the generated HTML content but merely to avoid extra whitespace between HTML tags to avoid browser rendering quirks under some circumstances.

set

Inside code blocks you can also assign values to variables. Assignments use the set tag and can have multiple targets.

Here is how you can assign the bar value to the foo variable:

{% set foo = 'bar' %}

After the set call, the foo variable is available in the template like any other ones:

{# displays bar #}
{{ foo }}

The assigned value can be any valid Twig Expressions:

{% set foo = [1, 2] %}
{% set foo = {'foo': 'bar'} %}
{% set foo = 'foo' ~ 'bar' %}

The assigned value can be any valid Twig Expressions:

{% set foo, bar = 'foo', 'bar' %}

{# is equivalent to #}

{% set foo = 'foo' %}
{% set bar = 'bar' %}

The set tag can also be used to 'capture' chunks of text:

{% set foo %}
    <div id="pagination">
        ...
    </div>
{% endset %}

macro

Macros are comparable with functions in regular programming languages. They are useful to put often used HTML idioms into reusable elements to not repeat yourself.

Here is a small example of a macro that renders a form element:

{% macro input(name, value, type, size) %}
    <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" />
{% endmacro %}

Macros differs from native PHP functions in a few ways:

• Default argument values are defined by using the default filter in the macro body;
• Arguments of a macro are always optional.
• If extra positional arguments are passed to a macro, they end up in the special varargs variable as a list of values.

But as with PHP functions, macros don't have access to the current template variables.

You can pass the whole context as an argument by using the special _context variable.

Macros can be defined in any template, and need to be "imported" before being used (see the documentation for the import tag for more information):

{% import "forms.html" as forms %}

The above import call imports the "forms.html" file (which can contain only macros, or a template and some macros), and import the functions as items of the forms variable.

The macro can then be called at will:

<p>{{ forms.input('username') }}</p>
<p>{{ forms.input('password', null, 'password') }}</p>

If macros are defined and used in the same template, you can use the special _self variable to import them:

{% import _self as forms %}

<p>{{ forms.input('username') }}</p>

When you want to use a macro in another macro from the same file, you need to import it locally:

{% macro input(name, value, type, size) %}
    <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" />
{% endmacro %}

{% macro wrapped_input(name, value, type, size) %}
    {% import _self as forms %}

    <div class="field">
        {{ forms.input(name, value, type, size) }}
    </div>
{% endmacro %}

include

The include statement includes a template and returns the rendered content of that file into the current namespace:

{% include 'header.html' %}
    Body
{% include 'footer.html' %}

Included templates have access to the variables of the active context.

If you are using the filesystem loader, the templates are looked for in the paths defined by it.

You can add additional variables by passing them after the with keyword:

{# template.html will have access to the variables from the current context and the additional ones provided #}
{% include 'template.html' with {'foo': 'bar'} %}

{% set vars = {'foo': 'bar'} %}
{% include 'template.html' with vars %}

You can disable access to the context by appending the only keyword:

{# only the foo variable will be accessible #}
{% include 'template.html' with {'foo': 'bar'} only %}

{# no variables will be accessible #}
{% include 'template.html' only %}

The template name can be any valid Twig expression:

{% include some_var %}
{% include ajax ? 'ajax.html' : 'not_ajax.html' %}

You can mark an include with ignore missing in which case Twig will ignore the statement if the template to be included does not exist. It has to be placed just after the template name.

Here some valid examples:

{% include 'sidebar.html' ignore missing %}
{% include 'sidebar.html' ignore missing with {'foo': 'bar'} %}
{% include 'sidebar.html' ignore missing only %}

You can also provide a list of templates that are checked for existence before inclusion. The first template that exists will be included:

{% include ['page_detailed.html', 'page.html'] %}

If ignore missing is given, it will fall back to rendering nothing if none of the templates exist, otherwise it will throw an exception.

import

Twig supports putting often used code into macros. These macros can go into different templates and get imported from there.

There are two ways to import templates. You can import the complete template into a variable or request specific macros from it.

Imagine we have a helper module that renders forms (called forms.html):

{% macro input(name, value, type, size) %}
    <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" />
{% endmacro %}

{% macro textarea(name, value, rows, cols) %}
    <textarea name="{{ name }}" rows="{{ rows|default(10) }}" cols="{{ cols|default(40) }}">{{ value|e }}</textarea>
{% endmacro %}

The easiest and most flexible is importing the whole module into a variable. That way you can access the attributes:

{% import 'forms.html' as forms %}

<dl>
    <dt>Username</dt>
    <dd>{{ forms.input('username') }}</dd>
    <dt>Password</dt>
    <dd>{{ forms.input('password', null, 'password') }}</dd>
</dl>
<p>{{ forms.textarea('comment') }}</p>

Alternatively you can import names from the template into the current namespace:

{% from 'forms.html' import input as input_field, textarea %}

<dl>
    <dt>Username</dt>
    <dd>{{ input_field('username') }}</dd>
    <dt>Password</dt>
    <dd>{{ input_field('password', '', 'password') }}</dd>
</dl>
<p>{{ textarea('comment') }}</p>

To import macros from the current file, use the special _self variable for the source.

if

The if statement in Twig is comparable with the if statements of PHP.

In the simplest form you can use it to test if an expression evaluates to true:

{% if online == false %}
    <p>Our website is in maintenance mode. Please, come back later.</p>
{% endif %}

You can also test if an array is not empty:

{% if products %}
    <ul>
        {% for product in products %}
            <li>{{ product.title|e }}</li>
        {% endfor %}
    </ul>
{% endif %}

You can also use not to check for values that evaluate to false:

{% if not user.subscribed %}
    <p>You are not subscribed to our mailing list.</p>
{% endif %}

For multiple conditions, and and or can be used:

{% if temperature > 18 and temperature < 27 %}
    <p>It's a nice day for a walk in the park.</p>
{% endif %}

For multiple branches elseif and else can be used like in PHP. You can use more complex expressions there too:

{% if kenny.sick %}
    Kenny is sick.
{% elseif kenny.dead %}
    You killed Kenny! You bastard!!!
{% else %}
    Kenny looks okay --- so far
{% endif %}

The rules to determine if an expression is true or false are the same as in PHP; here are the edge cases rules:

Value	Boolean evaluation
empty string	false
numeric zero	false
whitespace-only string	true
empty array	false
null	false
non-empty array	true
object	true

from

The from tag imports macro names into the current namespace. The tag is documented in detail in the documentation for the import tag.

for

Loop over each item in a sequence. For example, to display a list of users provided in a variable called products:

<h1>Products</h1>
<ul>
    {% for product in products %}
        <li>{{ product.title|e }}</li>
    {% endfor %}
</ul>

If you do need to iterate over a sequence of numbers, you can use the .. operator:

{% for i in 0..10 %}
    * {{ i }}
{% endfor %}

The above snippet of code would print all numbers from 0 to 10.

It can be also useful with letters:

{% for letter in 'a'..'z' %}
    * {{ letter }}
{% endfor %}

The .. operator can take any expression at both sides:

{% for letter in 'a'|upper..'z'|upper %}
    * {{ letter }}
{% endfor %}

The loop variable
Inside of a for loop block you can access some special variables:

Variable	Description
loop.index	The current iteration of the loop. (1 indexed)
loop.index0	The current iteration of the loop. (0 indexed)
loop.revindex	The number of iterations from the end of the loop (1 indexed)
loop.revindex0	The number of iterations from the end of the loop (0 indexed)
loop.first	True if first iteration
loop.last	True if last iteration
loop.length	The number of items in the sequence
loop.parent	The parent context

{% for product in products %}
    {{ loop.index }} - {{ product.title }}
{% endfor %}

Adding a condition
Unlike in PHP, it's not possible to break or continue in a loop. You can however filter the sequence during iteration which allows you to skip items.

The following example skips all the users which are not active:

<ul>
    {% for product in products if product.type == 3 %}
        <li>{{ product.title|e }}</li>
    {% endfor %}
</ul>

The advantage is that the special loop variable will count correctly thus not counting the users not iterated over. Keep in mind that properties like loop.last will not be defined when using loop conditions.

The else Clause

If no iteration took place because the sequence was empty, you can render a replacement block by using else:

<ul>
    {% for product in products %}
        <li>{{ product.title|e }}</li>
    {% else %}
        <li><em>no product found</em></li>
    {% endfor %}
</ul>

Iterating over Keys
By default, a loop iterates over the values of the sequence.

You can iterate on keys by using the keys filter:

<h1>Products</h1>
<ul>
    {% for key in products|keys %}
        <li>{{ key }}</li>
    {% endfor %}
</ul>

Iterating over Keys and Values

You can also access both keys and values:

<h1>Products</h1>
<ul>
    {% for key, product in products %}
        <li>{{ key }}: {{ product.title|e }}</li>
    {% endfor %}
</ul>

Iterating over a Sublet
You might want to iterate over a subset of values.

This can be achieved using the slice filter:

<h1>Top Ten Products</h1>
<ul>
    {% for product in products|slice(0, 10) %}
        <li>{{ product.title|e }}</li>
    {% endfor %}
</ul>

flush

The flush tag tells Twig to flush the output buffer:

{% flush %}

filter

Filter sections allow you to apply regular Twig filters on a block of template data.

Just wrap the code in the special filter section:

{% filter upper %}
    This text becomes uppercase
{% endfilter %}

You can also chain filters:

{% filter lower|escape %}
    <strong>SOME TEXT</strong>
{% endfilter %}

{# outputs "&lt;strong&gt;some text&lt;/strong&gt;" #}

extends

The extends tag can be used to extend a template from another one.

Let's define a base template, base.html, which defines a simple HTML skeleton document:

<!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 %}
                &copy; Copyright 2011 by <a href="http://domain.invalid/">you</a>.
            {% endblock %}
        </div>
    </body>
</html>

In this example, the 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.

Child Template

A child template might look like this:

{% 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 on my awesome homepage.
    </p>
{% endblock %}

The 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.

You can't define multiple block tags with the same name in the same template. This limitation exists because a block tag works in "both" directions. That is, a block tag doesn't just provide a hole to fill - it also defines the content that fills the hole in the parent. If there were two similarly-named block tags in a template, that template's parent wouldn't know which one of the blocks' content to use.

If you want to print a block multiple times you can however use the block function:

<title>{% block title %}{% endblock %}</title>
<h1>{{ block('title') }}</h1>
{% block body %}{% endblock %}

Parent Blocks

It's possible to render the contents of the parent block by using the parent function. This gives back the results of the parent block:

{% block sidebar %}
    <h3>Table Of Contents</h3>
    ...
    {{ parent() }}
{% endblock %}

Named Block-End Tags

Twig allows you to put the name of the block after the end tag for better readability:

{% block sidebar %}
    {% block inner_sidebar %}
        ...
    {% endblock inner_sidebar %}
{% endblock sidebar %}

Of course, the name after the endblock word must match the block name.

Block Nesting & Scope

Blocks can be nested for more complex layouts. Per default, blocks have access to variables from outer scopes:

{% for item in seq %}
    <li>{% block loop_item %}{{ item }}{% endblock %}</li>
{% endfor %}

Block Shortcuts

For blocks with little content, it's possible to use a shortcut syntax. The following constructs do the same thing:

{% block title %}
    {{ page_title|title }}
{% endblock %}

{% block title page_title|title %}

Conditional Inheritance

As the template name for the parent can be any valid Twig expression, it's possible to make the inheritance mechanism conditional:

{% extends standalone ? "minimum.html" : "base.html" %}

In this example, the template will extend the "minimum.html" layout template if the standalone variable evaluates to true, and "base.html" otherwise.

How do blocks work?
A block provides a way to change how a certain part of a template is rendered but it does not interfere in any way with the logic around it.

Let's take the following example to illustrate how a block works and more importantly, how it does not work:

{# base.twig #}

{% for post in posts %}
    {% block post %}
        <h1>{{ post.title }}</h1>
        <p>{{ post.body }}</p>
    {% endblock %}
{% endfor %}

If you render this template, the result would be exactly the same with or without the block tag. The block inside the for loop is just a way to make it overridable by a child template:

{# child.twig #}

{% extends "base.twig" %}

{% block post %}
    <article>
        <header>{{ post.title }}</header>
        <section>{{ post.text }}</section>
    </article>
{% endblock %}

Now, when rendering the child template, the loop is going to use the block defined in the child template instead of the one defined in the base one; the executed template is then equivalent to the following one:

{% for post in posts %}
    <article>
        <header>{{ post.title }}</header>
        <section>{{ post.text }}</section>
    </article>
{% endfor %}

Let's take another example: a block included within an if statement:

{% if posts is empty %}
    {% block head %}
        {{ parent() }}

        <meta name="robots" content="noindex, follow">
    {% endblock head %}
{% endif %}

Contrary to what you might think, this template does not define a block conditionally; it just makes overridable by a child template the output of what will be rendered when the condition is true.

If you want the output to be displayed conditionally, use the following instead:

{% block head %}
    {{ parent() }}

    {% if posts is empty %}
        <meta name="robots" content="noindex, follow">
    {% endif %}
{% endblock head %}

embed

The embed tag combines the behaviour of include and extends. It allows you to include another template's contents, just like include does. But it also allows you to override any block defined inside the included template, like when extending a template.

Think of an embedded template as a "micro layout skeleton".

{% embed "teasers_skeleton.twig" %}
    {# These blocks are defined in "teasers_skeleton.twig" #}
    {# and we override them right here:                    #}
    {% block left_teaser %}
        Some content for the left teaser box
    {% endblock %}
    {% block right_teaser %}
        Some content for the right teaser box
    {% endblock %}
{% endembed %}

The embed tag takes the idea of template inheritance to the level of content fragments. While template inheritance allows for "document skeletons", which are filled with life by child templates, the embed tag allows you to create "skeletons" for smaller units of content and re-use and fill them anywhere you like.

Since the use case may not be obvious, let's look at a simplified example. Imagine a base template shared by multiple HTML pages, defining a single block named "content":

┌─── page layout ─────────────────────┐
│                                     │
│           ┌── block "content" ──┐   │
│           │                     │   │
│           │                     │   │
│           │ (child template to  │   │
│           │  put content here)  │   │
│           │                     │   │
│           │                     │   │
│           └─────────────────────┘   │
│                                     │
└─────────────────────────────────────┘

Some pages ("foo" and "bar") share the same content structure - two vertically stacked boxes:

┌─── page layout ─────────────────────┐
│                                     │
│           ┌── block "content" ──┐   │
│           │ ┌─ block "top" ───┐ │   │
│           │ │                 │ │   │
│           │ └─────────────────┘ │   │
│           │ ┌─ block "bottom" ┐ │   │
│           │ │                 │ │   │
│           │ └─────────────────┘ │   │
│           └─────────────────────┘   │
│                                     │
└─────────────────────────────────────┘

While other pages ("boom" and "baz") share a different content structure - two boxes side by side:

┌─── page layout ─────────────────────┐
│                                     │
│           ┌── block "content" ──┐   │
│           │                     │   │
│           │ ┌ block ┐ ┌ block ┐ │   │
│           │ │"left" │ │"right"│ │   │
│           │ │       │ │       │ │   │
│           │ │       │ │       │ │   │
│           │ └───────┘ └───────┘ │   │
│           └─────────────────────┘   │
│                                     │
└─────────────────────────────────────┘

Without the embed tag, you have two ways to design your templates:

• Create two "intermediate" base templates that extend the master layout template: one with vertically stacked boxes to be used by the "foo" and "bar" pages and another one with side-by-side boxes for the "boom" and "baz" pages.
• Embed the markup for the top/bottom and left/right boxes into each page template directly.

These two solutions do not scale well because they each have a major drawback:

• The first solution may indeed work for this simplified example. But imagine we add a sidebar, which may again contain different, recurring structures of content. Now we would need to create intermediate base templates for all occurring combinations of content structure and sidebar structure... and so on.
• The second solution involves duplication of common code with all its negative consequences: any change involves finding and editing all affected copies of the structure, correctness has to be verified for each copy, copies may go out of sync by careless modifications etc.

In such a situation, the embed tag comes in handy. The common layout code can live in a single base template, and the two different content structures, let's call them "micro layouts" go into separate templates which are embedded as necessary:

Page template foo.twig:

{% extends "layout_skeleton.twig" %}

{% block content %}
    {% embed "vertical_boxes_skeleton.twig" %}
        {% block top %}
            Some content for the top box
        {% endblock %}

        {% block bottom %}
            Some content for the bottom box
        {% endblock %}
    {% endembed %}
{% endblock %}

And here is the code for vertical_boxes_skeleton.twig:

<div class="top_box">
    {% block top %}
        Top box default content
    {% endblock %}
</div>

<div class="bottom_box">
    {% block bottom %}
        Bottom box default content
    {% endblock %}
</div>

The goal of the vertical_boxes_skeleton.twig template being to factor out the HTML markup for the boxes.

The embed tag takes the exact same arguments as the include tag:

{% embed "base" with {'foo': 'bar'} %}
    ...
{% endembed %}

{% embed "base" with {'foo': 'bar'} only %}
    ...
{% endembed %}

{% embed "base" ignore missing %}
    ...
{% endembed %}

As embedded templates do not have "names", auto-escaping strategies based on the template "filename" won't work as expected if you change the context (for instance, if you embed a CSS/JavaScript template into an HTML one). In that case, explicitly set the default auto-escaping strategy with the autoescape tag.

do

The do tag works exactly like the regular variable expression ({{ ... }}) just that it doesn't print anything:

{% do 1 + 2 %}

block

Blocks are used for inheritance and act as placeholders and replacements at the same time. They are documented in detail in the documentation for the extends tag.

Block names should consist of alphanumeric characters, and underscores. Dashes are not permitted.

autoescape

Whether automatic escaping is enabled or not, you can mark a section of a template to be escaped or not by using the autoescape tag:

{% autoescape %}
    Everything will be automatically escaped in this block
    using the HTML strategy
{% endautoescape %}

{% autoescape 'html' %}
    Everything will be automatically escaped in this block
    using the HTML strategy
{% endautoescape %}

{% autoescape 'js' %}
    Everything will be automatically escaped in this block
    using the js escaping strategy
{% endautoescape %}

{% autoescape false %}
    Everything will be outputted as is in this block
{% endautoescape %}

When automatic escaping is enabled everything is escaped by default except for values explicitly marked as safe. Those can be marked in the template by using the raw filter:

{% autoescape %}
    {{ safe_value|raw }}
{% endautoescape %}

Functions returning template data (like macros and parent) always return safe markup.