macro

Макросы сопоставимы с функциями в обычных языках программирования. Они полезны для повторного использования фрагментов шаблонов, чтобы не повторяться.

Макросы определяются в обычных шаблонах.

Представьте, что у вас есть универсальный вспомогательный шаблон, который определяет, как отображать HTML-формы с помощью макросов (называемые forms.html):

{% macro input(name, value, type = "text", size = 20) %}
    <input type="{{ type }}" name="{{ name }}" value="{{ value|e }}" size="{{ size }}"/>
{% endmacro %}

{% macro textarea(name, value, rows = 10, cols = 40) %}
    <textarea name="{{ name }}" rows="{{ rows }}" cols="{{ cols }}">{{ value|e }}</textarea>
{% endmacro %}

Каждый аргумент макроса может иметь значение по умолчанию (здесь text — значение по умолчанию для type если оно не указано при вызове).

Макросы отличаются от встроенных функций PHP несколькими способами:

• Аргументы макроса всегда необязательны.
• Если макросу передаются дополнительные позиционные аргументы, они попадают в специальную переменную varargs в виде списка значений.

Но как и в случае с функциями PHP, макросы не имеют доступа к текущим переменным шаблона.

Импорт макросов

Существует два способа импорта макросов. Вы можете импортировать весь шаблон, содержащий макросы, в локальную переменную (через тег import) или только импортировать определенные макросы из шаблона (через тег from).

Чтобы импортировать все макросы из шаблона в локальную переменную, используйте тег import:

{% import "forms.html" as forms %}

Вышеупомянутый import вызов импортирует файл forms.html (который может содержать только макросы или шаблон и некоторые макросы) и импортирует макросы как элементы локальной переменной forms.

Затем макросы можно вызывать по своему усмотрению в текущем шаблоне:

<p>{{ forms.input('username') }}</p>
<p>{{ forms.input('password', null, 'password') }}</p>

В качестве альтернативы вы можете импортировать имена из шаблона в текущее пространство имен с помощью тега from:

{% from 'forms.html' import input as input_field, textarea %}

<p>{{ input_field('password', '', 'password') }}</p>
<p>{{ textarea('comment') }}</p>

<p>{{ _self.input('password', '', 'password') }}</p>

{% macro input(name, value, type = "text", size = 20) %}
    <input type="{{ type }}" name="{{ name }}" value="{{ value|e }}" size="{{ size }}"/>
{% endmacro %}

{% import _self as forms %}

<p>{{ forms.input('username') }}</p>

{% macro input(name, value, type, size) %}
    <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}"/>
{% endmacro %}

{% macro wrapped_input(name, value, type, size) %}
    {% import _self as forms %}

    <div class="field">
        {{ forms.input(name, value, type, size) }}
    </div>
{% endmacro %}

Ограничение области действия макросов

Правила области действия одинаковы независимо от того, импортировали ли вы макросы через import или from.

Импортированные макросы всегда локальные для текущего шаблона. Это означает, что макросы доступны во всех блоках и других макросах, определенных в текущем шаблоне, но они недоступны во включённых шаблонах или дочерних шаблонах; вам нужно явно повторно импортировать макросы в каждом шаблоне.

Импортированные макросы недоступны в теле тегов embed , необходимо явно повторно импортировать макросы внутри тега.

При вызове import или from из тега block, импортированные макросы определены только в текущем блоке и переопределяют макросы, определенные на уровне шаблона, с теми же именами.

При вызове import или from из тега macro, импортированные макросы определены только в текущем макросе и переопределяют макросы, определенные на уровне шаблона, с теми же именами.

Проверка определения макроса

Вы можете проверить, определен ли макрос, с помощью проверки defined:

{% import "macros.twig" as macros %}

{% from "macros.twig" import hello %}

{% if macros.hello is defined -%}
    OK
{% endif %}

{% if hello is defined -%}
    OK
{% endif %}

Именованные теги завершения макросов

Twig позволяет вам указать имя макроса после тега завершения для лучшей читаемости (имя после слова endmacro должно совпадать с именем макроса):

{% macro input() %}
    ...
{% endmacro input %}