vendor/twig/twig/doc/tags/extends.rst

   1 ``extends``
   2 ===========
   3
   4 The ``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
  12 Let's define a base template, ``base.html``, which defines a simple HTML
  13 skeleton 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
  35 In this example, the :doc:`block<block>` tags define four blocks that child
  36 templates can fill in.
  37
  38 All the ``block`` tag does is to tell the template engine that a child
  39 template may override those portions of the template.
  40
  41 Child Template
  42 --------------
  43
  44 A 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
  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
  67 in the template.
  68
  69 Note that since the child template doesn't define the ``footer`` block, the
  70 value from the parent template is used instead.
  71
  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.
  78
  79 If 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
  88 Parent Blocks
  89 -------------
  90
  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
  93 the parent block:
  94
  95 .. code-block:: jinja
  96
  97     {% block sidebar %}
  98         <h3>Table Of Contents</h3>
  99         ...
 100         {{ parent() }}
 101     {% endblock %}
 102
 103 Named Block End-Tags
 104 --------------------
 105
 106 Twig allows you to put the name of the block after the end tag for better
 107 readability:
 108
 109 .. code-block:: jinja
 110
 111     {% block sidebar %}
 112         {% block inner_sidebar %}
 113             ...
 114         {% endblock inner_sidebar %}
 115     {% endblock sidebar %}
 116
 117 Of course, the name after the ``endblock`` word must match the block name.
 118
 119 Block Nesting and Scope
 120 -----------------------
 121
 122 Blocks can be nested for more complex layouts. Per default, blocks have access
 123 to 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
 131 Block Shortcuts
 132 ---------------
 133
 134 For blocks with few content, it's possible to use a shortcut syntax. The
 135 following constructs do the same:
 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
 147 Dynamic Inheritance
 148 -------------------
 149
 150 Twig supports dynamic inheritance by using a variable as the base template:
 151
 152 .. code-block:: jinja
 153
 154     {% extends some_var %}
 155
 156 If the variable evaluates to a ``Twig_Template`` object, Twig will use it as
 157 the parent template::
 158
 159     // {% extends layout %}
 160
 161     $layout = $twig->loadTemplate('some_layout_template.twig');
 162
 163     $twig->display('template.twig', array('layout' => $layout));
 164
 165 .. versionadded:: 1.2
 166     The possibility to pass an array of templates has been added in Twig 1.2.
 167
 168 You can also provide a list of templates that are checked for existence. The
 169 first template that exists will be used as a parent:
 170
 171 .. code-block:: jinja
 172
 173     {% extends ['layout.html', 'base_layout.html'] %}
 174
 175 Conditional Inheritance
 176 -----------------------
 177
 178 As the template name for the parent can be any valid Twig expression, it's
 179 possible to make the inheritance mechanism conditional:
 180
 181 .. code-block:: jinja
 182
 183     {% extends standalone ? "minimum.html" : "base.html" %}
 184
 185 In this example, the template will extend the "minimum.html" layout template
 186 if the ``standalone`` variable evaluates to ``true``, and "base.html"
 187 otherwise.
 188
 189 How blocks work?
 190 ----------------
 191
 192 A block provides a way to change how a certain part of a template is rendered
 193 but it does not interfere in any way with the logic around it.
 194
 195 Let's take the following example to illustrate how a block work and more
 196 importantly, how it does not work:
 197
 198 .. code-block:: jinja
 199
 200     {# base.twig #}
 201
 202     {% for post in posts %}
 203         {% block post %}
 204             <h1>{{ post.title }}</h1>
 205             <p>{{ post.body }}</p>
 206         {% endblock %}
 207     {% endfor %}
 208
 209 If you render this template, the result would be exactly the same with or
 210 without the ``block`` tag. The ``block`` inside the ``for`` loop is just a way
 211 to make it overridable by a child template:
 212
 213 .. code-block:: jinja
 214
 215     {# child.twig #}
 216
 217     {% extends "base.twig" %}
 218
 219     {% block post %}
 220         <article>
 221             <header>{{ post.title }}</header>
 222             <section>{{ post.text }}</section>
 223         </article>
 224     {% endblock %}
 225
 226 Now, when rendering the child template, the loop is going to use the block
 227 defined in the child template instead of the one defined in the base one; the
 228 executed template is then equivalent to the following one:
 229
 230 .. code-block:: jinja
 231
 232     {% for post in posts %}
 233         <article>
 234             <header>{{ post.title }}</header>
 235             <section>{{ post.text }}</section>
 236         </article>
 237     {% endfor %}
 238
 239 Let's take another example: a block included within an ``if`` statement:
 240
 241 .. code-block:: jinja
 242
 243     {% if posts is empty %}
 244         {% block head %}
 245             {{ parent() }}
 246
 247             <meta name="robots" content="noindex, follow">
 248         {% endblock head %}
 249     {% endif %}
 250
 251 Contrary to what you might think, this template does not define a block
 252 conditionally; it just makes overridable by a child template the output of
 253 what will be rendered when the condition is ``true``.
 254
 255 If you want the output to be displayed conditionally, use the following
 256 instead:
 257
 258 .. code-block:: jinja
 259
 260     {% block head %}
 261         {{ parent() }}
 262
 263         {% if posts is empty %}
 264             <meta name="robots" content="noindex, follow">
 265         {% endif %}
 266     {% endblock head %}
 267
 268 .. seealso:: :doc:`block<../functions/block>`, :doc:`block<../tags/block>`, :doc:`parent<../functions/parent>`, :doc:`use<../tags/use>`