Von SIRIUS 2 auf SIRIUS 3 migrieren

SIRIUS 3 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 SIRIUS-3-ZIP-Datei aus dem Club-Bereich liegt dir vor

Überblick der Änderungen

Bereich SIRIUS 2.x SIRIUS 3.x
Theme-Paket Metapaket (nur Abhängigkeiten) Vollwertiges Contao-Bundle, liefert die Templates aus
Templates HTML5-Templates (*.html5) im Projekt Twig-Templates (*.html.twig) aus dem Bundle
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.2 (Theme Editor und Live-Editor)
Slider-Stopp ce_sliderStop Entfällt – verschachtelte Inhaltselemente (ab Contao 5.3)
Inline-JavaScript In den Templates eingebettet Als Datei im Theme (layout/sirius-theme/js/)
Skript-Cache umgehen Notwendig Nicht mehr nötig (übernimmt die Theme Toolbox)
Contao 5.1 bis 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.

2. SIRIUS 3 installieren

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

Nach dem Update findest du im Backend einen 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 Werkzeug zur Verwaltung der Theme-Dateien
  • Updates – hier werden ab sofort Theme-Updates eingespielt

3. SIRIUS 3 über den Updates-Menüpunkt einspielen

Wechsle in das Backend zu Theme-Toolbox » Updates und lade dort die SIRIUS-3-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/sirius-theme/ kopiert (das ist die neue, schreibgeschützte „Originalversion" des Themes).
  2. SIRIUS 3 liefert seine Templates selbst als Twig aus dem Bundle. 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 SIRIUS 3 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/_links.scss und components/_card.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.

_updates.scss aus früheren Versionen

Falls du in einem früheren SIRIUS-Update Anweisungen aus der _updates.scss in dein Theme übernommen oder die Datei über die default.scss importiert hast, prüfe diese Stellen. Die Anweisungen sind in SIRIUS 3 bereits in den regulären Dateien enthalten – ein zusätzlicher Import führt zu doppelten Regeln.

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.

Prüfe dabei auch den Dark Mode: Ist im Betriebssystem das dunkle Farbschema aktiv, greift der Block @media (prefers-color-scheme: dark) am Ende der _variables.scss. Eigene Farbänderungen müssen dort ggf. nachgezogen werden.

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 – der Compiler der Theme Toolbox erkennt Änderungen automatisch.

9. Eigene .html5-Templates behandeln

Die Templates werden bei der Migration nicht automatisch aktualisiert oder entfernt. SIRIUS 3 liefert nur noch Twig-Templates aus dem Bundle; 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.

SIRIUS 3 bringt diese Templates als Twig mit:

  • mod_article.html.twig
  • be_tinyMCE.html.twig
  • j_colorbox.html.twig
  • js_nav--mobile.html.twig
  • js_animate-article.html.twig

Diese Templates kannst du löschen – sie werden in SIRIUS 3 nicht mehr benötigt:

  • ce_sliderStop.html5 – der Slider-Stopp entfällt, seit Contao 5.3 gibt es dafür die verschachtelten Inhaltselemente.

Bei den übrigen gilt: Hast du an einem Template keine Anpassungen vorgenommen, lösche es einfach – dann greift automatisch das neue Twig-Template aus dem Bundle, das die Assets bereits korrekt referenziert.

Hast du ein Template angepasst und möchtest es behalten, musst du die Asset-Pfade korrigieren. Sie zeigen noch auf das alte Verzeichnis files/theme/ und laufen ins Leere, sobald du es in Abschnitt 10 entfernst. Das betrifft insbesondere be_tinyMCE, js_nav--mobile und js_animate-article, deren JavaScript in SIRIUS 3 nicht mehr inline im Template steht, sondern als Datei unter layout/sirius-theme/js/ liegt.

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 SIRIUS 3 über das Template Studio (Contao 5.7). Eine Einführung findest du in der offiziellen Contao-Dokumentation und mehr Details in der Anleitung SIRIUS 3 Theme individualisieren.

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.

11. Live-Editor aktivieren (optional)

Wenn du das Theme im Zuge der Migration ohnehin neu gestalten möchtest, aktiviere den neuen Live-Editor: In der Contao-Systemwartung findest du den Schalter „Frontend-Editor anzeigen" (standardmäßig aus). Danach erscheint für eingeloggte Backend-Benutzer:innen im Frontend die Dock-Pille „Theme bearbeiten".

Wie er funktioniert, steht in SIRIUS 3 Theme individualisieren.

Checkliste

  • Backup erstellt / Duplikat angelegt
  • Contao auf 5.7 aktualisiert (inkl. Datenbank-Migration)
  • SIRIUS auf Version 3.x aktualisiert
  • SIRIUS 3 ü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, _updates.scss) bereinigt
  • Frontend in allen Seitentypen getestet – hell und dunkel (Dark Mode)
  • Eigene .html5-Templates behandelt: ce_sliderStop gelöscht, unveränderte Templates gelöscht, angepasste behalten und Asset-Pfade korrigiert
  • Altes files/theme/-Verzeichnis entfernt (nach erfolgreichem Test)
  • sirius
  • migration
  • update
  • twig
  • theme-editor
  • live-editor
  • theme-toolbox

Zur Übersicht