macro

Las macros son comparables con funciones en lenguajes de programación regulares. Son útiles para poner modismos HTML utilizados frecuentemente en elementos reutilizables para no repetirlos.

He aquí un pequeño ejemplo de una macro que reproduce un elemento de formulario:

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

Las macros se diferencian de las funciones PHP nativas en varias formas:

• Los valores predeterminados de los argumentos se definen usando el filtro default en el cuerpo de la macro;
• Los argumentos de una macro siempre son opcionales.

Pero como las funciones de PHP, las macros no tienen acceso a las variables de la plantilla actual.

Truco

Puedes pasar todo el contexto como un argumento usando la variable especial _context.

Las macros se pueden definir en cualquier plantilla, y es necesario «importarlas», antes de utilizarlas (consulta la etiqueta import para más información):

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

La anterior llamada a import importa el archivo «formularios.html» (el cual puede contener macros solamente, o una plantilla y algunas macros), e importa las funciones como elementos de la variable forms.

Entonces puedes llamar a la macro a voluntad:

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

Si hay macros definidas y se usan en la misma plantilla, puedes utilizar la variable especial _self para importarlas:

{% import _self as forms %}

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

Advertencia

Cuándo defines una macro en la plantilla donde la vas a utilizar, podría ser tentador llamar a la macro directamente vía _self.entrada() en vez de importarla; incluso si parece trabajar, este es justo un efecto colateral de la implementación actual y no trabajará más en Twig 2.x.

Cuándo quieras utilizar una macro en otra macro del mismo archivo, necesitas importarla localmente:

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

Ver también

from, import