DfCustomCodeManager: complete gids

DfCustomCodeManager biedt een eenvoudig antwoord op een universeel probleem van Shopware-shops: waar zet je de eigen CSS en JavaScript die je uiteindelijk toch aan een thema toevoegt, hoe versioneer je die en hoe beveilig je die? De plugin levert een code-editor die in de administration is geïntegreerd, een systeem van containers die SCSS- of JavaScript-snippets bundelen, en vooral een rechtstreekse injectie in de compilatie van het thema via de native events van Shopware. Het gevolg: geen extra bestand dat wordt geserveerd, geen extra HTTP-aanvraag voor de bezoeker, en uw SCSS-snippets erven automatisch de variabelen en mixins van het actieve thema. Deze gids behandelt de installatie, de configuratie, het aanmaken van containers en snippets, de compilatie van het thema, de versiegeschiedenis, de safe mode, de presetbibliotheek, import en export, en de probleemoplossing.

Installatie

1. Download het archief DfCustomCodeManager-1.0.0.zip vanuit uw DataFirefly-omgeving.
2. Installeer het via Administration → Extensies → Mijn extensies → Extensie uploaden, of pak de map DfCustomCodeManager uit in custom/plugins/.
3. Start de installatie en de activering:

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

4. Bij de installatie maakt de plugin zijn 4 tabellen aan (df_ccm_container, df_ccm_container_sales_channel, df_ccm_snippet, df_ccm_snippet_version) en registreert hij zijn subscribers op de events van de themacompilatie.
5. Compileer het thema opnieuw zodat het de plugin meeneemt:

   bin/console theme:compile

Waar u de plugin vindt in de administration

Na de activering verschijnt er een item Custom Code Manager in het menu Catalogi van de administration (oranje icoon, positie 100). Dat is het centrale scherm: lijst met containers, zoekfunctie, filters en de globale acties Importeren, Exporteren, Presets en Thema compileren. Alle configuratie op laag niveau (safe mode, minify, banner) gebeurt via Extensies → Mijn extensies → DfCustomCodeManager → ⋯ → Configureren.

Configuratie van de plugin

De configuratiekaart van de Shopware-plugin biedt drie eenvoudige maar essentiële schakelaars:

• Safe mode (DfCustomCodeManager.config.safeMode): standaard uitgeschakeld. Ingeschakeld worden alle containers bij de volgende compilatie genegeerd, alsof ze allemaal inactief zijn. Dit is het vangnet dat hieronder wordt beschreven.
• Minify JS (DfCustomCodeManager.config.minifyJs): basisminificatie van de geïnjecteerde JavaScript. Nuttig in productie, laat het in ontwikkeling uit staan zodat u de snippets in de gecompileerde bundel kunt lezen.
• Een banner toevoegen (DfCustomCodeManager.config.addBanner): voegt aan het begin van de geïnjecteerde code een commentaar /* DataFirefly Custom Code Manager */ toe. Handig om uw snippets snel in de gecompileerde bundel terug te vinden.

Het denkmodel: containers en snippets

De plugin is op twee niveaus georganiseerd:

• Een container is een logische groepering: Zomerpromo 2026, GTM analytics, Dark mode opt-in, A/B-test CTA-knop, enzovoort. Elke container heeft een naam, een beschrijving, een prioriteit, een actief/inactief-schakelaar en een bereik per verkoopkanaal.
• Een snippet is een code-eenheid binnen een container. Type SCSS of JavaScript, naam, code, prioriteit, actief/inactief-schakelaar, notities in Markdown, en een schakelaar om het injecteren van de themavariabelen al dan niet te activeren.

Een container kan meerdere snippets van gemengde types bevatten. Dat is nuttig om snippets die bij elkaar horen logisch te bundelen: bijvoorbeeld een container Dark mode opt-in met een SCSS-snippet voor de stijlen en een JavaScript-snippet voor de klasseschakelaar op html.

Uw eerste container aanmaken

1. Klik vanuit Catalogi → Custom Code Manager rechtsboven op Nieuwe container.
2. Geef hem een sprekende naam (bijvoorbeeld Zomerpromo 2026, sticky header en badge).
3. Stel de prioriteit in (laat 0 als standaard staan, verhoog de waarde als u wilt dat deze container later in de bundel wordt geïnjecteerd en dus andere stijlen overschrijft).
4. (Optioneel) Activeer Beperken tot verkoopkanalen en selecteer een of meer kanalen. Staat de optie uit, dan geldt de container voor alle kanalen.
5. Vul een beschrijving in (interne notities, context, gekoppeld ticket); die wordt nooit in de bundel geïnjecteerd.
6. Sla op. U kunt nu snippets toevoegen.

Een SCSS- of JavaScript-snippet toevoegen

Op de kaart Code-snippets van de containerpagina staan twee knoppen: SCSS toevoegen en JavaScript toevoegen. Elk toegevoegd snippet verschijnt als een kaart met:

• Een badge SCSS (info) of JS (warning).
• Een naamveld (alleen zichtbaar tijdens het bewerken).
• Een actief/inactief-schakelaar.
• Een knop Syntaxis valideren (✓).
• Een knop Geschiedenis (klok), beschikbaar vanaf de eerste opslag.
• Een knop Dupliceren.
• Een knop Verwijderen.
• Een code-editor met syntaxiskleuring die bij het type past.
• Een zone Notities in Markdown om te documenteren wat het snippet doet.

Het thema compileren

Een opgeslagen snippet is nog niet zichtbaar op de storefront zolang het thema niet opnieuw is gecompileerd. Dat kan op twee manieren:

• Vanuit de administration, met de knop Thema compileren (rechtsboven in de lijst of op de containerpagina). Een melding bevestigt het einde van de bewerking.
• Vanaf de commandoregel:

  bin/console theme:compile

Bij de compilatie luistert de plugin naar drie Shopware-events en injecteert daar uw snippets:

• ThemeCompilerEnrichScssVariablesEvent: legt de map met SCSS-variabelen van het actieve thema vast. Daardoor kunnen uw SCSS-snippets $sw-color-brand-primary, $font-family-base en dergelijke gebruiken.
• ThemeCompilerConcatenatedStylesEvent: voegt uw gecompileerde SCSS achteraan de hoofdstylesheet toe.
• ThemeCompilerConcatenatedScriptsEvent: voegt uw JavaScript achteraan de hoofdscriptbundel toe.

Resultaat: nul extra HTTP-aanvragen voor de bezoeker, en uw code doorloopt de volledige optimalisatieketen van Shopware (samenvoeging, minificatie, cachefingerprinting).

Overerving van variabelen en mixins van het thema

Standaard krijgt elk SCSS-snippet een automatische preambule met alle variabelen en mixins die het actieve thema en zijn themaplugins beschikbaar stellen. U kunt dus in een snippet schrijven:

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

zonder handmatig iets te importeren, precies zoals in een SCSS-bestand van het thema. Wilt u om een bepaalde reden (variabeleconflict, zelfstandig snippet) deze overerving voor één specifiek snippet uitschakelen, vink dan de schakelaar Themavariabelen beschikbaar in de voettekst van de snippetkaart uit.

Bereik over meerdere kanalen

Activeer op de kaart Bereik en kanalen van de container de optie Beperken tot verkoopkanalen en selecteer de betreffende kanalen. De container wordt dan alleen geïnjecteerd in de themacompilaties voor die kanalen. Erg handig voor:

• Een promobanner die alleen voor een tweede merkshop bedoeld is.
• Een trackingscript dat specifiek is voor één markt.
• Een A/B-test op één enkel kanaal om de impact te meten.

Laadprioriteit

De prioriteit is een geheel getal (standaard 0) dat de injectievolgorde in de gecompileerde bundel bepaalt: hoe hoger de waarde, hoe later de code wordt geïnjecteerd en hoe meer die dus kan overschrijven wat eraan voorafgaat. De prioriteit bestaat op twee niveaus:

• Op containerniveau: de volgorde tussen containers.
• Op snippetniveau: de volgorde tussen snippets binnen dezelfde container.

De uiteindelijke volgorde is (containerprioriteit, snippetprioriteit) in oplopende volgorde. Eenvoudig advies: laat standaard alles op 0 staan en gebruik de prioriteit alleen als u expliciet iets moet overschrijven.

Versiegeschiedenis

Bij elke opslag van een snippet maakt de plugin automatisch een versie aan in de tabel df_ccm_snippet_version. De laatste 5 versies per snippet worden bewaard (de oudste wordt verwijderd zodra de drempel is bereikt). Om een versie te raadplegen en te herstellen:

1. Klik op de snippetkaart op het pictogram Geschiedenis (klok).
2. Er opent een venster met de lijst met versies, datum, auteur, commentaar en voorbeeld.
3. Klik rechts van de gewenste versie op Herstellen; de code van het snippet wordt direct vervangen door die van de versie. Er wordt een nieuwe versie aangemaakt om het herstel vast te leggen.
4. Sla de container op en compileer opnieuw om het effect te zien.

Safe mode: het noodvangnet

De safe mode is een globale schakelaar in de configuratie van de plugin. Ingeschakeld zorgt hij ervoor dat alle containers bij de volgende compilatie worden genegeerd, zonder ook maar één gegeven te wijzigen. Typisch gebruik:

1. Een slecht getest snippet breekt om 22 uur iets in productie.
2. Ga naar Extensies → Mijn extensies → DfCustomCodeManager → ⋯ → Configureren.
3. Zet de schakelaar Safe mode aan en sla op.
4. Compileer het thema opnieuw: bin/console theme:compile.
5. De storefront keert terug naar zijn oorspronkelijke staat (zonder enig geïnjecteerd snippet). U kunt nu in alle rust het foutieve snippet opsporen en corrigeren.
6. Zodra het is gecorrigeerd, schakelt u de safe mode uit en compileert u opnieuw.

Presetbibliotheek

De knop Presets (vanuit de containerlijst) opent een bibliotheek met 8 containers die met één klik te installeren zijn:

• Sticky header: header die bij het scrollen verandert (klasse is-sticky toegevoegd voorbij een drempel).
• Back to top: knop terug naar boven, zichtbaar vanaf een bepaalde scrollpositie.
• Cookie banner skin: herstyling van de native cookiebanner zodat die bij uw huisstijl past.
• Productbadge Nieuw: badge “Nieuw” op recent aangemaakte producten.
• Free shipping bar: voortgangsbalk voor gratis verzending bovenaan de pagina.
• Rounded buttons: afgeronde knoppen in de hele shop.
• GTM DOM-ready event: vuurt een eigen event af zodra de DOM klaar is, om uw data layers te starten.
• Fade-in on scroll: elementen verschijnen geleidelijk tijdens het scrollen.

Klikken op Installeren maakt de container en zijn snippets in de database aan. Daarna hoeft u alleen nog het thema opnieuw te compileren om ze live te zien. Containers die op basis van een preset zijn aangemaakt, zijn gewone containers: u kunt ze bewerken, uitbreiden, uitschakelen of verwijderen.

Import en export in JSON

Om snippets tussen omgevingen (dev, staging, productie) of tussen shops te migreren:

1. Export: selecteer een of meer containers in de lijst (selectievakjes) en klik daarna op Exporteren. Er wordt een JSON-bestand gedownload met alle geselecteerde containers, hun snippets, hun prioriteit en hun notities, plus het versienummer van het formaat (EXPORT_VERSION = 1) voor achterwaartse compatibiliteit.
2. Import: klik op de doelomgeving op Importeren en selecteer het JSON-bestand. De containers en snippets worden identiek opnieuw aangemaakt.

Syntaxisvalidatie

De knop ✓ Syntaxis valideren op elke snippetkaart start een validatie aan serverzijde zonder iets op te slaan. Afhankelijk van het type:

• SCSS: de plugin voert een proefcompilatie uit via scssphp/scssphp met de preambule van de themavariabelen. Slaagt de compilatie, dan is het snippet geldig. Anders worden de fouten in een foutzone op de kaart getoond (regelnummer, melding).
• JavaScript: de plugin ontdoet de code van tekenreeksen en commentaar en controleert daarna de balans van accolades {}, haakjes () en blokhaken []. Deze controle vervangt geen echte ECMAScript-parser, maar vangt 90 % van de knip-en-plakfouten op (vergeten accolade, slecht afgesloten tekenreeks). Voor meer zekerheid valideert u uw JavaScript in een specifiek hulpmiddel voordat u het plakt.

Technische architectuur

Voor ontwikkelaars die de plugin willen begrijpen of uitbreiden:

• PHP-hoofdnamespace: DataFirefly (subnamespace: CustomCodeManager, klassen onder src/).
• Pluginklasse: DfCustomCodeManager (breidt ShopwareCoreFrameworkPlugin uit).
• SystemConfig-voorvoegsel: DfCustomCodeManager.config.*.
• Tabellen: df_ccm_container, df_ccm_container_sales_channel, df_ccm_snippet, df_ccm_snippet_version.
• Migraties: Migration1779580800CreateCcmContainerTable, Migration1779580801CreateCcmSnippetTable, Migration1779580802CreateCcmSnippetVersionTable.
• Services: CodeCompiler (orkestratie en cache), SnippetExporter (JSON-import en -export), SnippetValidator (syntaxisvalidatie), VersionTracker (snapshot, herstel en opschoning).
• Subscribers: ThemeCompilerSubscriber (de 3 compilatie-events), SnippetWrittenSubscriber (automatische snapshot bij schrijven).
• Private API-routes onder /api/_action/df-ccm/ (scope api): validate, export, import, restore-version, recompile, presets.

Alle servicedeclaraties staan expliciet in services.xml (geen autowiring), in lijn met de conventies van DataFirefly.

De administratiemodule uitbreiden

De administratiemodule wordt gecompileerd en geplaatst onder Resources/public/administration/js/df-custom-code-manager.js. Hij is vooraf gecompileerd in de ZIP en vereist geen lokale build. Om hem uit te breiden, opent u de componenten (df-ccm-list, df-ccm-detail, df-ccm-snippet-card, df-ccm-code-field, df-ccm-preset-modal, df-ccm-version-modal) en past u ze aan via het standaard override-systeem van Shopware (Component.override).

FAQ en probleemoplossing

Mijn snippets verschijnen niet op de storefront. Hebt u het thema opnieuw gecompileerd? Zolang theme:compile na een wijziging niet is gedraaid, verandert er niets. Controleer ook of de container en het snippet actief zijn, of het betreffende verkoopkanaal binnen het bereik valt (als het bereik beperkt is), en of de safe mode niet is ingeschakeld.

SCSS-compilatiefout in de console na theme:compile. Meestal gaat het om een themavariabele die niet bestaat (typefout) of een SCSS-snippet dat een blok opent zonder het te sluiten. Schakel het verdachte snippet uit, compileer opnieuw ter bevestiging en corrigeer daarna in alle rust. De syntaxisvalidatie op de snippetkaart vangt de meeste van deze gevallen al vóór het opslaan op.

Het menu Custom Code Manager verschijnt niet in de admin. Voer bin/console assets:install && bin/console cache:clear uit en herlaad de administration met Ctrl+Shift+R. De module zit in de groep Catalogi.

De code-editor toont een textarea zonder kleuring. Dat is de terugvaloptie wanneer noch mt-code-editor (6.7) noch sw-code-editor (6.6) beschikbaar is. Controleer uw Shopware-versie en of de administratiemodule daadwerkelijk is geladen.

Ik wil alle snippets tijdelijk uitschakelen zonder iets te verwijderen. Daarvoor is de safe mode. Schakelaar in de pluginconfiguratie, opnieuw compileren, klaar.

De knop “Thema compileren” blijft eindeloos draaien. Controleer de Shopware-logs. De compilatie kan bij een groot thema tijd kosten; bij een echte blokkade is de gebruikelijke oorzaak een SCSS-snippet dat in een lus loopt of een onbekende variabele bevat. Zet de safe mode aan, compileer opnieuw en activeer daarna de snippets één voor één om de boosdoener te vinden.

Mijn JavaScript-snippet wordt niet uitgevoerd. Vergeet niet dat de geïnjecteerde code in de globale bundel wordt uitgevoerd, dus in een andere context dan die van de klassieke Shopware-plugins. Om met de JavaScript-plugins van de storefront te communiceren, luistert u beter naar document.addEventListener('DOMContentLoaded', …) of naar de globale events die de storefront uitzendt.

Wat gebeurt er bij het verwijderen? Bij plugin:uninstall toont Shopware het standaard selectievakje Gebruikersgegevens behouden. Is het uitgevinkt, dan verwijdert de plugin zijn 4 tabellen en alle bijbehorende gegevens (containers, snippets, versies, kanaalkoppelingen). Is het aangevinkt, dan blijven de tabellen bestaan en vindt u uw snippets terug als u de plugin later opnieuw installeert.