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-страниц, определяющий единственный блок с именем «содержимое»:

┌─── 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 %}