Templates wiederverwenden

Contao setzt mit Twig konsequent auf das Wiederverwenden von Teilen eines Templates. Twig unterstützt viele Möglichkeiten Teile eines Templates wiederzuverwenden. Dazu gehören u. a.:

• Erweitern
• Horizontale Wiederverwendung

Für komplexere Anpassungen stehen noch viele weitere Möglichkeiten zur Verfügung. Die Beschreibung findest du in der Entwicklerdokumentation:

• Einfügen
• Einbetten
• Makros
• Komponenten
• Vorlagenfunktionen

Template-Hierarchie

Für die Wiederverwendung von Templates solltest du dich mit der Template-Hierarchie in Contao vertraut machen.

• Templates aus Core
• Templates aus einer Erweiterung
• Templates aus einer Applikation
• Globale Templates
• Globale Varianten-Templates

Templates aus dem Core können durch Erweiterung und Applikation verändert werden. Für deine globale Templates aus dem Ordner /templates sind es übergeordnete Templates, die du anpassen kannst.
Die übergeordneten Templates (Basis-Templates) des Cores, aus Erweiterungen oder Applikation können durch ein globales Template aus dem Ordner /templates einmal grundsätzlich für alle Elemente eines Typs angepasst werden oder es können globale Varianten-Templates zur Verfügung gestellt werden. Ein Varianten-Template kann dabei entweder direkt ein Template aus dem Core, aus Erweiterungen oder Anwendungen anpassen oder ein globales Template aus dem Ordner /templates.

Zusätzlich stehen noch themespezifische Templates zur Verfügung, die aber nicht zur Template-Hierarchie gehören, weil sie erst zur Laufzeit erzeugt werden.

Die Template-Hierarchie kann über die Kommandozeile mit dem debug:contao-twig Kommando dargestellt werden. Beachte bei der Verwendung des Kommandozeilenbefehls auch den entsprechenden Abschnitt im Handbuch.

Erweitern

Zum Erweitern eines Templates steht der {% extend %}-Tag zu Verfügung.
Beim Erweitern wird ein Template nicht komplett überschrieben, sondern es werden nur gezielt einzelne Teilbereiche (Blöcke) eines übergeordneten Templates (Basis-Template) angepasst.
Dazu muss das Basis-Template mit {% extends "@Contao/('pfad-des-templates')/('name-des-templates') %} angegeben werden.

Contao unterstützt euch bei der Erweiterung von Templates und bei der Anpassung von Blöcken und Anpassen von HTML-Attributen.
Wählst du eines der neuen Twig-Templates zur Anpassung aus, dann wird dir das neue Template für die Vererbung so vorbereitet, dass das Basis-Template bereits angegeben ist. In den Kommentaren findest du die Blöcke und HTML-Attribute, die angepasst werden können.

Blöcke anpassen

Anpassbare Bereiche in Twig Templates befinden sich in Blöcken. Blöcke beginnen mit einem {% block('name-des-blocks') %}-Tag und enden mit einem {% endblock %}-Tag.

Alle Anpassungen müssen innerhalb der verfügbaren Blöcke vorgenommen werden.

Mit {{ parent() }} lässt sich der originale Inhalt des Blocks ausgeben.

Alle nicht angepassten Blöcke werden automatisch aus dem übergeordneten Template übernommen.

{# /templates/content_element/text.html.twig #}
{% extends "@Contao/content_element/text.html.twig" %}
{% block text %}
    <p>Einleitender Text für alle Textelemente</p>
    {{ parent() }}
{% endblock %}

{# /templates/content_element/text/tip.html.twig #}
{% extends "@Contao/content_element/text.html.twig" %}
{% block text %}
    {{ parent() }}
    <p>Hier steht ein zusätzlicher Schlusstext für die Variante »Tip«</p>
{% endblock %}

{# /templates/content_element/text/notice.html.twig #}
{% extends "@Contao/content_element/text.html.twig" %}
{% block text %}
    {{ parent() }}
    <p>Hier steht ein zusätzlicher Schlusstext für die Variante »Notice«</p>
{% endblock %}

HTML-Attribute anpassen

Für die meisten Contao-Komponenten kannst du eine zusätzliche CSS-ID oder CSS-Klasse im Backend vergeben.
Diese werden für die entsprechenden Komponenten gesetzt. Manchmal ist das nicht gewünscht und man möchte die Klasse nur für ein bestimmtes HTML-Tag vergeben bzw. verändern.
Dafür stellt dir Contao die {{ attrs() }}-Funktion zur Verfügung. Damit wird es möglich im übergeordneten Template als Variable verfügbare HTML-Attribute anzupassen.

{# /templates/content_element/text.html.twig #}
{% extends "@Contao/content_element/text.html.twig" %}
{% set text_attributes = attrs(text_attributes|default).addClass('description') %}

Weiter Beispiele und tiefer gehende Erklärungen findest Du im entsprechenden Abschnitt in der Entwicklerdokumentation.

Horizontale Wiederverwendung

Eine sehr leistungsfähige Möglichkeit Teile eines Templates wiederzuverwenden bietet uns die {{ block }}-Funktion. Damit ist es möglich Blöcke innerhalb eines Templates ein oder mehrmals auszugeben.

Dazu muss der Block im Template verfügbar sein. Ein Block ist verfügbar, wenn

• der Block direkt im Template definiert ist.
• der Block aus einem übergeordneten Template stammt.
• der Block über das {% use %}-Tag importiert wird.

Wenn du dir die neuen Contao Core-Templates auf GitHub anschaust, wirst du feststellen, dass das {% use %}-Tag neben dem {% extends %}-Tag am häufigsten verwendet wird.
Während mit dem {% extends %}-Tag alle Blöcke des übergeordneten Templates im Frontend ausgegeben werden, werden mit dem {% use %}-Tag die Blöcke dem Template nur zur Verfügung gestellt. Die Ausgabe eines Blockes erfolgt erst mit der{{ block }}-Funktion.
Dabei können zusätzliche Template-Parameter übergeben werden.

Weitere Informationen und Beispiele zur horizontalen Wiederverwendung findest du in der Entwicklerdokumentation.

Hier im Handbuch erwähnen wir diese komplexe Möglichkeit der Wiederverwendung von Templates nur deshalb, weil du dir für komplexere Template-Anpassungen insbesondere das {% use %}-Tag und die Verwendung von Contao-Komponenten anschauen solltest.