embed · Twig · 看云

# `embed` New in version 1.8: The `embed` tag was added in Twig 1.8. The `embed` tag combines the behaviour of [*include*](#) and[*extends*](#).It allows you to include another template's contents, just like `include`does. But it also allows you to override any block defined inside theincluded template, like when extending a template. Think of an embedded template as a "micro layout skeleton". <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1 2 3 4 5 6 7 8 9 10</pre></div></td><td class="code"><div class="highlight"><pre>{% embed "teasers_skeleton.twig" %} {# These blocks are defined in "teasers_skeleton.twig" #} {# and we override them right here: #} {% block left_teaser %} Some content for the left teaser box {% endblock %} {% block right_teaser %} Some content for the right teaser box {% endblock %} {% endembed %} </pre></div></td></tr></table> The `embed` tag takes the idea of template inheritance to the level ofcontent fragments. While template inheritance allows for "document skeletons",which are filled with life by child templates, the `embed` tag allows you tocreate "skeletons" for smaller units of content and re-use and fill themanywhere you like. Since the use case may not be obvious, let's look at a simplified example.Imagine a base template shared by multiple HTML pages, defining a single blocknamed "content": <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1 2 3 4 5 6 7 8 9 10 11 12</pre></div></td><td class="code"><div class="highlight"><pre>┌─── page layout ─────────────────────┐ │ │ │ ┌── block "content" ──┐ │ │ │ │ │ │ │ │ │ │ │ (child template to │ │ │ │ put content here) │ │ │ │ │ │ │ │ │ │ │ └─────────────────────┘ │ │ │ └─────────────────────────────────────┘ </pre></div></td></tr></table> Some pages ("foo" and "bar") share the same content structure -two vertically stacked boxes: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1 2 3 4 5 6 7 8 9 10 11 12</pre></div></td><td class="code"><div class="highlight"><pre>┌─── page layout ─────────────────────┐ │ │ │ ┌── block "content" ──┐ │ │ │ ┌─ block "top" ───┐ │ │ │ │ │ │ │ │ │ │ └─────────────────┘ │ │ │ │ ┌─ block "bottom" ┐ │ │ │ │ │ │ │ │ │ │ └─────────────────┘ │ │ │ └─────────────────────┘ │ │ │ └─────────────────────────────────────┘ </pre></div></td></tr></table> While other pages ("boom" and "baz") share a different content structure -two boxes side by side: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1 2 3 4 5 6 7 8 9 10 11 12</pre></div></td><td class="code"><div class="highlight"><pre>┌─── page layout ─────────────────────┐ │ │ │ ┌── block "content" ──┐ │ │ │ │ │ │ │ ┌ block ┐ ┌ block ┐ │ │ │ │ │"left" │ │"right"│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └───────┘ └───────┘ │ │ │ └─────────────────────┘ │ │ │ └─────────────────────────────────────┘ </pre></div></td></tr></table> Without the `embed` tag, you have two ways to design your templates: > > - Create two "intermediate" base templates that extend the master layouttemplate: one with vertically stacked boxes to be used by the "foo" and"bar" pages and another one with side-by-side boxes for the "boom" and"baz" pages. > - Embed the markup for the top/bottom and left/right boxes into each pagetemplate directly. These two solutions do not scale well because they each have a major drawback: > > - The first solution may indeed work for this simplified example. But imaginewe add a sidebar, which may again contain different, recurring structuresof content. Now we would need to create intermediate base templates forall occurring combinations of content structure and sidebar structure...and so on. > - The second solution involves duplication of common code with all its negativeconsequences: any change involves finding and editing all affected copiesof the structure, correctness has to be verified for each copy, copies maygo out of sync by careless modifications etc. In such a situation, the `embed` tag comes in handy. The common layoutcode can live in a single base template, and the two different content structures,let's call them "micro layouts" go into separate templates which are embeddedas necessary: Page template `foo.twig`: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1 2 3 4 5 6 7 8 9 10 11 12 13</pre></div></td><td class="code"><div class="highlight"><pre>{% extends "layout_skeleton.twig" %} {% block content %} {% embed "vertical_boxes_skeleton.twig" %} {% block top %} Some content for the top box {% endblock %} {% block bottom %} Some content for the bottom box {% endblock %} {% endembed %} {% endblock %} </pre></div></td></tr></table> And here is the code for `vertical_boxes_skeleton.twig`: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1 2 3 4 5 6 7 8 9 10 11</pre></div></td><td class="code"><div class="highlight"><pre><div class="top_box"> {% block top %} Top box default content {% endblock %} </div> <div class="bottom_box"> {% block bottom %} Bottom box default content {% endblock %} </div> </pre></div></td></tr></table> The goal of the `vertical_boxes_skeleton.twig` template being to factorout the HTML markup for the boxes. The `embed` tag takes the exact same arguments as the `include` tag: <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1 2 3 4 5 6 7 8 9 10 11</pre></div></td><td class="code"><div class="highlight"><pre>{% embed "base" with {'foo': 'bar'} %} ... {% endembed %} {% embed "base" with {'foo': 'bar'} only %} ... {% endembed %} {% embed "base" ignore missing %} ... {% endembed %} </pre></div></td></tr></table> Warning As embedded templates do not have "names", auto-escaping strategies basedon the template "filename" won't work as expected if you change thecontext (for instance, if you embed a CSS/JavaScript template into an HTMLone). In that case, explicitly set the default auto-escaping strategy withthe `autoescape` tag. See also [*include*](#)