DfCustomCodeManager — Vollständiger Leitfaden

DfCustomCodeManager liefert eine einfache Antwort auf ein universelles Problem in Shopware-Shops: wohin damit, wie versionieren und wie absichern das benutzerdefinierte CSS und JavaScript, das man immer wieder in einem Theme ergänzt? Das Plugin bietet einen Code-Editor direkt in der Administration, ein Container-System, das SCSS- oder JavaScript-Snippets gruppiert, und vor allem eine direkte Injektion in die Theme-Kompilierung über Shopwares native Events. Die Konsequenz: keine zusätzliche Datei ausgeliefert, keine zusätzliche HTTP-Anfrage für den Besucher, und Ihre SCSS-Snippets erben automatisch die Variablen und Mixins des aktiven Themes. Diese Anleitung deckt Installation, Konfiguration, das Erstellen von Containern und Snippets, die Theme-Kompilierung, die Versionshistorie, den Safe-Mode, die Vorlagen-Bibliothek, Import/Export und die Fehlerbehebung ab.

Installation

1. Laden Sie das Archiv DfCustomCodeManager-1.0.0.zip aus Ihrem DataFirefly-Konto herunter.
2. Installieren Sie es über Administration → Erweiterungen → Meine Erweiterungen → Erweiterung hochladen, oder entpacken Sie den Ordner DfCustomCodeManager nach custom/plugins/.
3. Führen Sie Installation und Aktivierung durch:

   bin/console plugin:refresh
   bin/console plugin:install --activate DfCustomCodeManager
   bin/console cache:clear

4. Bei der Installation erstellt das Plugin seine 4 Tabellen (df_ccm_container, df_ccm_container_sales_channel, df_ccm_snippet, df_ccm_snippet_version) und registriert seine Subscriber auf die Theme-Kompilierungs-Events.
5. Kompilieren Sie das Theme neu, damit es das Plugin berücksichtigt:

   bin/console theme:compile

Wo finden Sie das Plugin in der Administration

Nach der Aktivierung erscheint ein Custom Code Manager-Eintrag im Menü Kataloge der Administration (orangefarbenes Icon, Position 100). Das ist der zentrale Bildschirm: Liste der Container, Suche, Filter und die globalen Aktionen Importieren, Exportieren, Vorlagen und Theme kompilieren. Die gesamte Low-Level-Konfiguration (Safe-Mode, Minify, Banner) erfolgt über Erweiterungen → Meine Erweiterungen → DfCustomCodeManager → ⋯ → Konfigurieren.

Plugin-Konfiguration

Die Shopware-Plugin-Konfigurationskarte bietet drei einfache, aber wesentliche Schalter:

• Safe-Mode (DfCustomCodeManager.config.safeMode): standardmäßig deaktiviert. Wenn aktiviert, werden alle Container bei der nächsten Kompilierung ignoriert, als wären sie alle inaktiv. Das ist das unten beschriebene Sicherheitsnetz.
• JS minifizieren (DfCustomCodeManager.config.minifyJs): grundlegende Minifizierung des eingespeisten JavaScripts. Nützlich in Produktion, in Entwicklung deaktiviert lassen, um Snippets im kompilierten Bundle lesen zu können.
• Banner hinzufügen (DfCustomCodeManager.config.addBanner): fügt einen /* DataFirefly Custom Code Manager */-Kommentar am Anfang des eingespeisten Codes ein. Praktisch, um Ihre Snippets im kompilierten Bundle schnell zu finden.

Das mentale Modell: Container und Snippets

Das Plugin ist auf zwei Ebenen organisiert:

• Ein Container ist eine logische Gruppierung: Sommer-Promo 2026, GTM-Analytics, Dark-Mode-Opt-in, CTA-Button-A/B-Test… Jeder Container hat einen Namen, eine Beschreibung, eine Priorität, einen Aktiv-/Inaktiv-Schalter und einen Geltungsbereich nach Verkaufskanal.
• Ein Snippet ist eine Code-Einheit innerhalb eines Containers. Typ SCSS oder JavaScript, Name, Code, Priorität, Aktiv-/Inaktiv-Schalter, Markdown-Notizen und ein Schalter zum Aktivieren oder Deaktivieren der Theme-Variablen-Injektion.

Ein Container kann mehrere Snippets gemischter Typen enthalten. Praktisch, um logisch zusammengehörige Snippets zu gruppieren: zum Beispiel ein Dark-Mode-Opt-in-Container mit einem SCSS-Snippet für die Styles und einem JavaScript-Snippet für den Klassen-Toggle auf html.

Ihren ersten Container erstellen

1. Klicken Sie unter Kataloge → Custom Code Manager oben rechts auf Neuer Container.
2. Geben Sie ihm einen aussagekräftigen Namen (z. B. Sommer-Promo 2026 — Sticky Header & Badge).
3. Stellen Sie die Priorität ein (standardmäßig auf 0 belassen, erhöhen, wenn dieser Container später im Bundle eingespeist werden und damit andere Styles überschreiben soll).
4. (Optional) Aktivieren Sie Auf bestimmte Verkaufskanäle beschränken und wählen Sie einen oder mehrere Kanäle. Ist die Option deaktiviert, gilt der Container für alle Kanäle.
5. Geben Sie eine Beschreibung ein (interne Notizen, Kontext, zugehöriges Ticket) — sie wird nie ins Bundle eingespeist.
6. Speichern. Sie sind jetzt bereit, Snippets hinzuzufügen.

Ein SCSS- oder JavaScript-Snippet hinzufügen

In der Karte Code-Snippets der Container-Seite gibt es zwei Buttons: SCSS hinzufügen und JavaScript hinzufügen. Jedes hinzugefügte Snippet erscheint als Karte mit:

• Einem SCSS-Badge (info) oder JS-Badge (warning).
• Einem Namensfeld (nur im Bearbeitungsmodus sichtbar).
• Einem Aktiv-/Inaktiv-Schalter.
• Einem Syntax prüfen-Button (✓).
• Einem Historie-Button (Uhr) — ab dem ersten Speichern verfügbar.
• Einem Duplizieren-Button.
• Einem Entfernen-Button.
• Einem Code-Editor mit Syntaxhervorhebung passend zum Typ.
• Einem Notizen-Bereich in Markdown, um zu dokumentieren, was das Snippet tut.

Theme kompilieren

Ein gespeichertes Snippet ist noch nicht sichtbar auf der Storefront, solange das Theme nicht neu kompiliert wurde. Zwei Wege:

• Aus der Administration: Button Theme kompilieren (oben rechts in der Liste oder auf der Container-Seite). Eine Benachrichtigung bestätigt das Ende der Operation.
• Über die Kommandozeile:

  bin/console theme:compile

Bei der Kompilierung hört das Plugin auf drei Shopware-Events und speist Ihre Snippets dort ein:

• ThemeCompilerEnrichScssVariablesEvent — erfasst die SCSS-Variablen-Map des aktiven Themes. Das ist es, was Ihren SCSS-Snippets erlaubt, $sw-color-brand-primary, $font-family-base usw. zu verwenden.
• ThemeCompilerConcatenatedStylesEvent — hängt Ihr kompiliertes SCSS ans Ende des Haupt-Stylesheets an.
• ThemeCompilerConcatenatedScriptsEvent — hängt Ihr JavaScript ans Ende des Haupt-Skript-Bundles an.

Ergebnis: null zusätzliche HTTP-Anfragen für den Besucher, Ihr Code durchläuft die gesamte Shopware-Optimierungskette (Konkatenation, Minifizierung, Cache-Fingerprinting).

Vererbung von Theme-Variablen und Mixins

Standardmäßig profitiert jedes SCSS-Snippet von einer automatischen Präambel, die alle Variablen und Mixins enthält, die vom aktiven Theme und seinen Theme-Plugins exportiert werden. Sie können in einem Snippet schreiben:

.header {
    background: $sw-color-brand-primary;
    font-family: $font-family-base;
    transition: $transition-base;
}

…ohne etwas manuell zu importieren, genauso wie in einer Theme-SCSS-Datei. Wenn Sie aus einem bestimmten Grund (Variablenkonflikt, eigenständiges Snippet) diese Vererbung bei einem konkreten Snippet deaktivieren möchten, deaktivieren Sie den Schalter Theme-Variablen verfügbar im Footer der Snippet-Karte.

Multi-Channel-Geltungsbereich

In der Karte Geltungsbereich & Verkaufskanäle des Containers aktivieren Sie Auf bestimmte Verkaufskanäle beschränken und wählen die relevanten Kanäle aus. Der Container wird dann nur bei Theme-Kompilierungen für diese Kanäle eingespeist. Sehr nützlich für:

• Ein Promo-Banner, das einem sekundären Marken-Shop vorbehalten ist.
• Ein Tracking-Skript, das für einen Markt spezifisch ist.
• Ein A/B-Test auf einem einzelnen Kanal, um den Effekt zu messen.

Lade-Priorität

Die Priorität ist ein Integer (Standard 0), der die Injektionsreihenfolge im kompilierten Bundle steuert: je höher der Wert, desto später wird der Code eingespeist und kann daher mehr überschreiben, was davor kommt. Priorität existiert auf zwei Ebenen:

• Container-Ebene: Reihenfolge zwischen Containern.
• Snippet-Ebene: Reihenfolge zwischen Snippets innerhalb desselben Containers.

Die endgültige Reihenfolge ist: (Container-Priorität, Snippet-Priorität) aufsteigend. Einfacher Rat: standardmäßig alles auf 0 belassen, Priorität nur verwenden, wenn Sie wirklich etwas überschreiben müssen.

Versionshistorie

Bei jedem Speichern eines Snippets erstellt das Plugin automatisch eine Version in der Tabelle df_ccm_snippet_version. Die letzten 5 Versionen pro Snippet werden aufbewahrt (die älteste wird gelöscht, wenn das Limit erreicht ist). Um eine Version zu durchsuchen und wiederherzustellen:

1. Klicken Sie auf der Snippet-Karte auf das Historie-Symbol (Uhr).
2. Ein Modal öffnet sich mit der Liste der Versionen: Datum, Autor, Kommentar und Vorschau.
3. Klicken Sie rechts neben der gewünschten Version auf Wiederherstellen — der Snippet-Code wird sofort durch den der Version ersetzt. Eine neue Version wird erstellt, um die Wiederherstellung zu protokollieren.
4. Speichern Sie den Container und kompilieren Sie neu, um den Effekt zu sehen.

Safe-Mode: das Notfall-Sicherheitsnetz

Der Safe-Mode ist ein globaler Schalter in der Plugin-Konfiguration. Wenn aktiviert, sorgt er dafür, dass jeder Container bei der nächsten Kompilierung ignoriert wird, ohne dass irgendwelche Daten verändert werden. Typische Verwendung:

1. Ein schlecht getestetes Snippet macht um 22 Uhr etwas in der Produktion kaputt.
2. Gehen Sie zu Erweiterungen → Meine Erweiterungen → DfCustomCodeManager → ⋯ → Konfigurieren.
3. Schalten Sie den Safe-Mode-Schalter ein und speichern Sie.
4. Kompilieren Sie das Theme neu: bin/console theme:compile.
5. Die Storefront ist wieder im nativen Zustand (kein Snippet eingespeist). Sie können das fehlerhafte Snippet jetzt in Ruhe identifizieren und korrigieren.
6. Nach der Korrektur deaktivieren Sie den Safe-Mode und kompilieren erneut.

Vorlagen-Bibliothek

Der Button Vorlagen (aus der Container-Liste) öffnet eine Bibliothek mit 8 Containern, die mit einem Klick installierbar sind:

• Sticky-Header — Header, der sich beim Scrollen verwandelt (Klasse is-sticky ab einem Schwellenwert hinzugefügt).
• Nach-Oben-Button — Nach-Oben-Button, sichtbar ab einem bestimmten Scroll-Punkt.
• Cookie-Banner-Skin — Re-Skinning des nativen Cookie-Banners, um es an Ihre Markenrichtlinien anzupassen.
• Produkt-Badge — Neu — „Neu“-Abzeichen auf kürzlich erstellten Produkten.
• Gratisversand-Leiste — Gratisversand-Fortschrittsleiste am Seitenanfang.
• Abgerundete Buttons — abgerundete Buttons im gesamten Shop.
• GTM-DOM-Ready-Event — feuert ein benutzerdefiniertes Event, sobald das DOM bereit ist, um Ihre Data-Layer zu initialisieren.
• Fade-In beim Scrollen — progressives Einblenden der Elemente beim Scrollen.

Ein Klick auf Installieren erstellt den Container und seine Snippets in der Datenbank. Sie müssen nur noch das Theme neu kompilieren, um sie live zu sehen. Aus Vorlagen erstellte Container sind Container wie jeder andere: Sie können sie bearbeiten, erweitern, deaktivieren, löschen.

JSON-Import / -Export

Um Snippets zwischen Umgebungen (Dev, Staging, Produktion) oder zwischen Shops zu migrieren:

1. Export — wählen Sie einen oder mehrere Container in der Liste aus (Checkboxen), dann klicken Sie auf Exportieren. Eine JSON-Datei wird heruntergeladen, die alle ausgewählten Container mit ihren Snippets, ihrer Priorität, ihren Notizen enthält — und die Formatversionsnummer (EXPORT_VERSION = 1) zur Rückwärtskompatibilität.
2. Import — in der Zielumgebung klicken Sie auf Importieren und wählen die JSON-Datei aus. Container und Snippets werden identisch neu erstellt.

Syntaxvalidierung

Der ✓-Button Syntax prüfen auf jeder Snippet-Karte löst eine serverseitige Validierung aus, ohne etwas zu speichern. Je nach Typ:

• SCSS — das Plugin startet eine Trockenkompilierung via scssphp/scssphp mit der eingespeisten Theme-Variablen-Präambel. Wenn die Kompilierung durchläuft, ist das Snippet gültig. Andernfalls werden die Fehler in einem Fehlerbereich auf der Karte gemeldet (Zeilennummer, Nachricht).
• JavaScript — das Plugin bereinigt den Code von Strings und Kommentaren und überprüft dann das Gleichgewicht der geschweiften Klammern {}, runden Klammern () und eckigen Klammern []. Diese Prüfung ersetzt keinen echten ECMAScript-Parser, fängt aber 90 % der Copy-Paste-Fehler ab (vergessene Klammer, nicht geschlossener String). Für mehr Sicherheit validieren Sie Ihr JavaScript vor dem Einfügen in einem dedizierten Werkzeug.

Technische Architektur

Für Entwickler, die das Plugin verstehen oder erweitern möchten:

• Root-PHP-Namespace: DataFirefly (Sub-Namespace: CustomCodeManager, Klassen unter src/).
• Plugin-Klasse: DfCustomCodeManager (erweitert ShopwareCoreFrameworkPlugin).
• SystemConfig-Präfix: DfCustomCodeManager.config.*.
• Tabellen: df_ccm_container, df_ccm_container_sales_channel, df_ccm_snippet, df_ccm_snippet_version.
• Migrationen: Migration1779580800CreateCcmContainerTable, Migration1779580801CreateCcmSnippetTable, Migration1779580802CreateCcmSnippetVersionTable.
• Services: CodeCompiler (Orchestrierung + Cache), SnippetExporter (JSON-Import/Export), SnippetValidator (Syntaxvalidierung), VersionTracker (Snapshot + Restore + Trim).
• Subscriber: ThemeCompilerSubscriber (die 3 Kompilierungs-Events), SnippetWrittenSubscriber (automatischer Snapshot beim Schreiben).
• Private API-Routen unter /api/_action/df-ccm/ (Scope api): validate, export, import, restore-version, recompile, presets.

Alle Service-Deklarationen sind in services.xml explizit (kein Autowiring), um an den DataFirefly-Konventionen ausgerichtet zu bleiben.

Erweiterung des Administrations-Moduls

Das Administrations-Modul ist kompiliert und unter Resources/public/administration/js/df-custom-code-manager.js abgelegt. Es ist im ZIP vorkompiliert und benötigt keinen lokalen Build. Um es zu erweitern, finden Sie die Komponenten (df-ccm-list, df-ccm-detail, df-ccm-snippet-card, df-ccm-code-field, df-ccm-preset-modal, df-ccm-version-modal) und passen sie über das Standard-Override-System von Shopware an (Component.override).

FAQ und Fehlerbehebung

Meine Snippets erscheinen nicht auf der Storefront. Haben Sie das Theme neu kompiliert? Solange theme:compile nach einer Änderung nicht gelaufen ist, ändert sich nichts. Überprüfen Sie auch, ob der Container und das Snippet aktiv sind, ob der relevante Verkaufskanal im Geltungsbereich ist (wenn der Geltungsbereich eingeschränkt ist), und ob der Safe-Mode nicht aktiviert ist.

SCSS-Kompilierungsfehler in der Konsole nach theme:compile. Meistens ist es eine Theme-Variable, die nicht existiert (Tippfehler), oder ein SCSS-Snippet, das einen Block öffnet, ohne ihn zu schließen. Deaktivieren Sie das fehlerhafte Snippet, kompilieren Sie neu zur Bestätigung, dann korrigieren Sie in Ruhe. Die Syntaxvalidierung auf der Snippet-Karte fängt die meisten dieser Fälle vor dem Speichern ab.

Das Custom-Code-Manager-Menü erscheint nicht in der Administration. Führen Sie bin/console assets:install && bin/console cache:clear aus und laden Sie die Administration mit Strg+Shift+R neu. Das Modul befindet sich unter der Gruppe Kataloge.

Der Code-Editor zeigt ein Textarea ohne Syntaxhervorhebung an. Das ist der Fallback, wenn weder mt-code-editor (6.7) noch sw-code-editor (6.6) verfügbar ist. Überprüfen Sie Ihre Shopware-Version und ob das Administrations-Modul ordnungsgemäß geladen ist.

Ich möchte alle Snippets vorübergehend deaktivieren, ohne etwas zu löschen. Das ist genau der Safe-Mode. Schalter in der Plugin-Konfiguration, Neukompilierung, fertig.

Der „Theme kompilieren“-Button dreht endlos. Überprüfen Sie die Shopware-Logs. Die Kompilierung kann bei einem großen Theme dauern; bei einem echten Stillstand liegt die übliche Ursache in einem SCSS-Snippet, das in einer Schleife steckt oder eine unbekannte Variable enthält. Aktivieren Sie den Safe-Mode, kompilieren Sie neu, dann reaktivieren Sie die Snippets einzeln, um den Übeltäter zu identifizieren.

Mein JavaScript-Snippet wird nicht ausgelöst. Denken Sie daran, dass der eingespeiste Code im globalen Bundle ausgeführt wird, also in einem anderen Kontext als reguläre Shopware-JavaScript-Plugins. Um mit den Storefront-JavaScript-Plugins zu interagieren, hören Sie eher auf document.addEventListener('DOMContentLoaded', …) oder die globalen Events, die die Storefront ausgibt.

Was passiert bei der Deinstallation? Bei plugin:uninstall zeigt Shopware das Standard-Kontrollkästchen Benutzerdaten beibehalten an. Wenn es deaktiviert ist, löscht das Plugin seine 4 Tabellen und alle zugehörigen Daten (Container, Snippets, Versionen, Kanal-Verknüpfungen). Wenn es aktiviert ist, bleiben die Tabellen erhalten und Sie finden Ihre Snippets wieder, wenn Sie das Plugin später neu installieren.