extends · Twig

# `extends` The `extends` tag can be used to extend a template from another one. Note Like PHP, Twig does not support multiple inheritance. So you can only haveone extends tag called per rendering. However, Twig supports horizontal[*reuse*](#). Let's define a base template, `base.html`, which defines a simple HTMLskeleton document: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17</pre></div></td><td class="code"><div class="highlight"><pre><!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> </pre></div></td></tr></table> In this example, the [*block*](#) tags define four blocks that childtemplates can fill in. All the `block` tag does is to tell the template engine that a childtemplate may override those portions of the template. ### Child Template A child template might look like this: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15</pre></div></td><td class="code"><div class="highlight"><pre>{% 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 %} </pre></div></td></tr></table> The `extends` tag is the key here. It tells the template engine that thistemplate "extends" another template. When the template system evaluates thistemplate, first it locates the parent. The extends tag should be the first tagin the template. Note that since the child template doesn't define the `footer` block, thevalue from the parent template is used instead. You can't define multiple `block` tags with the same name in the sametemplate. 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 alsodefines the content that fills the hole in the *parent*. If there were twosimilarly-named `block` tags in a template, that template's parent wouldn'tknow which one of the blocks' content to use. If you want to print a block multiple times you can however use the`block` function: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1 2 3</pre></div></td><td class="code"><div class="highlight"><pre><title>{% block title %}{% endblock %}</title> <h1>{{ block('title') }}</h1> {% block body %}{% endblock %} </pre></div></td></tr></table> ### Parent Blocks It's possible to render the contents of the parent block by using the[*parent*](#) function. This gives back the results ofthe parent block: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1 2 3 4 5</pre></div></td><td class="code"><div class="highlight"><pre>{% block sidebar %} <h3>Table Of Contents</h3> ... {{ parent() }} {% endblock %} </pre></div></td></tr></table> ### Named Block End-Tags Twig allows you to put the name of the block after the end tag for betterreadability: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1 2 3 4 5</pre></div></td><td class="code"><div class="highlight"><pre>{% block sidebar %} {% block inner_sidebar %} ... {% endblock inner_sidebar %} {% endblock sidebar %} </pre></div></td></tr></table> Of course, the name after the `endblock` word must match the block name. ### Block Nesting and Scope Blocks can be nested for more complex layouts. Per default, blocks have accessto variables from outer scopes: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1 2 3</pre></div></td><td class="code"><div class="highlight"><pre>{% for item in seq %} <li>{% block loop_item %}{{ item }}{% endblock %}</li> {% endfor %} </pre></div></td></tr></table> ### Block Shortcuts For blocks with few content, it's possible to use a shortcut syntax. Thefollowing constructs do the same: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1 2 3</pre></div></td><td class="code"><div class="highlight"><pre>{% block title %} {{ page_title|title }} {% endblock %} </pre></div></td></tr></table> <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre>{% block title page_title|title %} </pre></div></td></tr></table> ### Dynamic Inheritance Twig supports dynamic inheritance by using a variable as the base template: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre>{% extends some_var %} </pre></div></td></tr></table> If the variable evaluates to a `Twig_Template` object, Twig will use it asthe parent template: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1 2 3 4 5</pre></div></td><td class="code"><div class="highlight"><pre>// {% extends layout %} $layout = $twig->loadTemplate('some_layout_template.twig'); $twig->display('template.twig', array('layout' => $layout)); </pre></div></td></tr></table> New in version 1.2: The possibility to pass an array of templates has been added in Twig 1.2. You can also provide a list of templates that are checked for existence. Thefirst template that exists will be used as a parent: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre>{% extends ['layout.html', 'base_layout.html'] %} </pre></div></td></tr></table> ### Conditional Inheritance As the template name for the parent can be any valid Twig expression, it'spossible to make the inheritance mechanism conditional: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre>{% extends standalone ? "minimum.html" : "base.html" %} </pre></div></td></tr></table> In this example, the template will extend the "minimum.html" layout templateif 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 renderedbut 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 moreimportantly, how it does not work: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1 2 3 4 5 6 7 8</pre></div></td><td class="code"><div class="highlight"><pre>{# base.twig #} {% for post in posts %} {% block post %} <h1>{{ post.title }}</h1> <p>{{ post.body }}</p> {% endblock %} {% endfor %} </pre></div></td></tr></table> If you render this template, the result would be exactly the same with orwithout the `block` tag. The `block` inside the `for` loop is just a wayto make it overridable by a child template: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1 2 3 4 5 6 7 8 9 10</pre></div></td><td class="code"><div class="highlight"><pre>{# child.twig #} {% extends "base.twig" %} {% block post %} <article> <header>{{ post.title }}</header> <section>{{ post.text }}</section> </article> {% endblock %} </pre></div></td></tr></table> Now, when rendering the child template, the loop is going to use the blockdefined in the child template instead of the one defined in the base one; theexecuted template is then equivalent to the following one: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1 2 3 4 5 6</pre></div></td><td class="code"><div class="highlight"><pre>{% for post in posts %} <article> <header>{{ post.title }}</header> <section>{{ post.text }}</section> </article> {% endfor %} </pre></div></td></tr></table> Let's take another example: a block included within an `if` statement: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1 2 3 4 5 6 7</pre></div></td><td class="code"><div class="highlight"><pre>{% if posts is empty %} {% block head %} {{ parent() }} <meta name="robots" content="noindex, follow"> {% endblock head %} {% endif %} </pre></div></td></tr></table> Contrary to what you might think, this template does not define a blockconditionally; it just makes overridable by a child template the output ofwhat will be rendered when the condition is `true`. If you want the output to be displayed conditionally, use the followinginstead: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1 2 3 4 5 6 7</pre></div></td><td class="code"><div class="highlight"><pre>{% block head %} {{ parent() }} {% if posts is empty %} <meta name="robots" content="noindex, follow"> {% endif %} {% endblock head %} </pre></div></td></tr></table> See also [*block*](#), [*block*](#), [*parent*](#), [*use*](#)