embed

Тег embed объединяет поведение тегов include и extends. Он позволяет включать содержимое другого шаблона, как и тег include. Но он также позволяет переопределять любые блоки, определённые внутри включённого шаблона, подобно расширению шаблона.

Представьте вложенный шаблон как «микро-скелет макета».

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

Тег embed поднимает идею наследования шаблонов на уровень фрагментов содержимого. В то время как наследование шаблонов позволяет создавать «скелеты документов», которые наполняются содержимым дочерними шаблонами, тег embed позволяет создавать «скелеты» для более мелких единиц содержимого и повторно использовать/заполнять их где угодно.

Поскольку использование может быть не очевидным, давайте рассмотрим упрощённый пример. Представьте базовый шаблон, используемый несколькими страницами HTML, определяющий единственный блок с именем «content»:

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

Некоторые страницы («foo» и «bar») используют одинаковую структуру содержимого — две вертикально расположенные области:

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

В то время как другие страницы («boom» и «baz») используют другую структуру содержимого — две расположенные бок о бок области:

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

Без тега embed, у вас есть два способа разработки шаблонов:

• Создать два «промежуточных» базовых шаблона, которые расширяют основной макет: один с вертикально расположенными областями для страниц «foo» и «bar» и другой с расположенными бок о бок областями для страниц «boom» и «baz».
• Встроить разметку для верхних/нижних и левых/правых областей напрямую в каждый шаблон страницы.

Эти два решения не масштабируются, так как у каждого из них есть существенный недостаток:

• Первое решение, возможно, сработает для этого упрощённого примера. Но представьте, что мы добавим боковую панель, которая может снова содержать различные повторяющиеся структуры содержимого. Теперь нам нужно будет создавать промежуточные базовые шаблоны для всех возникающих комбинаций структуры содержимого и структуры боковой панели… и так далее.
• Второе решение предполагает дублирование общего кода со всеми его негативными последствиями: любое изменение требует поиска и редактирования всех затронутых копий структуры, корректность должна быть проверена для каждой копии, копии могут разойтись из-за неосторожных изменений и т. д.

В такой ситуации тег embed оказывается полезным. Общий код макета может храниться в одном базовом шаблоне, а две разные структуры содержимого, назовём их «микро-макеты», хранятся в отдельных шаблонах, которые подключаются по мере необходимости:

Шаблон страницы foo.twig:

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

И вот код для vertical_boxes_skeleton.twig:

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

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

Цель шаблона vertical_boxes_skeleton.twig — вынести разметку HTML для областей.

Тег embed принимает точно такие же аргументы, как и тег include:

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

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

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