4 The ``extends`` tag can be used to extend a template from another one.
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
12 Let's define a base template, ``base.html``, which defines a simple HTML
15 .. code-block:: html+jinja
21 <link rel="stylesheet" href="style.css" />
22 <title>{% block title %}{% endblock %} - My Webpage</title>
26 <div id="content">{% block content %}{% endblock %}</div>
29 © Copyright 2011 by <a href="http://domain.invalid/">you</a>.
35 In this example, the :doc:`block<block>` tags define four blocks that child
36 templates can fill in.
38 All the ``block`` tag does is to tell the template engine that a child
39 template may override those portions of the template.
44 A child template might look like this:
48 {% extends "base.html" %}
50 {% block title %}Index{% endblock %}
53 <style type="text/css">
54 .important { color: #336699; }
60 Welcome on my awesome homepage.
64 The ``extends`` tag is the key here. It tells the template engine that this
65 template "extends" another template. When the template system evaluates this
66 template, first it locates the parent. The extends tag should be the first tag
69 Note that since the child template doesn't define the ``footer`` block, the
70 value from the parent template is used instead.
72 You can't define multiple ``block`` tags with the same name in the same
73 template. This limitation exists because a block tag works in "both"
74 directions. That is, a block tag doesn't just provide a hole to fill - it also
75 defines the content that fills the hole in the *parent*. If there were two
76 similarly-named ``block`` tags in a template, that template's parent wouldn't
77 know which one of the blocks' content to use.
79 If you want to print a block multiple times you can however use the
84 <title>{% block title %}{% endblock %}</title>
85 <h1>{{ block('title') }}</h1>
86 {% block body %}{% endblock %}
91 It'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
98 <h3>Table Of Contents</h3>
106 Twig allows you to put the name of the block after the end tag for better
109 .. code-block:: jinja
112 {% block inner_sidebar %}
114 {% endblock inner_sidebar %}
115 {% endblock sidebar %}
117 Of course, the name after the ``endblock`` word must match the block name.
119 Block Nesting and Scope
120 -----------------------
122 Blocks can be nested for more complex layouts. Per default, blocks have access
123 to variables from outer scopes:
125 .. code-block:: jinja
127 {% for item in seq %}
128 <li>{% block loop_item %}{{ item }}{% endblock %}</li>
134 For blocks with little content, it's possible to use a shortcut syntax. The
135 following constructs do the same thing:
137 .. code-block:: jinja
140 {{ page_title|title }}
143 .. code-block:: jinja
145 {% block title page_title|title %}
150 Twig supports dynamic inheritance by using a variable as the base template:
152 .. code-block:: jinja
154 {% extends some_var %}
156 If the variable evaluates to a ``Twig_Template`` or a ``Twig_TemplateWrapper``
157 instance, Twig will use it as the parent template::
159 // {% extends layout %}
161 // deprecated as of Twig 1.28
162 $layout = $twig->loadTemplate('some_layout_template.twig');
165 $layout = $twig->load('some_layout_template.twig');
167 $twig->display('template.twig', array('layout' => $layout));
169 .. versionadded:: 1.2
170 The possibility to pass an array of templates has been added in Twig 1.2.
172 You can also provide a list of templates that are checked for existence. The
173 first template that exists will be used as a parent:
175 .. code-block:: jinja
177 {% extends ['layout.html', 'base_layout.html'] %}
179 Conditional Inheritance
180 -----------------------
182 As the template name for the parent can be any valid Twig expression, it's
183 possible to make the inheritance mechanism conditional:
185 .. code-block:: jinja
187 {% extends standalone ? "minimum.html" : "base.html" %}
189 In this example, the template will extend the "minimum.html" layout template
190 if the ``standalone`` variable evaluates to ``true``, and "base.html"
196 A block provides a way to change how a certain part of a template is rendered
197 but it does not interfere in any way with the logic around it.
199 Let's take the following example to illustrate how a block works and more
200 importantly, how it does not work:
202 .. code-block:: jinja
206 {% for post in posts %}
208 <h1>{{ post.title }}</h1>
209 <p>{{ post.body }}</p>
213 If you render this template, the result would be exactly the same with or
214 without the ``block`` tag. The ``block`` inside the ``for`` loop is just a way
215 to make it overridable by a child template:
217 .. code-block:: jinja
221 {% extends "base.twig" %}
225 <header>{{ post.title }}</header>
226 <section>{{ post.text }}</section>
230 Now, when rendering the child template, the loop is going to use the block
231 defined in the child template instead of the one defined in the base one; the
232 executed template is then equivalent to the following one:
234 .. code-block:: jinja
236 {% for post in posts %}
238 <header>{{ post.title }}</header>
239 <section>{{ post.text }}</section>
243 Let's take another example: a block included within an ``if`` statement:
245 .. code-block:: jinja
247 {% if posts is empty %}
251 <meta name="robots" content="noindex, follow">
255 Contrary to what you might think, this template does not define a block
256 conditionally; it just makes overridable by a child template the output of
257 what will be rendered when the condition is ``true``.
259 If you want the output to be displayed conditionally, use the following
262 .. code-block:: jinja
267 {% if posts is empty %}
268 <meta name="robots" content="noindex, follow">
272 .. seealso:: :doc:`block<../functions/block>`, :doc:`block<../tags/block>`, :doc:`parent<../functions/parent>`, :doc:`use<../tags/use>`