diff options
Diffstat (limited to 'vendor/twig/twig/doc/tags/embed.rst')
-rw-r--r-- | vendor/twig/twig/doc/tags/embed.rst | 178 |
1 files changed, 178 insertions, 0 deletions
diff --git a/vendor/twig/twig/doc/tags/embed.rst b/vendor/twig/twig/doc/tags/embed.rst new file mode 100644 index 00000000..5a6a0299 --- /dev/null +++ b/vendor/twig/twig/doc/tags/embed.rst | |||
@@ -0,0 +1,178 @@ | |||
1 | ``embed`` | ||
2 | ========= | ||
3 | |||
4 | .. versionadded:: 1.8 | ||
5 | The ``embed`` tag was added in Twig 1.8. | ||
6 | |||
7 | The ``embed`` tag combines the behaviour of :doc:`include<include>` and | ||
8 | :doc:`extends<extends>`. | ||
9 | It allows you to include another template's contents, just like ``include`` | ||
10 | does. But it also allows you to override any block defined inside the | ||
11 | included template, like when extending a template. | ||
12 | |||
13 | Think of an embedded template as a "micro layout skeleton". | ||
14 | |||
15 | .. code-block:: jinja | ||
16 | |||
17 | {% embed "teasers_skeleton.twig" %} | ||
18 | {# These blocks are defined in "teasers_skeleton.twig" #} | ||
19 | {# and we override them right here: #} | ||
20 | {% block left_teaser %} | ||
21 | Some content for the left teaser box | ||
22 | {% endblock %} | ||
23 | {% block right_teaser %} | ||
24 | Some content for the right teaser box | ||
25 | {% endblock %} | ||
26 | {% endembed %} | ||
27 | |||
28 | The ``embed`` tag takes the idea of template inheritance to the level of | ||
29 | content fragments. While template inheritance allows for "document skeletons", | ||
30 | which are filled with life by child templates, the ``embed`` tag allows you to | ||
31 | create "skeletons" for smaller units of content and re-use and fill them | ||
32 | anywhere you like. | ||
33 | |||
34 | Since the use case may not be obvious, let's look at a simplified example. | ||
35 | Imagine a base template shared by multiple HTML pages, defining a single block | ||
36 | named "content": | ||
37 | |||
38 | .. code-block:: text | ||
39 | |||
40 | ┌─── page layout ─────────────────────┐ | ||
41 | │ │ | ||
42 | │ ┌── block "content" ──┐ │ | ||
43 | │ │ │ │ | ||
44 | │ │ │ │ | ||
45 | │ │ (child template to │ │ | ||
46 | │ │ put content here) │ │ | ||
47 | │ │ │ │ | ||
48 | │ │ │ │ | ||
49 | │ └─────────────────────┘ │ | ||
50 | │ │ | ||
51 | └─────────────────────────────────────┘ | ||
52 | |||
53 | Some pages ("foo" and "bar") share the same content structure - | ||
54 | two vertically stacked boxes: | ||
55 | |||
56 | .. code-block:: text | ||
57 | |||
58 | ┌─── page layout ─────────────────────┐ | ||
59 | │ │ | ||
60 | │ ┌── block "content" ──┐ │ | ||
61 | │ │ ┌─ block "top" ───┐ │ │ | ||
62 | │ │ │ │ │ │ | ||
63 | │ │ └─────────────────┘ │ │ | ||
64 | │ │ ┌─ block "bottom" ┐ │ │ | ||
65 | │ │ │ │ │ │ | ||
66 | │ │ └─────────────────┘ │ │ | ||
67 | │ └─────────────────────┘ │ | ||
68 | │ │ | ||
69 | └─────────────────────────────────────┘ | ||
70 | |||
71 | While other pages ("boom" and "baz") share a different content structure - | ||
72 | two boxes side by side: | ||
73 | |||
74 | .. code-block:: text | ||
75 | |||
76 | ┌─── page layout ─────────────────────┐ | ||
77 | │ │ | ||
78 | │ ┌── block "content" ──┐ │ | ||
79 | │ │ │ │ | ||
80 | │ │ ┌ block ┐ ┌ block ┐ │ │ | ||
81 | │ │ │"left" │ │"right"│ │ │ | ||
82 | │ │ │ │ │ │ │ │ | ||
83 | │ │ │ │ │ │ │ │ | ||
84 | │ │ └───────┘ └───────┘ │ │ | ||
85 | │ └─────────────────────┘ │ | ||
86 | │ │ | ||
87 | └─────────────────────────────────────┘ | ||
88 | |||
89 | Without the ``embed`` tag, you have two ways to design your templates: | ||
90 | |||
91 | * Create two "intermediate" base templates that extend the master layout | ||
92 | template: one with vertically stacked boxes to be used by the "foo" and | ||
93 | "bar" pages and another one with side-by-side boxes for the "boom" and | ||
94 | "baz" pages. | ||
95 | |||
96 | * Embed the markup for the top/bottom and left/right boxes into each page | ||
97 | template directly. | ||
98 | |||
99 | These two solutions do not scale well because they each have a major drawback: | ||
100 | |||
101 | * The first solution may indeed work for this simplified example. But imagine | ||
102 | we add a sidebar, which may again contain different, recurring structures | ||
103 | of content. Now we would need to create intermediate base templates for | ||
104 | all occurring combinations of content structure and sidebar structure... | ||
105 | and so on. | ||
106 | |||
107 | * The second solution involves duplication of common code with all its negative | ||
108 | consequences: any change involves finding and editing all affected copies | ||
109 | of the structure, correctness has to be verified for each copy, copies may | ||
110 | go out of sync by careless modifications etc. | ||
111 | |||
112 | In such a situation, the ``embed`` tag comes in handy. The common layout | ||
113 | code can live in a single base template, and the two different content structures, | ||
114 | let's call them "micro layouts" go into separate templates which are embedded | ||
115 | as necessary: | ||
116 | |||
117 | Page template ``foo.twig``: | ||
118 | |||
119 | .. code-block:: jinja | ||
120 | |||
121 | {% extends "layout_skeleton.twig" %} | ||
122 | |||
123 | {% block content %} | ||
124 | {% embed "vertical_boxes_skeleton.twig" %} | ||
125 | {% block top %} | ||
126 | Some content for the top box | ||
127 | {% endblock %} | ||
128 | |||
129 | {% block bottom %} | ||
130 | Some content for the bottom box | ||
131 | {% endblock %} | ||
132 | {% endembed %} | ||
133 | {% endblock %} | ||
134 | |||
135 | And here is the code for ``vertical_boxes_skeleton.twig``: | ||
136 | |||
137 | .. code-block:: html+jinja | ||
138 | |||
139 | <div class="top_box"> | ||
140 | {% block top %} | ||
141 | Top box default content | ||
142 | {% endblock %} | ||
143 | </div> | ||
144 | |||
145 | <div class="bottom_box"> | ||
146 | {% block bottom %} | ||
147 | Bottom box default content | ||
148 | {% endblock %} | ||
149 | </div> | ||
150 | |||
151 | The goal of the ``vertical_boxes_skeleton.twig`` template being to factor | ||
152 | out the HTML markup for the boxes. | ||
153 | |||
154 | The ``embed`` tag takes the exact same arguments as the ``include`` tag: | ||
155 | |||
156 | .. code-block:: jinja | ||
157 | |||
158 | {% embed "base" with {'foo': 'bar'} %} | ||
159 | ... | ||
160 | {% endembed %} | ||
161 | |||
162 | {% embed "base" with {'foo': 'bar'} only %} | ||
163 | ... | ||
164 | {% endembed %} | ||
165 | |||
166 | {% embed "base" ignore missing %} | ||
167 | ... | ||
168 | {% endembed %} | ||
169 | |||
170 | .. warning:: | ||
171 | |||
172 | As embedded templates do not have "names", auto-escaping strategies based | ||
173 | on the template "filename" won't work as expected if you change the | ||
174 | context (for instance, if you embed a CSS/JavaScript template into an HTML | ||
175 | one). In that case, explicitly set the default auto-escaping strategy with | ||
176 | the ``autoescape`` tag. | ||
177 | |||
178 | .. seealso:: :doc:`include<../tags/include>` | ||