Arbeiten mit Twig-Templates

Drupal ermöglicht es Ihnen, alle Templates zu überschreiben, die für die Erstellung des HTML-Markups verwendet werden, sodass Sie die vollständige Kontrolle über das Markup haben, das in Ihrem benutzerdefinierten Theme ausgegeben wird. Es gibt Templates für jedes Seitenelement, von hochrangigem HTML bis zu kleinen Feldern.

Templates überschreiben

Sie können die Haupttemplates von Drupal überschreiben, indem Sie Templates in den Theme-Ordner hinzufügen, die einer bestimmten Namenskonvention entsprechen.

Um Templates zu überschreiben, müssen Sie:

1. Das Template finden, das Sie überschreiben möchten.
2. Die Template-Datei aus ihrem Basisverzeichnis in den Ordner Ihres Themes kopieren.
3. (optional) Das Template gemäß den Namenskonventionen umbenennen, um gezielt eine spezifischere Untermenge der Bereiche anzusprechen, in denen das Template verwendet wird.
4. Das Template nach Belieben anpassen.

Sobald Sie die Template-Datei in Ihr Theme kopiert und den Cache geleert haben, verwendet Drupal Ihre Template-Datei anstelle der Basisversion.

Sie können herausfinden, welche Templates für einen beliebigen Seitenbereich verwendet werden, indem Sie die Twig-Debugging-Tools verwenden.

Theme-Hook-Vorschläge

Manchmal möchten Sie Änderungen an einer Template-Datei nur für bestimmte Einsatzzwecke vornehmen. Ein typisches Beispiel ist die Änderung der Node-Template-Datei nur für Nodes eines bestimmten Typs. Das Theming-System von Drupal erlaubt es Ihnen, solche speziellen Einsatzzwecke mittels Namenskonventionen anzusprechen. Wenn beispielsweise ein Artikel-Node gerendert wird, sucht Drupal zuerst nach node--article.html.twig und verwendet diese Datei, falls vorhanden. Andernfalls wird das Standardtemplate node.html.twig verwendet. Der Prozess, mit dem Drupal ermittelt, welche möglichen Template-Namen verwendet werden können, heißt Theme-Hook-Vorschläge.

Theme-Hook-Vorschläge erlauben es Ihnen, gezielte Überschreibungen in Ihrem Theme für Template-Dateien mit bestimmten Namenskonventionen vorzunehmen.

Alle Ebenen aus Core, Modulen, Theme-Engines und Themes können Vorschläge liefern. Sie können Vorschläge hinzufügen oder verändern, indem Sie folgende Hooks verwenden:

• hook_theme_suggestions_HOOK(array $variables)
• hook_theme_suggestions_alter(array &$suggestions, array $variables, $hook)
• hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables)

Cache leeren

Beim Arbeiten mit Theme-Hook-Vorschlägen kann es passieren, dass Drupal seinen Cache verwendet und nicht die neuen Templates, wie vorgeschlagen. Leeren Sie den Cache, falls dieses Problem auftritt. Um den Cache zu leeren, nutzen Sie eine der Methoden aus dem Abschnitt Drupal Cache leeren.

Hintergrundinformationen

Sie können Vorschläge als Benennungshinweise betrachten, die das System anweisen, je nach Situation eine Auswahl zu treffen.

Template-Vorschläge werden über Theme-Hooks gesetzt und können verändert werden. Diese Hooks erlauben es jedem Modul oder Theme, alternative Theme-Funktionen oder Template-Namensvorschläge bereitzustellen und die von hook_theme_suggestions_HOOK() oder früheren Hook-Aufrufen gelieferten Vorschläge zu verändern oder zu entfernen.

Wie Drupal Theme-Hook-Vorschläge für Seiten basierend auf dem Pfad ermittelt

Hier eine weitere Erklärung basierend auf der Funktion theme_get_suggestions():

Drupal erzeugt die Liste möglicher Templates für eine Seite mittels der Funktion theme_get_suggestions(), die von system_theme_suggestions_page() aufgerufen wird.

Der Pfad der Seite in Drupal wird zunächst in seine Komponenten zerlegt. Wie oben erwähnt, ist der Drupal-Pfad niemals einer seiner Aliase: Es gibt für eine Seite genau einen Drupal-Pfad. Für die Beispiele "http://www.example.com/node/1/edit" und "http://www.example.com/mysitename?q=node/1/edit" ist der Drupal-Pfad node/1/edit, dessen Komponenten „node“, 1 und „edit“ sind.

Dann wird das Präfix „page“ gesetzt. Für jede Komponente gilt folgende Logik:

1. Wenn die Komponente eine Zahl ist, wird das Präfix plus „__%“ zur Vorschlagsliste hinzugefügt.
2. Unabhängig davon, ob die Komponente eine Zahl ist oder nicht, wird das Präfix plus „__“ plus Komponente zur Vorschlagsliste hinzugefügt.
3. Ist die Komponente keine Zahl, wird „__“ plus Komponente zum Präfix hinzugefügt.

Nachdem alle Komponenten durchlaufen sind, wird, falls die Seite die Startseite ist (wie unter "Administration > Konfiguration > System > Website-Informationen" definiert), „page__front“ zur Vorschlagsliste hinzugefügt.

Beachten Sie, dass zum Erzeugen des tatsächlichen Dateinamens aus dem Vorschlag „__“ in „--“ umgewandelt wird und „.html.twig“ angehängt wird. Für node/1/edit ergibt sich folgende Vorschlagsliste:

1. page.html.twig (immer Vorschlag)
2. page--node.html.twig (Präfix ist page__node)
3. page--node--%.html.twig
4. page--node--1.html.twig (Präfix bleibt, da Komponente Zahl ist)
5. page--node--edit.html.twig (Präfix ist page__node__edit)
6. page--front.html.twig (nur wenn node/1/edit Startseite ist)

Beim Rendern der Seite wird geprüft, ob das letzte Template existiert. Falls ja, wird es verwendet. Wenn nicht, wird das nächstfolgende geprüft usw. Wenn keine Vorschläge gefunden werden, wird page.html.twig verwendet. Das erklärt auch, warum page--front.html.twig, wenn vorhanden, alle anderen Vorschläge für die Startseite überschreibt: Es ist immer das letzte Vorschlags-Template für die Startseite.

Unterschiede zu Drupal 7

Früher haben Sie die Template-Vorschläge durch Änderung von $variable['theme_hook_suggestion'] und $variable['theme_hook_suggestions'] in Preprocess-Funktionen hinzugefügt. In Drupal 8 definieren und verändern Module und Themes nun ihre Theme-Vorschläge in eigenen speziellen Hooks.

Weitere Informationen

Siehe Änderung Neue Hooks für Theme-Vorschläge