Von LASR 4 auf LASR 5 migrieren

LASR 5 bringt einige strukturelle Änderungen mit, die bei der Migration eines bestehenden Projekts beachtet werden müssen. Diese Anleitung führt dich durch die wichtigsten Schritte.

Wichtig: Die Änderungen sind umfangreich. Erstelle vor der Migration mindestens ein Backup, besser noch ein Duplikat des Projekts, in dem du die Migration durchführst. Erst nach erfolgreichem Test solltest du die Änderungen auf das Live-System übernehmen.

Voraussetzungen

• Vollständiges Backup der Dateien und der Datenbank
• Staging-Umgebung oder Duplikat statt direkt auf dem Live-System zu arbeiten
• Du hast Zugriff auf Contao Manager und Backend
• Die LASR-5-ZIP-Datei aus dem Club-Bereich liegt dir vor

Überblick der Änderungen

Bereich	LASR 4.x	LASR 5.x
Templates	HTML5-Templates (*.html5)	Twig-Templates (*.html.twig)
Template-Anpassungen	templates/-Ordner	Template Studio (empfohlen, templates/ weiterhin möglich)
Theme-Dateien	files/theme/	layout/custom/ (per Theme Editor verwaltet)
Theme-Toolbox	3.x	4.x
Skript-Cache umgehen	Notwendig	Nicht mehr nötig (übernimmt Theme Toolbox)
Updates	Über Contao Manager / Composer	Über Menüpunkt Updates in der Theme Toolbox
Contao	5.3 / 5.7	5.7

1. Contao auf 5.7 aktualisieren

Sofern noch nicht geschehen, musst du das Projekt auf Contao 5.7 aktualisieren. Dafür einfach im Contao Manager auf Version 5.7 umstellen und „Alle Pakete aktualisieren" ausführen. Anschließend werden die anstehenden Datenbank-Migrationen durchgeführt.

Nach dem Update ist Contao auf der gewünschten Version, im Frontend könnten aber noch Fehler auftauchen. Das liegt daran, dass der SCSS-Compiler in Contao 5.7 strenger ist als bisher. Diese Fehler beheben wir in den nächsten Schritten.

Hinweis: In LASR ab Version 4.2 wurden viele dieser Probleme bereits abgefangen. Wenn du mit einer älteren 4.x-Version startest, wirst du mehr Fehlermeldungen sehen – der Migrationspfad ist trotzdem derselbe.

2. LASR 5 installieren

Im Contao Manager das Paket erdmannfreunde/lasr-theme-bundle auswählen und auf Version ^5.0 aktualisieren. Anschließend „Alle Pakete aktualisieren" ausführen und die Datenbank-Migrationen durchführen lassen.

Nach dem Update findest du im Backend einen neuen, eigenständigen Bereich Theme-Toolbox mit drei Untermenüpunkten:

• Klassen-Manager – die bisherigen CSS-Klassen mit ihren Übersetzungen (wie aus früheren Versionen bekannt)
• Theme Editor – das neue Werkzeug zur Verwaltung der Theme-Dateien
• Updates – hier werden ab sofort Theme-Updates eingespielt

3. LASR 5 über den Updates-Menüpunkt einspielen

Wechsle in das Backend zu Theme-Toolbox » Updates und lade dort die LASR-5-ZIP-Datei aus dem Club-Bereich hoch.

In Zukunft werden alle Theme-Updates über diesen Menüpunkt installiert. Während des Updates passiert Folgendes:

1. Die neuen Theme-Dateien werden in den Ordner layout/lasr-theme/ kopiert (das ist die neue, schreibgeschützte „Originalversion" des Themes).
2. LASR 5 selbst enthält nur noch Twig-Templates. Eigene .html5-Templates aus deinem templates/-Ordner werden vom Update nicht angefasst und funktionieren weiterhin (siehe Abschnitt 9).
3. Eine kurze Statistik zeigt, welche Dateien kopiert oder aktualisiert wurden.
4. Vorhandene Custom-Dateien werden vor dem Überschreiben unter var/backups/theme-updates/ gesichert.

4. Bestehende Theme-Anpassungen migrieren

Da das Update erkennt, dass bereits ein Theme unter files/theme/ existiert, fragt es:

„Es wurde ein bestehendes Theme unter files/theme/ gefunden. Möchten Sie Dateien nach layout/custom/ kopieren?"

Bestätige diese Abfrage. Hintergrund: Der Theme-Code soll künftig nicht mehr im Datei-Manager (files/) liegen, sondern unter layout/custom/. Dort werden die Dateien vom Theme Editor verwaltet – oder, wenn du direkt auf dem Server arbeitest, mit deinem Code-Editor deiner Wahl.

Wichtig: Das alte Verzeichnis files/theme/ bleibt zunächst unverändert erhalten – es wird kopiert, nicht verschoben. Du solltest es nach erfolgreicher Migration manuell entfernen.

4.1 Duplikate prüfen

Im nächsten Schritt fragt der Updater:

„Möchten Sie prüfen, welche Dateien in layout/custom/ identisch mit dem Pendant aus dem Theme sind und gelöscht werden können?"

Bestätige auch diesen Schritt. Der Updater vergleicht die kopierten Dateien mit den neuen Originalen und entfernt alle, die ohnehin unverändert sind. Übrig bleiben nur die Dateien, die wirklich projektspezifische Anpassungen enthalten.

5. Seitenlayout auf neue SCSS-Datei umstellen

Solange im Seitenlayout noch die alte default.scss aus files/theme/ referenziert ist, wird die alte Datei verwendet und die Migration wirkt sich nicht auf das Frontend aus.

Gehe daher in jedes Seitenlayout (mindestens das Standard-Layout) und passe die externen Style Sheets an:

1. Layout » Seitenlayouts » [Layout bearbeiten]
2. Im Bereich Externe Style Sheets die alte default.scss (aus files/theme/) abwählen.
3. Im neuen Bereich Theme Toolbox im Select-Feld Theme SCSS die default.scss aus dem layout/-Ordner auswählen.
4. Speichern.

Wiederhole das für alle Seitenlayouts, die das Theme verwenden.

6. Anpassungen im Theme Editor abgleichen

Öffne Theme-Toolbox » Theme Editor. In der Dateibaum-Ansicht erkennst du sofort, welche Dateien projektspezifisch angepasst wurden:

• Fett gedruckt mit Sternchen (*) = Variante vom Original (entweder durch deine Anpassungen oder durch Änderungen in der neuen Theme-Version)
• Normale Schrift = unverändertes Original

Klicke eine angepasste Datei an. Über die Funktion Unterschiede anzeigen siehst du den Diff zwischen Original und deiner Version.

Daraus ergibt sich die Aufräumstrategie:

• Keine eigenen Anpassungen, nur Versions-Unterschiede (z.B. weggefallene Vendor-Prefixes) → Original wiederherstellen. Die Datei wird aus layout/custom/ entfernt, das Theme nutzt wieder die Originalversion.
• Eigene Anpassungen vorhanden (z.B. eigene Farben in _variables.scss) → Datei behalten, ggf. neue Variablen aus dem Original ergänzen.

Gehe so der Reihe nach durch alle als Variante markierten Dateien. Je weniger Custom-Dateien übrig bleiben, desto einfacher fallen künftige Updates aus.

7. Bekannte SCSS-Stolperfallen

In Contao 5.7 wird der SCSS-Compiler in Version 2 verwendet. Dieser ist strenger als der bisherige Compiler. Häufige Probleme:

@extend mit Klassen ist nicht mehr erlaubt

Konstrukte wie @extend .button funktionieren nicht mehr. In LASR 5 wurde das durch Placeholder gelöst – z.B. %button-secondary, der dann mit @extend %button-secondary verwendet wird.

Wenn du eigene Anpassungen mit @extend einer Klasse hattest, musst du sie auf Placeholder umstellen oder die jeweilige Datei zurück auf das Original setzen, wenn die Anpassung nicht zwingend nötig war.

Typische betroffene Dateien sind components/_newsletter.scss und base/_links.scss. Im aktivierten Debug-Modus (im Backend oben rechts) erkennst du das schnell daran, dass nach Auswahl der neuen default.scss Fehlermeldungen wie „Selector ... not found" auftauchen.

Vendor-Prefixes

In der neuen Theme-Version sind viele -webkit--Prefixes entfernt worden. Wenn dein Diff im Theme Editor nur Vendor-Prefixe zeigt und sonst nichts, kannst du die Datei bedenkenlos auf das Original zurücksetzen.

8. Test im Frontend

Nachdem die Layouts umgestellt und die wichtigsten Diffs abgearbeitet sind, sollte das Frontend wieder fehlerfrei laden. Falls noch Fehler auftauchen:

1. Im Theme Editor die in der Fehlermeldung genannte Datei öffnen.
2. Diff anschauen.
3. Bei Versionsänderungen ggf. „Original wiederherstellen".
4. Bei eigenen Anpassungen die problematische Stelle (oft @extend) händisch umbauen.

Tipp: Änderungen im Theme Editor sind unmittelbar sichtbar. Du musst weder den Cache leeren, noch wie bisher unter Systemwartung die Option „Skript Cache umgehen" aktivieren – das übernimmt die Theme Toolbox automatisch.

9. Eigene .html5-Templates behandeln

Die Templates werden bei der Migration nicht automatisch aktualisiert oder entfernt. LASR 5 liefert nur noch Twig-Templates; deine bestehenden .html5-Templates im templates/-Ordner bleiben unangetastet und haben in Contao 5.7 weiterhin Vorrang vor dem Twig-Pendant aus dem Theme. Du musst dich also selbst darum kümmern.

Falls du keine Anpassungen an den Templates vorgenommen hast, lösche die vorhandenen .html5-Templates manuell aus dem templates/-Ordner. Dadurch werden automatisch die neuen Twig-Templates aus dem Theme verwendet.

Falls du die .html5-Templates angepasst hast, behältst du sie zunächst – musst aber die fest verdrahteten Asset-Pfade korrigieren. Sie zeigen noch auf das alte Verzeichnis files/theme/ und laufen ins Leere, sobald du es in Abschnitt 10 entfernst. Stelle die Pfade von /theme/… auf /assets/lasr-theme/… um. Betroffen sind u.a.:

• be_tinyMCE.html5 → /theme/css/tinymce.css
• js_accessibility.html5 → /theme/js/accessibility.js
• js_countup.html5 → /theme/js/count-up.js
• js_nav--mobile.html5 → /theme/js/navigation.js

Mittelfristig solltest du angepasste Templates ohnehin auf Twig umstellen – spätestens mit Blick auf Contao 6, wo die Unterstützung für .html5-Templates wegfällt. Anpassungen erfolgen ab LASR 5 über das Template Studio (Contao 5.7). Eine Einführung findest du in der offiziellen Contao-Dokumentation und mehr Details in der Anleitung LASR 5 Theme individualisieren.

Damit steht den Aufräumarbeiten nun nichts mehr im Wege.

10. Aufräumarbeiten

Nachdem die Theme-Migration abgeschlossen ist, solltest du alte Theme-Datei-Leichen unter files/theme entfernen. Dieser Schritt stellt auch gleichzeitig sicher, dass nicht doch noch ein Seitenlayout Dateien aus der alten Version importiert.

Checkliste

• Backup erstellt / Duplikat angelegt
• Contao auf 5.7 aktualisiert (inkl. Datenbank-Migration)
• LASR auf Version 5.x aktualisiert
• LASR 5 über Theme-Toolbox » Updates eingespielt
• Bestehende Anpassungen nach layout/custom/ kopiert
• Duplikate-Prüfung durchgeführt
• Seitenlayouts auf neue default.scss umgestellt
• Diff-Cleanup im Theme Editor abgeschlossen
• SCSS-Stolperfallen (@extend, Vendor-Prefixes) bereinigt
• Frontend in allen Seitentypen getestet
• Eigene .html5-Templates behandelt: nicht angepasste gelöscht (Twig greift automatisch), angepasste behalten und Asset-Pfade von /theme/… auf /assets/lasr-theme/… umgestellt
• Altes files/theme/-Verzeichnis entfernt (nach erfolgreichem Test)