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

Uit de officiële Twig-documentatie: «Macro’s zijn vergelijkbaar met functies in gewone programmeertalen. Ze zijn nuttig om vaak gebruikte HTML-idioom in herbruikbare elementen te plaatsen, zodat je jezelf niet hoeft te herhalen».

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

Macro’s verschillen van native PHP-functies op enkele manieren:

• Standaardwaarden voor argumenten worden gedefinieerd met de default-filter in de body van de macro;
• Macro-argumenten zijn altijd optioneel.
• Als extra positionele argumenten aan de macro worden doorgegeven, worden ze opgeslagen in de speciale variabele varargs als een lijst met waarden.

Maar, net als bij PHP-functies, hebben macro’s geen toegang tot de huidige variabelen in het sjabloon. Je kunt echter de volledige context als argument doorgeven met behulp van de speciale variabele _context.

Een macro aanroepen

Vanuit _self

Een macro kan in hetzelfde Twig-bestand staan waarin je hem aanroept. In dit geval gebruik je de context _self ...

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

Uit een extern bestand

Het is echter aanbevolen om macro’s in een apart bestand te plaatsen (bijvoorbeeld macros.twig), zodat ze in meerdere sjablonen kunnen worden hergebruikt.

Bijvoorbeeld: in het custom thema «mytheme» plaatsen we het macro-bestand hier ...

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

Opmerking: het macro-bestand kan elke naam hebben met de extensie .twig, maar mag geen .html-extensie hebben (dus macros.html.twig zal niet werken). Het bestand moet ook altijd in de map «templates» staan, ongeacht waar het wordt gebruikt (bijvoorbeeld voor Layout Builder layouts die je in .../mytheme/layouts plaatst, moet de macro in ../mytheme/templates bestaan).

In het sjabloon waar je de macro wilt gebruiken, voeg je deze import-instructie toe:

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

@mytheme verwijst automatisch naar de map «templates» van je thema, maar je moet zelf de extra submapstructuur opgeven in de import, bijvoorbeeld:

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

Let op: in oudere versies van de documentatie werd vermeld dat het definiëren van de nested mapstructuur niet nodig was, dus dat kan verschillen. Als je dit in een custom module doet, gebruik je dezelfde techniek, maar dan met de modulenaam in plaats van de themanaam (bijvoorbeeld @mycustommodule).

Daarna gebruik je de macro zo ...

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

Voorbeelden

In Drupal 8 wordt een macro bijvoorbeeld gebruikt om de hoofd­navigatie op te bouwen (zie het bestand menu.html.twig).