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 или 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 %}