Der Umstieg auf Contao 5 Twig Templates ist der radikalste, aber auch lohnendste Schritt in der modernen Contao-Entwicklung. Während wir früher mit unsicheren PHP-Templates (.html5) und globalen Arrays kämpften, bietet die neue Architektur Sicherheit und Struktur. Wer Contao 5 Twig Templates beherrscht, schreibt keinen Spaghetti-Code mehr, sondern nutzt echte Fragment Controller und die mächtige Vererbung der Twig-Engine.

Unsere Datenbank ist gefüllt, die Logik ist getestet (siehe Teil 6). Aber wenn wir die Webseite aufrufen, sehen wir noch nichts. Es ist Zeit, die "Black Box" zu öffnen. Wir rendern jetzt unsere Strandkörbe.

Warum Twig statt PHP? Laut der offiziellen Contao Developer Documentation und dem Upgrade Guide gibt es drei Gründe für den Wechsel:

Security by Design: Contao 5 Twig Templates escapen Ausgaben automatisch. XSS-Lücken (Cross-Site Scripting) gehören der Vergangenheit an.
Vererbung (Inheritance): Wir müssen CSS-Klassen oder Wrapper-Divs nicht neu erfinden, sondern erben via {% extends %} direkt vom Core.
Debugging: Twig warnt dich sofort, wenn du eine Variable nutzt, die nicht existiert.

Das ist der Plan:

Einen Content Element Controller schreiben (Datenbeschaffung).
Das Twig Template erstellen (Vererbung nutzen).
Bilder professionell mit dem Image Studio (contao_figure) rendern.
Listenansichten und Attribute-Helper (attrs) meistern.

Lass uns den Controller bauen.

Evolution von alten PHP-Templates zu modernen Twig-Templates

1. Der Fragment Controller: Datenbeschaffung

In Contao 4 nutzten wir oft noch Klassen, die von ContentElement erbten und die generate()-Methode überschrieben. Das war "okay", aber nicht wirklich Symfony-like. In Contao 5 ist ein Content-Element (oder Modul) technisch gesehen ein Fragment Controller. Er nimmt eine Anfrage entgegen, verarbeitet Daten und gibt eine Response zurück. Das macht den Code extrem testbar und sauber.

Wir erstellen einen Controller, der einen spezifischen Strandkorb basierend auf einer Auswahl im Backend anzeigt. Wir gehen davon aus, dass wir im DCA (Teil 3) ein Feld beachChair angelegt haben, das die ID des Strandkorbs speichert.

Die Datei: Erstelle: /src/BeachsideBundle/src/Controller/ContentElement/BeachChairElementController.php

PHP

<?php

namespace Acme\BeachsideBundle\Controller\ContentElement;

use Acme\BeachsideBundle\Repository\BeachChairRepository;
use Contao\ContentModel;
use Contao\CoreBundle\Controller\ContentElement\AbstractContentElementController;
use Contao\CoreBundle\DependencyInjection\Attribute\AsContentElement;
use Contao\CoreBundle\Twig\FragmentTemplate;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

#[AsContentElement(category: 'beachside', template: 'content_element/beach_chair_details')]
class BeachChairElementController extends AbstractContentElementController
{
    public function __construct(
        private readonly BeachChairRepository $repository
    ) {
    }

    protected function getResponse(FragmentTemplate $template, ContentModel $model, Request $request): Response
    {
        // Wir gehen davon aus, dass wir im DCA ein Feld 'beachChair' haben, 
        // das die ID speichert (haben wir in Teil 4 vorbereitet).
        $chairId = $model->beachChair; 

        if (!$chairId) {
            return new Response(); // Leeres Element, wenn nichts ausgewählt
        }

        // Daten aus der DB holen
        $chair = $this->repository->find($chairId);

        if (!$chair) {
            // Optional: Fehlermeldung im Debug-Mode ausgeben
            return new Response();
        }

        // Daten an das Template übergeben
        $template->set('chair', $chair);
        
        // Zusatz-Feature: Verfügbarkeit prüfen (Nutzen wir unseren Service aus Teil 5/6?)
        // $template->set('isAvailable', ...);

        return $template->getResponse();
    }
}

Code-Analyse:

#[AsContentElement]: Dieses PHP 8 Attribut registriert den Controller automatisch bei Contao. Wir definieren hier auch gleich die Kategorie (für den Auswahl-Wizard im Backend) und den Pfad zum Twig-Template.
Dependency Injection: Wir nutzen unser BeachChairRepository direkt im Konstruktor. Keine statischen Aufrufe wie Database::getInstance() mehr! Das ist der moderne Weg.
FragmentTemplate: Das ist unser Wrapper für das Twig-Template. Wir "befüllen" ihn mit set() und lassen ihn am Ende die fertige Response generieren.

Ein Chip wird installiert, darüber schwebt ein Attribut-Tag

2. Das Twig Template: Basics & Vererbung

Jetzt erstellen wir die Datei, die wir im Controller definiert haben: content_element/beach_chair_details. Der Speicherort hängt von deiner Bundle-Konfiguration ab, aber standardmäßig in einem lokalen Bundle liegt sie unter: /src/BeachsideBundle/templates/content_element/beach_chair_details.html.twig.

Der Clou bei Contao 5 Twig Templates: Wir fangen nicht bei Null an. Wir erben vom Basis-Element des Contao Cores. Das ist ein massiver Vorteil gegenüber alten .html5 Templates. Indem wir {% extends "@Contao/content_element/_base.html.twig" %} nutzen, kümmert sich Contao automatisch um:

Den umschließenden Wrapper (<div>).
Die CSS-ID und CSS-Klassen, die der Redakteur im Backend eingibt.
Den Zugriffsschutz (Element nur für Gäste/Mitglieder sichtbar).
Abstände (Space before/after).

Wir müssen uns nur um den Inhalt kümmern.

Der Code:

Twig

{# Wir erben vom Basis-Template des Cores #}
{% extends "@Contao/content_element/_base.html.twig" %}

{# Wir überschreiben den 'content' Block #}
{% block content %}
    
    <div>
        <header>
            <h2>{{ chair.title }} <small>(Nr. {{ chair.chairNumber }})</small></h2>
        </header>

        <div>
            <p>
                Preise ab: <strong>{{ (chair.pricePerDay / 100)|format_currency('EUR') }}</strong> / Tag
            </p>
            
            <div>
                {# 'raw' Filter ist sicher, da wir im DCA den TinyMCE nutzen, der Code bereinigt #}
                {{ chair.description|raw }}
            </div>
        </div>
        
        {# Platzhalter für Buchungs-Button #}
        <div>
            <button>Jetzt buchen</button>
        </div>
    </div>

{% endblock %}

Wichtige Twig-Features hier:

Getter-Support: {{ chair.title }} funktioniert, obwohl die Property private ist und die Methode getTitle() heißt. Twig ist schlau genug, die Verknüpfung herzustellen.
Filter: |number_format formatiert unseren Cent-Preis in lesbare Euro.
extends: Wir schreiben kein div für das Content-Element selbst. Das kommt aus der _base.html.twig.

Verschachtelte Ebenen zeigen die Template-Vererbung

3. Bilder rendern mit dem Image Studio

In früheren Contao-Versionen war der Umgang mit Bildern oft mühsam: FilesModel laden, Pfad suchen, Image::get() aufrufen. In Contao 5 nutzen wir das Image Studio und die mächtige Twig-Funktion contao_figure. Sie ist der neue Standard und generiert vollautomatisch responsive Bilder (srcset, sizes), WebP-Formate und Metadaten.

Voraussetzung: Wir gehen davon aus, dass deine Entity BeachChair ein Feld imageUUID hat (in der Datenbank als BINARY(16) gespeichert), das über den DCA-Filetree befüllt wurde.

Der Code im Template: Wir erweitern unser beach_chair_details.html.twig:

Twig

{% block content %}
    <div>
        
        {# Bild rendern #}
        {% if chair.image %}
            <div>
                {# 
                   uuid: Die Binary UUID aus der Datenbank
                   size: Die ID einer Bildgröße aus dem Theme (z.B. 'product_image') 
                         oder null für Originalgröße 
                #}
                {{ contao_figure(chair.image, 'product_image', {
                    class: 'img-fluid rounded',
                    alt: chair.title
                }) }}
            </div>
        {% endif %}

        <header>...</header>
        ...
    </div>
{% endblock %}

Warum ist contao_figure genial? Laut der Image Studio Dokumentation passiert im Hintergrund Folgendes:

Metadaten-Lookup: Contao sucht automatisch den Alt-Text und die Bildunterschrift, die der Redakteur in der Dateiverwaltung hinterlegt hat. Du musst das nicht manuell tun!
Responsive Markup: Es wird ein komplettes HTML <picture>-Element generiert, inklusive WebP-Sources und Fallbacks.
Performance: loading="lazy" und width/height Attribute werden automatisch gesetzt, um Layout Shifts (CLS) zu verhindern.

Profi-Tipp: Wenn du eine Bildgröße "On-the-Fly" definieren willst (ohne Backend-Konfiguration), nutze die Funktion picture_config:

Twig

{% set my_size = picture_config({
    width: 800,
    height: 600,
    resizeMode: 'crop'
}) %}

{{ contao_figure(chair.imageUUID, my_size) }}

Ein Bild wird in verschiedene Größen aufgeteilt

4. Listenansicht: Das Frontend Modul

Bisher haben wir ein einzelnes Element gerendert. Jetzt wollen wir eine Liste aller Strandkörbe anzeigen. Dafür eignet sich klassischerweise ein "Frontend Modul". Interessant in Contao 5: Die Grenze zwischen Content-Element und Modul verschwimmt. Beide sind Fragment Controller. Der Hauptunterschied liegt oft nur in der semantischen Nutzung (Module sind oft global im Layout eingebunden, Content-Elemente im Artikel).

Der Controller:
Erstelle: /src/BeachsideBundle/src/Controller/FrontendModule/BeachChairListController.php

PHP

<?php

namespace Acme\BeachsideBundle\Controller\FrontendModule;

use Acme\BeachsideBundle\Repository\BeachChairRepository;
use Contao\CoreBundle\Controller\FrontendModule\AbstractFrontendModuleController;
use Contao\CoreBundle\DependencyInjection\Attribute\AsFrontendModule;
use Contao\CoreBundle\Twig\FragmentTemplate;
use Contao\ModuleModel;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

#[AsFrontendModule(category: 'beachside', template: 'frontend_module/beach_chair_list')]
class BeachChairListController extends AbstractFrontendModuleController
{
    public function __construct(
        private readonly BeachChairRepository $repository
    ) {
    }

    protected function getResponse(FragmentTemplate $template, ModuleModel $model, Request $request): Response
    {
        // Alle Strandkörbe holen
        // In einer echten App würden wir hier Paginierung und Sortierung einbauen.
        $chairs = $this->repository->findAll();

        $template->set('chairs', $chairs);

        return $template->getResponse();
    }
}

Das Template: Wir erstellen templates/frontend_module/beach_chair_list.html.twig. Hier nutzen wir die Stärke von Twig, um Code zu recyceln (DRY - Don't Repeat Yourself). Anstatt den HTML-Code für die "Strandkorb-Karte" neu zu schreiben, lagern wir ihn in ein Partial aus.

Twig

{# Wir erben vom Basis-Modul-Template #}
{% extends "@Contao/frontend_module/_base.html.twig" %}

{% block content %}
    <div>
        {% for chair in chairs %}
            
            {# 
               Wir inkludieren ein Teaser-Template und übergeben den aktuellen Strandkorb.
               Das Partial '_teaser.html.twig' liegt im Ordner 'partial' oder 'common'.
            #}
            {% include '@AcmeBeachside/content_element/_beach_chair_teaser.html.twig' with { chair: chair } %}
        
        {% else %}
            
            {# Fallback, wenn das Array leer ist #}
            <div>
                Aktuell sind alle Strandkörbe im Winterschlaf.
            </div>
            
        {% endfor %}
    </div>
{% endblock %}

Was wir gelernt haben:

AbstractFrontendModuleController: Das Gegenstück zum ContentElementController.
{% for ... else %}: Twig Loops haben einen eingebauten else-Zweig für leere Arrays. Das spart uns ein if count > 0 in PHP.
include: Damit halten wir unsere Templates klein und wartbar.

Profi-Tipp: Nutze include oder Twig Components, um den Code für die "Karte" (Teaser) auszulagern. So kannst du das Layout für die Liste und das Einzel-Element teilen.

5. Attributes & HTML Helper: Schluss mit String-Chaos

Ein häufiges Problem in alten Templates war das Zusammenbauen von CSS-Klassen: $class = 'item ' . ($obj->highlight ? 'highlight ' : '') . $this->class; Das führt oft zu fehlenden Leerzeichen oder doppeltem Code.

In Contao 5 Twig Templates nutzen wir dafür die mächtige Funktion attrs(). Sie erstellt ein intelligentes Attribut-Objekt, das wir manipulieren können, bevor wir es rendern.

Beispiel: Dynamische Klassen für den Strandkorb Wir wollen dem Container eine Klasse geben, wenn der Strandkorb "Premium" ist (Preis > 20€), und eine Data-ID für JavaScript hinzufügen.

Twig

{# Wir erstellen ein Attribut-Objekt #}
{% set chairAttributes = attrs()
    .addClass('beach-chair-card')
    .addClass('is-premium', chair.pricePerDay > 2000) {# Bedingung direkt hier! #}
    .set('data-id', chair.id)
    .set('title', 'Strandkorb ' ~ chair.chairNumber)
%}

{# 
   Ausgabe: 
   data-id="42" title="Strandkorb 7"
#}
<div {{ chairAttributes }}>
    ...
</div>

Warum ist das besser?

Sicherheit: Attribute werden automatisch escaped.
Logik-Trennung: Keine if-Blöcke mitten im HTML-Tag.
Merging: Wenn du ein Template erweiterst (extends), kannst du attributes.mergeWith(...) nutzen, um die Klassen des Parent-Templates zu behalten und deine eigenen hinzuzufügen.

Weitere nützliche Helper für Contao 5 Twig Templates:

content_url(uuid): Generiert die URL zu einer Datei aus der Dateiverwaltung (anhand der UUID).
format_date(timestamp, 'date'): Formatiert Datumswerte lokalisiert (benötigt twig/intl-extra).
- Beispiel: {{ chair.tstamp|format_date('relative_medium') }} -> "vor 2 Tagen".

Verschachtelte Elemente (Nested Fragments): Wenn dein Strandkorb selbst Container für andere Inhaltselemente sein soll (z.B. ein Slider im Strandkorb-Detail), nutzt du: {{ content_element(nestedFragment) }}. Das ermöglicht komplexe Layout-Strukturen ("Elemente in Elementen"), die in Contao 5 viel sauberer gelöst sind als früher.

Ein Roboterarm fügt Attribute zu einem HTML-Block hinzu

6. Performance: Caching verstehen

Contao 5 ist schnell. Aber nur, wenn wir das Caching verstehen. Standardmäßig cacht Contao die komplette HTML-Ausgabe deines Controllers automatisch, sofern die Seite im Seitenlayout als "cachebar" markiert ist und das Element nicht explizit als "privat" (nicht cachebar) definiert wurde.

Was aber, wenn wir eine individuelle Cache-Zeit für unseren Strandkorb wollen? Zum Beispiel soll die Verfügbarkeit für 1 Stunde (3600 Sekunden) im Cache bleiben, auch wenn die Seite eigentlich 24 Stunden gecacht wird.

Wo gehört der Code hin? Der Eingriff passiert in deinem Fragment Controller (z.B. BeachChairElementController.php), innerhalb der protected function getResponse.

Der exakte Code-Ablauf:

PHP

    // ... Imports und Klassendefinition ...

    protected function getResponse(FragmentTemplate $template, ContentModel $model, Request $request): Response
    {
        // 1. Datenlogik (wie in Iteration 2)
        $chairId = $model->beachChair;
        $chair = $this->repository->find($chairId);
        
        // Daten an das Template übergeben
        $template->set('chair', $chair);

        // -----------------------------------------------------------
        // 2. Response Objekt generieren
        // -----------------------------------------------------------
        // Wir lassen das Template die Standard-Response erstellen.
        $response = $template->getResponse();

        // -----------------------------------------------------------
        // 3. Cache-Header manipulieren (HIER IST DER ORT)
        // -----------------------------------------------------------
        // Wir setzen die "Shared Max Age" (TTL für Reverse Proxies/HttpCache).
        // Das bedeutet: Dieses Fragment ist für 1 Stunde gültig.
        if ($chair && $chair->isHighlyFluctuating()) {
             // Kurze Cache-Zeit für dynamische Preise/Verfügbarkeit
             $response->setSharedMaxAge(600); // 10 Minuten
        } else {
             // Lange Cache-Zeit für statische Inhalte
             $response->setSharedMaxAge(3600); // 1 Stunde
        }

        // Optional: Varnish/Browser anweisen, neu zu validieren
        // $response->headers->addCacheControlDirective('must-revalidate', true);

        // -----------------------------------------------------------
        // 4. Modifizierte Response zurückgeben
        // -----------------------------------------------------------
        return $response;
    }

Erklärung der Schritte:

Daten holen: Zuerst passiert die normale Logik.
$template->getResponse(): Das ist der entscheidende Moment. Contao wandelt das befüllte Template in ein HTTP-Response-Objekt um.
Manipulation: Da $response ein Objekt ist (Referenz), können wir jetzt Methoden darauf aufrufen. setSharedMaxAge() steuert den HTTP-Header s-maxage.
Return: Erst jetzt geben wir das manipulierte Objekt an den Core zurück.

Szenario für Profis: ESI (Edge Side Includes) Wenn der Rest der Seite extrem lange gecacht werden soll (z.B. 1 Woche), aber der "Buchen"-Button live sein muss, lagerst du den Button in einen eigenen Controller aus und bindest ihn im Twig-Template via {{ render_esi(...) }} ein. Contao 5 erkennt das automatisch und cacht die Hauptseite und den Button getrennt voneinander.

#template

Contao 5 Twig Templates: Frontend-Ausgabe mit Fragment Controllern