1``embed``
2=========
3
4.. versionadded:: 1.8
5    The ``embed`` tag was added in Twig 1.8.
6
7The ``embed`` tag combines the behaviour of :doc:`include<include>` and
8:doc:`extends<extends>`.
9It allows you to include another template's contents, just like ``include``
10does. But it also allows you to override any block defined inside the
11included template, like when extending a template.
12
13Think 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
28The ``embed`` tag takes the idea of template inheritance to the level of
29content fragments. While template inheritance allows for "document skeletons",
30which are filled with life by child templates, the ``embed`` tag allows you to
31create "skeletons" for smaller units of content and re-use and fill them
32anywhere you like.
33
34Since the use case may not be obvious, let's look at a simplified example.
35Imagine a base template shared by multiple HTML pages, defining a single block
36named "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
53Some pages ("foo" and "bar") share the same content structure -
54two 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
71While other pages ("boom" and "baz") share a different content structure -
72two 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
89Without 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
99These 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
112In such a situation, the ``embed`` tag comes in handy. The common layout
113code can live in a single base template, and the two different content structures,
114let's call them "micro layouts" go into separate templates which are embedded
115as necessary:
116
117Page 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
135And 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
151The goal of the ``vertical_boxes_skeleton.twig`` template being to factor
152out the HTML markup for the boxes.
153
154The ``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 name won't work as expected if you change the context (for
174    instance, if you embed a CSS/JavaScript template into an HTML one). In that
175    case, explicitly set the default auto-escaping strategy with the
176    ``autoescape`` tag.
177
178.. seealso:: :doc:`include<../tags/include>`
179