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.:
Für komplexere Anpassungen stehen noch viele weitere Möglichkeiten zur Verfügung. Die Beschreibung findest du in der Entwicklerdokumentation:
Für die Wiederverwendung von Templates solltest du dich mit der Template-Hierarchie in Contao vertraut machen.
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.
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.
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.
Wir legen uns über das Backend ein neues Template für das Inhaltselement Text an und fügen in den Block {% block text %} einen zusätzlichen Text ein.
{# /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 %}
In allen Text-Elementen wird jetzt vor dem Text, den wir im Tiny-MCE eingegeben haben, der Text Einleitender Text für alle Text-Elemente ausgegeben.
Wir legen uns nun zusätzlich zwei Varianten für das Text-Element an. Die Varianten erhalten im Block {% block text %}
jeweils einen eigenen Schlusstext.
{# /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 %}
Wählen wir jetzt das Template content_element/text/tip aus, dann ist das übergeordnete Template das Template
/templates/content_element/text.html.twig.
Zu Beginn wird wieder der Text Einleitender Text für alle Text-Elemente ausgegeben und zusätzlich am Ende der
Text Hier steht ein zusätzlicher Schlusstext für die Variante »Tip«. Zwischen diesen beiden Texten steht der komplette
Text, den wir im Tiny-MCE eingegeben haben.
Bei Verwendung des Templates content_element/text/notice wird der Schlusstext Hier steht ein zusätzlicher Schlusstext für die Variante »Notice« ausgegeben.
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.
Wir möchten für das div-Tag, welches um den Textbereich liegt, die Klasse description ergänzen. Dazu passen wir die
Variable text_attributes entsprechend an. Mit set wird die Variable mit neuem Inhalt gefüllt. Die
Funktion attrs(text_attributes|default)
stellt uns die vorhandenen Attribute zur Verfügung mit addClass ergänzen wir die Attribute um die gewünschte Klasse.
{# /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.
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
{% 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.
Schau dir den Aufbau der neuen Core Templates an. Dann siehst du, welcher Code sich in den einzelnen Blöcken der
Templates befindet. Du findest diese auf GitHub.