diff options
Diffstat (limited to 'vendor/twig/twig/doc/tags/extends.rst')
-rw-r--r-- | vendor/twig/twig/doc/tags/extends.rst | 268 |
1 files changed, 268 insertions, 0 deletions
diff --git a/vendor/twig/twig/doc/tags/extends.rst b/vendor/twig/twig/doc/tags/extends.rst new file mode 100644 index 00000000..f995a5dc --- /dev/null +++ b/vendor/twig/twig/doc/tags/extends.rst | |||
@@ -0,0 +1,268 @@ | |||
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 | © 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>` | ||