aleph1.co.uk Git - yaffs-website/blob - 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 little content, it's possible to use a shortcut syntax. The
 135 following 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
 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`` or a ``Twig_TemplateWrapper``
 157 instance, 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', array('layout' => $layout));
 168
 169 .. versionadded:: 1.2
 170     The possibility to pass an array of templates has been added in Twig 1.2.
 171
 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:
 174
 175 .. code-block:: jinja
 176
 177     {% extends ['layout.html', 'base_layout.html'] %}
 178
 179 Conditional Inheritance
 180 -----------------------
 181
 182 As the template name for the parent can be any valid Twig expression, it's
 183 possible to make the inheritance mechanism conditional:
 184
 185 .. code-block:: jinja
 186
 187     {% extends standalone ? "minimum.html" : "base.html" %}
 188
 189 In this example, the template will extend the "minimum.html" layout template
 190 if the ``standalone`` variable evaluates to ``true``, and "base.html"
 191 otherwise.
 192
 193 How do blocks work?
 194 -------------------
 195
 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.
 198
 199 Let's take the following example to illustrate how a block works and more
 200 importantly, 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
 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:
 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
 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:
 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
 243 Let'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
 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``.
 258
 259 If you want the output to be displayed conditionally, use the following
 260 instead:
 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>`