Contao Austria - Twig Templates

Twig Templates in Contao 5

Basics

Bernhard Renner
werbepanorama.at
WERBEpanorama OG

Was ist Twig?

Twig ist eine Template-Engine für PHP
ist seit Contao 4.13 im Einsatz
Die legacy Content Elemente können noch weiterhin eingesetzt werden ...

Das bedarf jedoch einer Anpassung

in der `contao/config/config.php` braucht es folgende Anpassung:  
							```
							// Restore legacy content elements
							$GLOBALS['TL_CTE']['texts']['code'] = \Contao\ContentCode::class;
							$GLOBALS['TL_CTE']['texts']['headline'] = \Contao\ContentHeadline::class;
							$GLOBALS['TL_CTE']['texts']['html'] = \Contao\ContentHtml::class;
							$GLOBALS['TL_CTE']['texts']['list'] = \Contao\ContentList::class;
							$GLOBALS['TL_CTE']['texts']['text'] = \Contao\ContentText::class;
							$GLOBALS['TL_CTE']['texts']['table'] = \Contao\ContentTable::class;
							$GLOBALS['TL_CTE']['links']['hyperlink'] = \Contao\ContentHyperlink::class;
							$GLOBALS['TL_CTE']['links']['toplink'] = \Contao\ContentToplink::class;
							$GLOBALS['TL_CTE']['media']['image'] = \Contao\ContentImage::class;
							$GLOBALS['TL_CTE']['media']['gallery'] = \Contao\ContentGallery::class;
							$GLOBALS['TL_CTE']['media']['youtube'] = \Contao\ContentYouTube::class;
							$GLOBALS['TL_CTE']['media']['vimeo'] = \Contao\ContentVimeo::class;
							$GLOBALS['TL_CTE']['files']['downloads'] = \Contao\ContentDownloads::class;
							$GLOBALS['TL_CTE']['files']['download'] = \Contao\ContentDownload::class;
							$GLOBALS['TL_CTE']['media']['player'] = \Contao\ContentPlayer::class;
							$GLOBALS['TL_CTE']['includes']['teaser'] = \Contao\ContentTeaser::class;  
							```

Müssen wir Twig verwenden?

noch nicht - es kann noch mit den legacy html5-Templates gearbeitet werden
html5-Templates werden zukünftig abgeschalten werden » Contao 6 (??)
Entwickler von Erweiterungen und Themes können jedoch bereits auf Twig setzen
JA, wir müssen uns damit beschäftigen

Syntax von Twig

Variablen ausgeben
{{ meineVariable }}
Kommandos
{% if ... endif ... %}
Kommentare
{# my awesome command #}

Contao Handbuch - Syntax

Twig Syntax

Twig Filter

Korrekte Ordnerstruktur

Twig benötigt eindeutige Ordnerstrukturen.
eigene Templates liegen jedoch immer im Ordner

							
								/templates

Wir unterscheiden zwischen

Globale Twig Templates
Varianten-Twig Templates

Contao Handbuch - Ordnerstruktur

je nach angepassten Template sieht auch die Ordnerstruktur aus:

								
									/templates/component/
									/templates/content_element/
									/templates/frontend_element/
									/templates/theme/

Legen wir ein neues Twig-Template im Backend an, müssen wir uns über die Ordnerstruktur keine weiteren Gedanken machen.

Wir erstellen das Template, ohne selbst eine Ordnerstruktur erstellen zu müssen.

erstellt wurde nun automatisch:

Ordner /templates/content_element
Datei /swiper.html.twig

je nachdem, welches Template wir ausgewählt haben, wird ein globales Twig-Template angelegt.

Anpassungen in diesem globalen Twig-Template haben Auswirkungen auf alle verwendeten Inhaltselemente - in diesem Fall

Individuelles Template

Um jedoch gezielt, für z.B. unterschiedliche Darstellungen im Frontend, ein Template einzusetzen, nutzen wir ein variables Twig-Template.

Hierzu erstellen wir im Ordner des globalen Templates einen neuen Ordner, der so heisst wie das Template selbst.
swiper.html.twig » /swiper/
template.html.twig » /template/

In den jeweiligen Ordner kommt nun unser angepasstes Twig-Template rein.
unbedingt Namenskonvention beachten!
Contao Enwickler-Handbuch

zurück » korrekte Ordnerstruktur

RSCE Templates

RSCE Templates werden wie bisher gehandhabt.
Es gibt weiterhin (mind.) 2 Dateien:

rsce_myown_config.php
rsce_myown.html.twig
(rsce_myown_be.html.twig)

RSCE Templates verbleiben weiterhin im Ordner
/templates/theme/

Twig-Template anpassen

Beispiel text.html.twig
Wir erstellen unser Template wie vorhin beschrieben und erhalten

							
								/templates/content_element/text.html.twig

```
							{% extends "@Contao/content_element/text.html.twig" %}

{#
							  ** Add changes to the base template here. **
							
							  Hint: Try adjusting blocks and attributes instead of
							  overwriting the whole template. This way your version
							  can remain compatible with future changes to the base
							  template as well as adjustments made by extensions.
							
							  Currently available blocks:
								"picture_component", "image", "sources", "source",
								"schema_org", "figure_component", "media",
								"media_link", "caption", "caption_inner",
								"text_media", "content", "text",
								"text_attributes", "headline_component",
								"headline_attributes", "headline_inner",
								"wrapper", "wrapper_tag", "attributes", "inner",
								"metadata", "style", "script"
							
							  Example:
								{% block picture_component %}
								   {{ parent() }}
								   My additional content for 'picture_component'…
								{% endblock %}
							#}
							```  
							[text.html.twig auf Github](https://github.com/contao/contao/blob/5.3/core-bundle/contao/templates/twig/content_element/text.html.twig)

BEACHTE:
Anpassungen im Bereich Twig-Templates werden nicht sofort übernommen.
Es muss der Production cache geleert werden.
Oder aber man arbeitet im DEV-Mode.

							
								/env.local
								APP_ENV=dev

Varianten Twig-Template anlegen

Hier gehen wir wie bereits vorab beschrieben vor.

Template anlegen
Ordner für das Varianten-Twig anlegen
Varianten-Twig darinnen anlegen
Varianten-Twig nach den eigenen Bedürfnissen anpassen

im Inhaltselement muss das variable Twig-Template nun noch ausgewählt werden.

Beispiel

Dem Inhaltselement Galerie werden zusätzliche Klassen hinzugefügt.

Woher weiss man, welche Blöcke angepasst werden müssen?

das angepasste Twig schreibt die verwendbaren Blöcke in die commands
Lesen des Codes im Core-Twig-Template
üben, testen und lernen :-)

RSCE Template anlegen

Um ein RSCE Twig-Template anzulegen braucht es keine gesonderte Ordnerstruktur.
Alles bleibt so wie bisher » Ausnahme:
Templatename für das Frontend ändert sich
rsce_myown.html.twig

Beispiel: Service Box

```
							{# /templates/theme/rsce_service-box_config.php #}
							<?php

return [
								'label' => ['Service-Box','Erstellt Element Service-Box'],
								'types' => ['content'],
								'standardFields' => ['cssID'],
								'contentCategory' => 'texts',
								'fields' => [
									'headline' => [
										'inputType' => 'standardField',
										'options' => ['h3'],
									],
									'text' => [
										'inputType' => 'standardField',
										'eval' => [
											'tl_class' => 'clr',
										],
									],
									'url' => [
										'label' => &$GLOBALS['TL_LANG']['MSC']['url'],
										'inputType' => 'text',
										'eval' => [
											'mandatory' => false, 
											'rgxp' => 'url',
											'decodeEntities' => true,
											'maxlength' => 2048,
											'dcaPicker' => true,
											'tl_class' => 'w50'
										],
									],            
									'linkTitle' => [
										'label' => ['Link-Text','Der Link-Text wird anstelle der Link-Adresse angezeigt.'],
										'inputType' => 'text',
										'eval' => [
											'tl_class' => 'w50'
										],
									],
									'titleText' => [
										'label' => ['Link-Titel','Der Link-Titel wird als title-Attribut im HTML-Markup eingefügt.'],
										'inputType' => 'text',
										'eval' => [
											'tl_class' => 'w50'
										],
									],
									'target' => [
										'label' => &$GLOBALS['TL_LANG']['MSC']['target'],
										'inputType' => 'checkbox',
										'eval' => [
											'tl_class' => 'w50 m12'
										],
									],       
									'image' => [
										'label' => ['Icon','Wähle ein Bild als Icon aus.'],
										'inputType' => 'fileTree',
										'eval' => [
											'tl_class' => 'clr',
											'filesOnly' => true,
											'fieldType' => 'radio',
											'mandatory' => false,
											'extensions' => '%contao.image.valid_extensions%',
										],
									],         
								],
							];
							```

							{{ class }}

fügt die Standardklasse plus die im Inhaltselement eingefügten Klassen ein.

fragt ab, ob headline definiert und nicht leer ist.
Und fügt danach mit dem Filter raw den Inhalt ein.

							{{ text|raw }}

fügt mit dem Filter raw den Inhalt des tinyMCE Fensters ein.

fragt ab, ob url definiert und nicht leer ist.
Fügt danach mit dem Filter raw die URL ein.
Löst linkTitle auf und fügt diesen ein und schliesst nach einer Abfrage wieder den <a>-tag

In diesem Abschnitt wird der Bild-link ausgelesen und eingefügt.