Ein Theme lokal entwickeln und debuggen

Die Entwicklungsschleife für ein hostware-Theme lautet: SCSS-Watcher starten, Twig oder SCSS bearbeiten, Storefront aktualisieren. Cache-Probleme, lautlose Überschreibungen und falsche Template-Pfade decken ungefähr alle Fragen nach dem Muster „Warum wird meine Änderung nicht angezeigt?“ ab, und für jedes davon gibt es eine schnelle Prüfung.

SCSS-Watcher laufen lassen

Das CSS des Themes pro Sales Channel wird über die Speichern-Schaltfläche in der Administration kompiliert, nicht durch das Bearbeiten von Dateien. Lass den Watcher während deiner gesamten Sitzung in einem Terminal laufen; dann wird er bei jeder Änderung an einer SCSS-Datei neu erstellen:

php artisan theme:watch                # poll every 1s
php artisan theme:watch --interval=2   # slower cadence
php artisan theme:watch --initial      # compile every sales channel once on startup

Der Watcher durchsucht den public/css/-Baum jedes installierten Themes und kompiliert bei einer Dateiänderung jeden Sales Channel neu, der das betroffene Theme verwendet. Ein Syntaxfehler wird in der Ausgabe des Watchers angezeigt.

Caches leeren, wenn Twig-Änderungen nicht übernommen werden

Änderungen an Twig-Templates sollten bei der nächsten Anfrage übernommen werden. Wenn das nicht passiert, ist der Twig-Cache veraltet:

• UI: Administration > Einstellungen > Debug enthält eine Schaltfläche „Cache leeren“.

• CLI: php artisan twig:clean.

Das Hinzufügen einer neuen Datei unter resources/views/ erfordert gelegentlich auch das Leeren des Theme-Caches. Führe php artisan theme:cache aus.

Herausfinden, welches Template tatsächlich gerendert wird

Der Template-Resolver durchsucht Theme -> Module -> Core. Wenn deine Überschreibung nicht greift, befindet sich die Datei entweder am falschen Pfad oder ein Modul hat Vorrang. Es gibt zwei Möglichkeiten, dies nachzuverfolgen:

1. Durchsuche den Quellbaum nach einer Klasse oder einem Attribut, das du im gerenderten HTML siehst. Führe grep -rn "class-name" resources/views custom/themes custom/modules aus. Jeder Treffer ist ein Kandidat; der tatsächlich verwendete Treffer steht in der Prioritätsreihenfolge an höchster Stelle.

2. Aktiviere die Debug Bar (Administration > Einstellungen > Debug). Der Tab „Views“ listet jedes bei der aktuellen Anfrage gerenderte Twig-Template mit seinem vollständigen absoluten Pfad auf. Wenn die Datei deines Themes nicht in der Liste enthalten ist, die Datei des Core aber schon, ist der Pfad deiner Überschreibung falsch.

Häufige Fehler

Fast jedes Problem nach dem Muster „Die Änderung wird nicht angezeigt“ ist auf einen dieser Fehler zurückzuführen.

• Falscher Pfad bei der Überschreibung. Deine Überschreibung muss unter resources/views/storefront/ genau am selben relativen Pfad liegen wie das Core-Template, das sie ersetzt. Ein Ordner zu viel oder zu wenig (storefront/component/product statt storefront/components/product) führt dazu, dass der Resolver sie nie findet.

• Einen äußeren Block überschreiben. Wenn du einen Block neu deklarierst, der innere Blöcke enthält, sind diese inneren Blöcke verschwunden, sofern du nicht {{ parent() }} aufrufst oder sie anhand ihres Namens einbindest. Überschreibe den passenden innersten Block, nicht seinen übergeordneten Block.

• Fehlendes !default in SCSS. Variablen mit Markenbezug, die nicht !default verwenden, ignorieren das Branding-Formular der Administration, weil deine Zeile den Wert erneut zuweist, den die Kompilierungspipeline bereits vorangestellt hatte.

• Asset-Pfad ohne Vendor-Segment. /themes/mytheme/... liefert immer 404. Verwende /themes/<vendor>/<name>/....

• Twig erweitert einen einfachen Pfad. {% hw_extends 'home.twig' %} wird vom Resolver abgelehnt. Verwende immer die Namespace-Form: storefront::home.twig.

• Namespace des CMS-Elements stimmt nicht überein. Der PHP-Namespace in einer Datei unter Cms/Elements/*.php muss exakt custom\themes\<vendor>\<name-lowercased>\Cms\Elements lauten. Bei jedem Tippfehler wird die Klasse bei der Erkennung stillschweigend übersprungen.

Über mehrere Sales Channels hinweg testen

Das Theme-CSS gilt pro Sales Channel. Eine Kompilierung für den falschen Channel aktualisiert daher nicht den Channel, den du gerade ansiehst. Wenn ein Sales Channel deine Änderungen nicht übernimmt, überprüfe sein zugewiesenes Theme (Administration > Sales Channels > Theme). Der Watcher kompiliert nur Channels neu, die derzeit das Theme verwenden, das du bearbeitest.