Macros en plantillas Twig

Desde la documentación oficial de Twig: «Los macros son comparables a las funciones en los lenguajes de programación tradicionales. Son útiles para colocar idioms HTML usados frecuentemente en elementos reutilizables, para evitar la repetición».

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

Los macros se diferencian de las funciones nativas de PHP en varios aspectos:

• Los valores predeterminados de los argumentos se definen mediante el filtro default dentro del cuerpo del macro;
• Los argumentos de un macro siempre son opcionales.
• Si se pasan argumentos posicionales adicionales al macro, estos se almacenan en una variable especial varargs como una lista de valores.

Pero, al igual que en las funciones PHP, los macros no tienen acceso a las variables actuales del template. Puedes pasar todo el contexto como argumento usando la variable especial _context.

Llamando al macro

Desde _self

El macro puede estar ubicado en el mismo Twig desde donde se llama. En ese caso, se usa el contexto _self ...

{{ _self.input(name, value, type, size) }}

Desde un archivo externo

Sin embargo, se recomienda colocar los macros en un archivo separado (por ejemplo, macros.twig), para que los macros puedan usarse en múltiples plantillas.

Por ejemplo, en el tema personalizado «mytheme» colocamos aquí el archivo de macros ...

[site_root]/themes/custom/mytheme/templates/macros.twig

Nota: el archivo de macros puede llamarse any.twig, pero no puede tener extensión html (es decir, macros.html.twig no funcionará). Además, el archivo debe ubicarse en el directorio «templates» sin importar dónde se use (es decir, para diseños de Layout Builder que coloques en ... /mytheme/layouts, el macro debe existir en ../mytheme/templates).

En la plantilla donde quieres usar el macro, añade esta declaración de importación.

{% import '@mytheme/macros.twig' as myMacros %}

@mytheme localiza mágicamente el directorio «templates» de tu tema, pero debes especificar cualquier estructura adicional de carpetas en la declaración de importación, por ejemplo:

{% import '@mytheme/foo/bar/macros.twig' as myMacros %}

Ten en cuenta que en versiones anteriores de esta documentación se decía que no era necesario definir estructuras de carpetas anidadas, así que tu experiencia puede variar. Si haces esto en un módulo personalizado, usa la misma técnica pero con el nombre del módulo en lugar del nombre del tema (por ejemplo, @mycustommodule).

Luego usa el macro ...

{{ myMacros.input(name, value, type, size) }}

Ejemplos

En Drupal 8, un macro se usa para crear, por ejemplo, la navegación principal (ver el archivo menu.html.twig).