1``extends``
2===========
3
4The ``extends`` tag can be used to extend a template from another one.
5
6.. note::
7
8    Like PHP, Twig does not support multiple inheritance. So you can only have
9    one extends tag called per rendering. However, Twig supports horizontal
10    :doc:`reuse<use>`.
11
12Let's define a base template, ``base.html``, which defines a simple HTML
13skeleton document:
14
15.. code-block:: html+jinja
16
17    <!DOCTYPE html>
18    <html>
19        <head>
20            {% block head %}
21                <link rel="stylesheet" href="style.css" />
22                <title>{% block title %}{% endblock %} - My Webpage</title>
23            {% endblock %}
24        </head>
25        <body>
26            <div id="content">{% block content %}{% endblock %}</div>
27            <div id="footer">
28                {% block footer %}
29                    &copy; Copyright 2011 by <a href="http://domain.invalid/">you</a>.
30                {% endblock %}
31            </div>
32        </body>
33    </html>
34
35In this example, the :doc:`block<block>` tags define four blocks that child
36templates can fill in.
37
38All the ``block`` tag does is to tell the template engine that a child
39template may override those portions of the template.
40
41Child Template
42--------------
43
44A child template might look like this:
45
46.. code-block:: jinja
47
48    {% extends "base.html" %}
49
50    {% block title %}Index{% endblock %}
51    {% block head %}
52        {{ parent() }}
53        <style type="text/css">
54            .important { color: #336699; }
55        </style>
56    {% endblock %}
57    {% block content %}
58        <h1>Index</h1>
59        <p class="important">
60            Welcome on my awesome homepage.
61        </p>
62    {% endblock %}
63
64The ``extends`` tag is the key here. It tells the template engine that this
65template "extends" another template. When the template system evaluates this
66template, first it locates the parent. The extends tag should be the first tag
67in the template.
68
69Note that since the child template doesn't define the ``footer`` block, the
70value from the parent template is used instead.
71
72You can't define multiple ``block`` tags with the same name in the same
73template. This limitation exists because a block tag works in "both"
74directions. That is, a block tag doesn't just provide a hole to fill - it also
75defines the content that fills the hole in the *parent*. If there were two
76similarly-named ``block`` tags in a template, that template's parent wouldn't
77know which one of the blocks' content to use.
78
79If you want to print a block multiple times you can however use the
80``block`` function:
81
82.. code-block:: jinja
83
84    <title>{% block title %}{% endblock %}</title>
85    <h1>{{ block('title') }}</h1>
86    {% block body %}{% endblock %}
87
88Parent Blocks
89-------------
90
91It's possible to render the contents of the parent block by using the
92:doc:`parent<../functions/parent>` function. This gives back the results of
93the parent block:
94
95.. code-block:: jinja
96
97    {% block sidebar %}
98        <h3>Table Of Contents</h3>
99        ...
100        {{ parent() }}
101    {% endblock %}
102
103Named Block End-Tags
104--------------------
105
106Twig allows you to put the name of the block after the end tag for better
107readability:
108
109.. code-block:: jinja
110
111    {% block sidebar %}
112        {% block inner_sidebar %}
113            ...
114        {% endblock inner_sidebar %}
115    {% endblock sidebar %}
116
117Of course, the name after the ``endblock`` word must match the block name.
118
119Block Nesting and Scope
120-----------------------
121
122Blocks can be nested for more complex layouts. Per default, blocks have access
123to variables from outer scopes:
124
125.. code-block:: jinja
126
127    {% for item in seq %}
128        <li>{% block loop_item %}{{ item }}{% endblock %}</li>
129    {% endfor %}
130
131Block Shortcuts
132---------------
133
134For blocks with little content, it's possible to use a shortcut syntax. The
135following constructs do the same thing:
136
137.. code-block:: jinja
138
139    {% block title %}
140        {{ page_title|title }}
141    {% endblock %}
142
143.. code-block:: jinja
144
145    {% block title page_title|title %}
146
147Dynamic Inheritance
148-------------------
149
150Twig supports dynamic inheritance by using a variable as the base template:
151
152.. code-block:: jinja
153
154    {% extends some_var %}
155
156If the variable evaluates to a ``\Twig\Template`` or a ``\Twig\TemplateWrapper``
157instance, Twig will use it as the parent template::
158
159    // {% extends layout %}
160
161    // deprecated as of Twig 1.28
162    $layout = $twig->loadTemplate('some_layout_template.twig');
163
164    // as of Twig 1.28
165    $layout = $twig->load('some_layout_template.twig');
166
167    $twig->display('template.twig', ['layout' => $layout]);
168
169.. versionadded:: 1.2
170    The possibility to pass an array of templates has been added in Twig 1.2.
171
172You can also provide a list of templates that are checked for existence. The
173first template that exists will be used as a parent:
174
175.. code-block:: jinja
176
177    {% extends ['layout.html', 'base_layout.html'] %}
178
179Conditional Inheritance
180-----------------------
181
182As the template name for the parent can be any valid Twig expression, it's
183possible to make the inheritance mechanism conditional:
184
185.. code-block:: jinja
186
187    {% extends standalone ? "minimum.html" : "base.html" %}
188
189In this example, the template will extend the "minimum.html" layout template
190if the ``standalone`` variable evaluates to ``true``, and "base.html"
191otherwise.
192
193How do blocks work?
194-------------------
195
196A block provides a way to change how a certain part of a template is rendered
197but it does not interfere in any way with the logic around it.
198
199Let's take the following example to illustrate how a block works and more
200importantly, how it does not work:
201
202.. code-block:: jinja
203
204    {# base.twig #}
205
206    {% for post in posts %}
207        {% block post %}
208            <h1>{{ post.title }}</h1>
209            <p>{{ post.body }}</p>
210        {% endblock %}
211    {% endfor %}
212
213If you render this template, the result would be exactly the same with or
214without the ``block`` tag. The ``block`` inside the ``for`` loop is just a way
215to make it overridable by a child template:
216
217.. code-block:: jinja
218
219    {# child.twig #}
220
221    {% extends "base.twig" %}
222
223    {% block post %}
224        <article>
225            <header>{{ post.title }}</header>
226            <section>{{ post.text }}</section>
227        </article>
228    {% endblock %}
229
230Now, when rendering the child template, the loop is going to use the block
231defined in the child template instead of the one defined in the base one; the
232executed template is then equivalent to the following one:
233
234.. code-block:: jinja
235
236    {% for post in posts %}
237        <article>
238            <header>{{ post.title }}</header>
239            <section>{{ post.text }}</section>
240        </article>
241    {% endfor %}
242
243Let's take another example: a block included within an ``if`` statement:
244
245.. code-block:: jinja
246
247    {% if posts is empty %}
248        {% block head %}
249            {{ parent() }}
250
251            <meta name="robots" content="noindex, follow">
252        {% endblock head %}
253    {% endif %}
254
255Contrary to what you might think, this template does not define a block
256conditionally; it just makes overridable by a child template the output of
257what will be rendered when the condition is ``true``.
258
259If you want the output to be displayed conditionally, use the following
260instead:
261
262.. code-block:: jinja
263
264    {% block head %}
265        {{ parent() }}
266
267        {% if posts is empty %}
268            <meta name="robots" content="noindex, follow">
269        {% endif %}
270    {% endblock head %}
271
272.. seealso:: :doc:`block<../functions/block>`, :doc:`block<../tags/block>`, :doc:`parent<../functions/parent>`, :doc:`use<../tags/use>`
273