Holy-Grail-Layout mit Twig in Contao 5.7

Wenn die Migration nach Twig schnell gehen muss

Glen Langer (Contao Ninja)

Version: 1.0.1 vom 29.09.2026

Quellen

Online Doku von Symfony / Quellcode Contao
Erfahrung durch Ausprobieren

Über mich

Contao seit 2.5.8
PHP ZCE
Forum: BugBuster
GitHub: BugBuster1701
https://contao.ninja/
Arbeitgeber: T-Systems

Kurze Umfrage

Contao 4.13
mit Holy-Grail-Layout
mit internem CSS Editor

Contao 4.13 nach 5.7 (kurz)

Wie ist das Konzept (composer.json, Datenbank)
Was tun mit Holy-Grail-Layout, statischem html5 Layout
CSS Problematiken (interner Editor, neue Class Namen)
Vorbereitungen
Migration auf 5.7
Probleme und Lösungen
... weiter wie bei Migration Contao 5 auf Twig

Vorbereitung: Interner CSS Editor verwendet?

CSS exportieren
als externe CSS wieder im Theme Layout einbinden, Reihenfolge!
identische interne CSS dann abwählen
Testen

CSS Änderungen - Content-Elemente

code (ce_code → content-code)
headline (ce_headline → content-headline)
html (ce_html → content-html)
list (ce_list → content-list)
text (ce_text → content-text)
table (ce_table → content-table)
hyperlink (ce_hyperlink → content-hyperlink)
toplink (ce_toplink → content-toplink)
image (ce_image → content-image)
gallery (ce_gallery → content-gallery)
youtube (ce_youtube → content-youtube)
vimeo (ce_vimeo → content-vimeo)
download (ce_download → content-download)
downloads (ce_downloads → content-downloads)
markdown (ce_markdown→ content-markdown)
player (ce_player → content-player)
teaser (ce_teaser → content-teaser)

CSS Änderungen - Frontendmodule

CSS Klassen in Frontendmodule bleiben unverändert!
("Sie sterben ja ohnehin allesamt restlos")
Beispiel: faq-bundle/contao/templates/mod_faqpage.html.twig
<div class="ce_text block">
Ticket Anfrage in Slack

CSS Änderungen - Bildposition

float_left → media--left
float_right → media--right
float_above → media--above
float_below → media--below
caption → figcaption

CSS Änderungen 1/3

class image_container

komplett entfernt
HTML-Tag <figure> ansprechen

CSS Änderungen 2/3

CSS Klassen first, last, even und odd

wurden entfernt
durch CSS-Selektoren (first-child, last-child, nth-child) ersetzen

CSS Änderungen 3/3

CSS-Klassen bei der Galerie

zahlreiche CSS-Klassen entfernt
Korrekte Darstellung der Galerien im Frontend prüfen!

Vorbereitung: Erweiterungen für Contao 5.7 verfügbar?

Über die Seite contao-update-check.de prüfen,
passende composer.json generieren lassen

Umstellung auf 5.7 Standard Layout

Hierfür gibt es zahlreiche Anleitungen

Alte angepasste html5 Templates verwendet?
Prüfen ob die noch funktionieren -> neue CE

Kein Backup - kein Mitleid!

Nachbearbeitung vor der Twig Layout Umstellung

Selbst wenn alte html5 Templates noch funktionieren,
Umstellung auf Twig sinnvoll.
andere Altlasten bei der Gelegenheit entfernen / umstellen

Contao 5.7 Twig-Layout mit Slots

Warum (jetzt schon) umstellen auf Twig Layout?

Contao 6 Umstellung auf Output-Encoding
nur mit Twig möglich
Contao 6.3 ~ 02.2028
Umstellung dann schon erledigt
Zeit in Ruhe umzustellen
Grosse Projekte HEUTE vorbereiten:
z.B. jede Woche ein angepasstes Template
Twig macht auch in Contao 5.7 Spaß
Template Studio

Was liefert Contao mit?

Standardlayout - Holy Grail Layout

Template: fe_page

Twig-Layout with Slots

Template: page/layout

Twig

Template Engine für PHP
Standard von Symfony
Endung .twig
Ausgabetyp HTML -> .html - Auto Escaping
template.html.twig

Infos dazu auch auf docs.contao.org - layout/templates/twig/

Was tun mit Holy-Grail-Layout?

Profi Variante

Umbau auf Twig z.B. mit GRID Template Areas, Flexbox
Meine POCs: Repository Contao Twig-Layouts
Maren Vortrag Freitag, 14.00 - 14.50 Uhr | Raum 1

Non-Profi Variante

Holy-Grail-Layout behalten, mit Twig nachbauen

Vorbereitungen
Twig Seiten-Templates erstellen
Umstellen auf Twig-Layout mit Slots
Empfehlung: Umbau der alten CE auf die neuen CE
Optional: Navi mit responsive Template

Migration Contao 5.x zu 5.7 Twig

Vorbereitung

Welches Theme Layout ist in welcher Seite definiert?
Gibt es eigene Bereiche?
Theme Layouts anschauen,
daraus ableitend neue passende Twig Page Layout Variante(n) Templates anlegen
wegen Holy-Grail-Layout mit Helper DIVs

Vorbereitung

Welches Theme Layout ist in welcher Seite definiert?

Liste erstellen
- Hilfreiche SQL Anweisung(en)
- GitHubGist: BugBuster1701 SQL Sammlung

Beispiel

Alle verwendeten Theme - Layout Kombinationen

Beispiel

Alle Seiten mit ihren Theme-Namen und Layout-Namen

Alternative mit Erweiterung

Name: Zusätzliche Seiteninformation im Seitenbaum
e-spin/page-info-bundle (Ingolf)

Beispiel Ausgabe

Vorbereitung

Page Layout nach Holy Grail

neue passende Page Layout Variante anlegen
- mit Helper DIVs
- mit Verwendung der originalen Layout.css
- CSS / JS einbinden was benötigt wird

Beispiel aus Tapestry Demo

{% extends "@Contao/page/layout.html.twig" %}

{%- set body_attributes = attrs()
    .addClass('layout--3x3')
    .mergeWith(body_attributes|default)
-%}

{% block end_of_head %}
    {{ parent() }}
    <style{{ attrs().setIfExists('nonce', csp_nonce('style-src')) }}>
        #wrapper {
            width: 1140px;
            margin: 0 auto;
        }

        #left {
            width: 200px;
            right: 200px;
        }
        
        #right {
            width: 200px;
        }

        #container {
            padding-left: 200px;
            padding-right: 200px;
        }
    </style>
    <link rel="stylesheet" href="{{ asset('tapestry/css/layout.css', 'contao_vfs.files') }}">
    <link rel="stylesheet" href="{{ asset('tapestry/css/responsive.css', 'contao_vfs.files') }}">
    <link rel="stylesheet" href="{{ asset('tapestry/css/basic_tapestry.css', 'contao_vfs.files') }}">
    <link rel="stylesheet" href="{{ asset('tapestry/css/default_tapestry.css', 'contao_vfs.files') }}">
    <link rel="stylesheet" href="{{ asset('tapestry/css/footer_tapestry.css', 'contao_vfs.files') }}">
    <link rel="stylesheet" href="{{ asset('tapestry/css/sticky_footer.css', 'contao_vfs.files') }}">
    <link rel="stylesheet" href="{{ asset('tapestry/css/print_tapestry.css', 'contao_vfs.files') }}">
    <link rel="stylesheet" href="{{ asset('tapestry/css/content_gallery_tapestry.css', 'contao_vfs.files') }}">
    <link rel="stylesheet" href="{{ asset('tapestry/fonts/oswald-latin-regular.css', 'contao_vfs.files') }}">
    <link rel="stylesheet" href="{{ asset('tapestry/fonts/abel-latin-regular.css', 'contao_vfs.files') }}">
    <link rel="stylesheet" href="{{ asset('tapestry/fonts/satisfy-latin-regular.css', 'contao_vfs.files') }}">
    <script src="{{ asset('js/jquery.js', 'contao-components/jquery') }}"></script>
    <meta name="google-site-verification" content="IviramUWcqudfQEX2W47Zd_QCKb0lQp2NP0q-2OFsNk">
{% endblock %}

{% block body %}
    {{ parent() }}
    {{ include('@Contao/j_accordion.html.twig') }}
    {{ include('@Contao/j_colorbox.html.twig') }}
    {{ include('@Contao/js_slider.html.twig') }}
    {# {{ include('@Contao/j_tablesort.html.twig') }} #}
    {# {{ include('@Contao/js_autofocus.html.twig') }} #}
{% endblock %}

{% block body_content %}
<div id="wrapper">
    {% slot header %}
    <header id="header">
        <div class="inside">
            {{ slot() }}
        </div>
    </header>
    {% endslot %}

    <div id="container">
    {% slot main %}
        <main id="main">
            <div class="inside">
                {{ slot() }}
            </div>
        </main>
    {% endslot %}
    {% slot left %}
        <aside id="left">
            <div class="inside">
                {{ slot() }}
            </div>
        </aside>
    {% endslot %}
    {% slot right %}
        <aside id="right">
            <div class="inside">
                {{ slot() }}
            </div>
        </aside>
    {% endslot %}
    </div>

    {% slot footer %}
    <footer id="footer">
        <div class="inside">
            {{ slot() }}
        </div>
    </footer>
    {% endslot %}
</div>
{% endblock %}

Umstellen

Page Layout nach Holy Grail mit Twig

Theme Layout Kopie anlegen und umstellen auf Twig
- Auswahl des vorher angelegten Page Layout Templates
Seite(n) umstellen auf das neue Theme Layout
Testen!

Nacharbeiten Contao 5.x zu 5.7 Twig

Selbst wenn alte html5 Templates noch funktionieren,
Umstellung auf Twig sinnvoll.
andere Altlasten bei der Gelegenheit entfernen / umstellen

Nacharbeiten Contao 5.x zu 5.7 Twig

Empfehlung

Umbau der Legacy Elemente auf die neuen CE, falls noch in Verwendung
- betrifft Akkordeon, (alt: Einzel, Umschlag Anfang/Ende)
  neu: Verschiedenes ->Akkordeon
- betrifft Slider (alt: Umschlag Anfang/Ende)
  neu: Content-Slider

Optional

Navigation mit responsive Template, CSS Anpassungen

Links (Profi Variante)

Grid Named Areas

YT: css-tricks.com: Using Grid Named Areas...

coding2go

Maren@Konferenz 2025

YT: Modernes CSS (Grid, Subgrid, Flex und Co) in Contao nutzen

Fragen?

Dann los!

Bonus Easteregg?!

Contao 5.7

Theme Layout "Standardlayout" +
Seiten-Template "fe_page" = ?
=> fe_page.html.twig!
Holy-Grail-Layout mit Twig ohne Slots

Happy Coding!

Aktuelle Version dieser Folien auf: docs.contao.ninja

(später auch als PDF)