Makros in Twig-Templates

Aus der offiziellen Twig-Dokumentation: „Makros sind vergleichbar mit Funktionen in gewöhnlichen Programmiersprachen. Sie sind nützlich, um häufig verwendete HTML-Idiome in wiederverwendbaren Elementen unterzubringen, damit man sich nicht wiederholt.“

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

Makros unterscheiden sich in mehreren Punkten von nativen PHP-Funktionen:

• Standardwerte für Argumente werden im Makro-Körper mit dem Filter default definiert;
• Makro-Argumente sind immer optional.
• Wenn zusätzliche positionsabhängige Argumente an ein Makro übergeben werden, landen diese in einer speziellen Variablen varargs als Liste von Werten.

Wie bei PHP-Funktionen haben Makros jedoch keinen Zugriff auf die aktuellen Template-Variablen. Sie können den gesamten Kontext als Argument übergeben, indem Sie die spezielle Variable _context verwenden.

Aufruf von Makros

From _self

Ein Makro kann in dasselbe Twig-Template eingefügt werden, aus dem Sie es aufrufen. In diesem Fall wird der Kontext _self verwendet ...

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

Aus einer externen Datei

Es wird jedoch empfohlen, Makros in einer separaten Datei (z. B. macros.twig) zu platzieren, damit sie in mehreren Templates verwendet werden können.

Zum Beispiel platzieren wir in unserem benutzerdefinierten Theme „mytheme“ die Makro-Datei hier ...

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

Hinweis: Die Makro-Datei kann beliebig.twig heißen, darf jedoch nicht die Erweiterung html tragen (also funktioniert macros.html.twig nicht). Die Datei muss außerdem im „templates“-Verzeichnis liegen, unabhängig davon, wo sie verwendet wird (d. h. für Layout-Builder-Layouts, die Sie in ... /mytheme/layouts abgelegt haben, muss das Makro im ../mytheme/templates-Verzeichnis existieren).

Fügen Sie im Template, in dem Sie das Makro verwenden möchten, folgende Import-Anweisung hinzu:

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

@mytheme findet dabei auf magische Weise das „templates“-Verzeichnis Ihres Themes, aber Sie müssen eine eventuell vorhandene weitere Verzeichnisstruktur im Import-Pfad angeben, z. B.:

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

Beachten Sie, dass in älteren Versionen dieser Dokumentation angegeben war, dass die Angabe verschachtelter Verzeichnisse nicht nötig sei, daher kann es unterschiedlich sein. Wenn Sie das in einem benutzerdefinierten Modul machen, verwenden Sie dieselbe Technik, nur mit dem Modulnamen statt des Theme-Namens (z. B. @mycustommodule).

Dann verwenden Sie das Makro so ...

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

Beispiele

In Drupal 8 wird ein Makro z. B. verwendet, um die Hauptnavigation zu erzeugen (siehe Datei menu.html.twig).