Макросы в шаблонах Twig

Dalla documentazione ufficiale di Twig: «I macro sono paragonabili alle funzioni nei linguaggi di programmazione tradizionali. Sono utili per inserire idiomi HTML usati di frequente in elementi riutilizzabili, in modo da non doversi ripetere».

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

I macro si differenziano dalle funzioni native PHP in diversi modi:

• I valori predefiniti degli argomenti vengono definiti usando il filtro default nel corpo del macro;
• Gli argomenti dei macro sono sempre opzionali.
• Se vengono passati argomenti posizionali aggiuntivi a un macro, essi vengono inseriti in una variabile speciale varargs come lista di valori.

Ma, come per le funzioni PHP, i macro non hanno accesso alle variabili correnti del template. Puoi passare l’intero contesto come argomento usando la variabile speciale _context.

Invocare un macro

Da _self

Un macro può essere inserito nello stesso file Twig da cui viene richiamato. In questo caso si usa il contesto _self ...

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

Da un file esterno

È comunque consigliato posizionare i macro in un file separato (ad esempio macros.twig), così da poterli usare in più template.

Ad esempio, in un tema personalizzato «mytheme» possiamo posizionare il file del macro qui ...

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

Nota: il file del macro può avere qualsiasi nome con estensione .twig, ma non può avere estensione .html (quindi macros.html.twig non funzionerà). Inoltre, il file deve essere inserito nella cartella «templates», indipendentemente da dove venga usato (per esempio, per i layout di Layout Builder che posizioni in .../mytheme/layouts, il macro deve esistere in ../mytheme/templates).

Nel template in cui vuoi usare il macro, aggiungi questa istruzione di import:

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

@mytheme individua automaticamente la cartella «templates» del tuo tema, ma devi specificare manualmente eventuali sottocartelle nella dichiarazione di import, ad esempio:

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

Nota: nelle versioni più vecchie di questa documentazione si affermava che non era necessario specificare la struttura delle sottocartelle, quindi il comportamento può variare. Se lo fai in un modulo personalizzato, usa la stessa tecnica ma specifica il nome del modulo invece del nome del tema (per esempio, @mycustommodule).

Quindi puoi usare il macro ...

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

Esempi

In Drupal 8 un macro viene utilizzato, ad esempio, per costruire la navigazione principale (vedi il file menu.html.twig).