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