5 The ``embed`` tag was added in Twig 1.8.
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.
13 Think of an embedded template as a "micro layout skeleton".
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
23 {% block right_teaser %}
24 Some content for the right teaser box
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
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
40 ┌─── page layout ─────────────────────┐
42 │ ┌── block "content" ──┐ │
45 │ │ (child template to │ │
46 │ │ put content here) │ │
49 │ └─────────────────────┘ │
51 └─────────────────────────────────────┘
53 Some pages ("foo" and "bar") share the same content structure -
54 two vertically stacked boxes:
58 ┌─── page layout ─────────────────────┐
60 │ ┌── block "content" ──┐ │
61 │ │ ┌─ block "top" ───┐ │ │
63 │ │ └─────────────────┘ │ │
64 │ │ ┌─ block "bottom" ┐ │ │
66 │ │ └─────────────────┘ │ │
67 │ └─────────────────────┘ │
69 └─────────────────────────────────────┘
71 While other pages ("boom" and "baz") share a different content structure -
72 two boxes side by side:
76 ┌─── page layout ─────────────────────┐
78 │ ┌── block "content" ──┐ │
80 │ │ ┌ block ┐ ┌ block ┐ │ │
81 │ │ │"left" │ │"right"│ │ │
84 │ │ └───────┘ └───────┘ │ │
85 │ └─────────────────────┘ │
87 └─────────────────────────────────────┘
89 Without the ``embed`` tag, you have two ways to design your templates:
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
96 * Embed the markup for the top/bottom and left/right boxes into each page
99 These two solutions do not scale well because they each have a major drawback:
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...
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.
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
117 Page template ``foo.twig``:
119 .. code-block:: jinja
121 {% extends "layout_skeleton.twig" %}
124 {% embed "vertical_boxes_skeleton.twig" %}
126 Some content for the top box
130 Some content for the bottom box
135 And here is the code for ``vertical_boxes_skeleton.twig``:
137 .. code-block:: html+jinja
139 <div class="top_box">
141 Top box default content
145 <div class="bottom_box">
147 Bottom box default content
151 The goal of the ``vertical_boxes_skeleton.twig`` template being to factor
152 out the HTML markup for the boxes.
154 The ``embed`` tag takes the exact same arguments as the ``include`` tag:
156 .. code-block:: jinja
158 {% embed "base" with {'foo': 'bar'} %}
162 {% embed "base" with {'foo': 'bar'} only %}
166 {% embed "base" ignore missing %}
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
178 .. seealso:: :doc:`include<../tags/include>`