embed ¶

The embed tag combines the behavior 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 the included template, like when extending a template.

Think of an embedded template as a "micro layout skeleton".

1
2
3
4
5
6
7
8
9
10

{% 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 %}

The embed tag takes the idea of template inheritance to the level of content fragments. While template inheritance allows for "document skeletons", which are filled with life by child templates, the embed tag allows you to create "skeletons" for smaller units of content and re-use and fill them anywhere 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 block named "content":

1
2
3
4
5
6
7
8
9
10
11
12

┌─── page layout ─────────────────────┐
│                                     │
│           ┌── block "content" ──┐   │
│           │                     │   │
│           │                     │   │
│           │ (child template to  │   │
│           │  put content here)  │   │
│           │                     │   │
│           │                     │   │
│           └─────────────────────┘   │
│                                     │
└─────────────────────────────────────┘

Some pages ("foo" and "bar") share the same content structure - two vertically stacked boxes:

1
2
3
4
5
6
7
8
9
10
11
12

┌─── page layout ─────────────────────┐
│                                     │
│           ┌── block "content" ──┐   │
│           │ ┌─ block "top" ───┐ │   │
│           │ │                 │ │   │
│           │ └─────────────────┘ │   │
│           │ ┌─ block "bottom" ┐ │   │
│           │ │                 │ │   │
│           │ └─────────────────┘ │   │
│           └─────────────────────┘   │
│                                     │
└─────────────────────────────────────┘

While other pages ("boom" and "baz") share a different content structure - two boxes side by side:

1
2
3
4
5
6
7
8
9
10
11
12

┌─── page layout ─────────────────────┐
│                                     │
│           ┌── block "content" ──┐   │
│           │                     │   │    
│           │ ┌ block ┐ ┌ block ┐ │   │
│           │ │"left" │ │"right"│ │   │
│           │ │       │ │       │ │   │
│           │ │       │ │       │ │   │
│           │ └───────┘ └───────┘ │   │
│           └─────────────────────┘   │
│                                     │
└─────────────────────────────────────┘

Without the embed tag, you have two ways to design your templates:

• Create two "intermediate" base templates that extend the master layout template: 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.
  マスター レイアウト テンプレートを拡張する 2 つの「中間」ベース テンプレートを作成します。ページ。
• Embed the markup for the top/bottom and left/right boxes into each page template 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 imagine we add a sidebar, which may again contain different, recurring structures of content. Now we would need to create intermediate base templates for all occurring combinations of content structure and sidebar structure... and so on.
  最初の解決策は、この単純化された例では実際に機能する可能性があります。しかし、サイドバーを追加すると想像してみてください。サイドバーには、コンテンツのさまざまな繰り返し構造が含まれている可能性があります。ここで、コンテンツ構造とサイドバー構造のすべての組み合わせの中間ベース テンプレートを作成する必要があります。
• The second solution involves duplication of common code with all its negative consequences: any change involves finding and editing all affected copies of the structure, correctness has to be verified for each copy, copies may go out of sync by careless modifications etc.
  2 番目の解決策は、すべてのマイナスの結果を伴う共通コードの複製を伴います。変更には、構造の影響を受けるすべてのコピーの検索と編集が含まれ、コピーごとに正確性を検証する必要があり、不注意な変更によってコピーが同期しなくなる可能性があります。

In such a situation, the embed tag comes in handy. The common layout code 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 embedded as necessary:

Page template foo.twig:

1
2
3
4
5
6
7
8
9
10
11
12
13

{% 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 %}

And here is the code for vertical_boxes_skeleton.twig:

1
2
3
4
5
6
7
8
9
10
11

<div class="top_box">
    {% block top %}
        Top box default content
    {% endblock %}
</div>

<div class="bottom_box">
    {% block bottom %}
        Bottom box default content
    {% endblock %}
</div>

The goal of the vertical_boxes_skeleton.twig template being to factor out the HTML markup for the boxes.

The embed tag takes the exact same arguments as the include tag:

1
2
3
4
5
6
7
8
9
10
11

{% embed "base" with {'foo': 'bar'} %}
    ...
{% endembed %}

{% embed "base" with {'foo': 'bar'} only %}
    ...
{% endembed %}

{% embed "base" ignore missing %}
    ...
{% endembed %}