Plugin-Integration

Diese Seite beschreibt, wie eigene Shopware-Plugins kompatibel mit dem Guppy-Theme entwickelt werden, ohne die Vererbungs-Kette zu brechen oder spätere Updates des Themes zu blockieren.

• Goldene Regeln
• Composer-Setup
• SCSS-Integration
  • Eigene Styles via Theme-Pipeline
  • Funktionen und Mixins des Themes nutzen
• Twig-Integration
  • Templates überschreiben
  • Theme-Konfig in Plugin-Templates
  • Eigene Twig-Extension registrieren
• Storefront-JS-Integration
  • Auf Splide-Slider aufsetzen
• CMS-Integration
• Asset-Pipeline
• Migrationen und Custom-Fields
• Versions-Kompatibilität
• Validierung
• Verwandt

Goldene Regeln

Regel	Warum
Niemals DmfGuppyTheme direkt patchen	Updates werden unmöglich. Eigener Code gehört in ein eigenes Plugin oder Child-Theme.
Twig immer mit sw_extends überschreiben	sw_replace bricht die Inheritance-Kette für nachfolgende Plugins.
SCSS via overrides.scss und base.scss	Direkter Zugriff auf Bootstrap-Build wäre brüchig.
Variablen mit !default markieren	Damit Child-Themes weiter überschreiben können.
theme.json-Inheritance nicht verändern	["@Storefront", "@DmfGuppyTheme"] ist fixe Reihenfolge.

Composer-Setup

Eigenes Plugin als reguläres shopware-platform-plugin paketieren:

{
  "name": "acme/guppy-extension",
  "type": "shopware-platform-plugin",
  "license": "proprietary",
  "require": {
    "shopware/core": "~6.7.0",
    "dmf/sw6-guppy-theme": "^2.0"
  },
  "autoload": {
    "psr-4": {
      "Acme\\GuppyExtension\\": "src/"
    }
  },
  "extra": {
    "shopware-plugin-class": "Acme\\GuppyExtension\\AcmeGuppyExtension"
  }
}

Lokales Path-Repo

Wer im Monorepo entwickelt, hängt das Plugin per Composer-path-Repository ein, siehe Lokale Einrichtung.

SCSS-Integration

Eigene Styles via Theme-Pipeline

Plugins, die als shopware-storefront-plugin markiert sind und einen @Plugins-Eintrag im Theme bekommen, werden automatisch in der Compile-Reihenfolge berücksichtigt:

overrides.scss
   ↓
@StorefrontBootstrap
   ↓
@Plugins   ← hier landet dein Plugin-CSS
   ↓
skin/shopware/base.scss
   ↓
base.scss

Plugin-Struktur:

src/Resources/app/storefront/src/scss/
└── base.scss        # einziger Entry-Point, wird vom Theme-Compiler eingebunden

base.scss:

.acme-component {
    background-color: $sw-color-gray-100;
    border-radius: $border-radius;
    padding: $spacer;

    @include media-breakpoint-up(md) {
        padding: $spacer * 2;
    }

    &:focus-visible {
        @include focus-style;
    }
}

Bootstrap-Variablen erst ab base.scss verfügbar

Im Plugin selbst kannst du keine Variablen vor Bootstrap setzen (kein overrides.scss-Hook). Wer Variablen umsetzen muss, gehört in ein Child-Theme, siehe Child Theme manuell entwickeln.

Funktionen und Mixins des Themes nutzen

Plugins können die Theme-Mixins ohne extra Imports nutzen, theme:compile löst sie aus dem Guppy-Theme auf:

@include focus-style;
@include line-height(1.4);
@include button-adaptive-hover($primary);

Vollständige Liste: Variablen & Tokens.

Twig-Integration

Templates überschreiben

Plugin-Templates landen unter:

src/Resources/views/storefront/...

Beispiel: Custom-Block in der Header-Logo-Komponente:

{# src/Resources/views/storefront/layout/header/logo.html.twig #}
{% sw_extends '@Storefront/storefront/layout/header/logo.html.twig' %}

{% block layout_header_logo %}
    {{ parent() }}
    <span class="acme-logo-suffix">Powered by Acme</span>
{% endblock %}

sw_extends statt sw_replace

sw_replace bricht die Inheritance-Kette für nachfolgende Plugins. Nutze immer sw_extends.

Theme-Konfig in Plugin-Templates

Plugins können theme_config() lesen, egal ob das Feld vom Guppy-Theme oder einem anderen Plugin definiert ist:

{% if theme_config('guppy-header') == 'extended' %}
    {# Acme-spezifisches Verhalten bei extended Header #}
{% endif %}

Eigene Twig-Extension registrieren

// src/Twig/AcmeExtension.php
namespace Acme\GuppyExtension\Twig;

use Twig\Extension\AbstractExtension;
use Twig\TwigFunction;

class AcmeExtension extends AbstractExtension
{
    public function getFunctions(): array
    {
        return [
            new TwigFunction('acmeFormat', [$this, 'acmeFormat']),
        ];
    }

    public function acmeFormat(string $value): string
    {
        return strtoupper($value);
    }
}

<!-- src/Resources/config/services.xml -->
<service id="Acme\GuppyExtension\Twig\AcmeExtension">
    <tag name="twig.extension"/>
</service>

Storefront-JS-Integration

Eigenes Plugin als reguläres Shopware-Storefront-Plugin schreiben, Pattern und Beispiele siehe Storefront-JS.

Auf Splide-Slider aufsetzen

Statt einen eigenen Slider zu schreiben, DmfSplideSlider einbinden:

<div class="splide" data-splide-slider-plugin="true">
    <div class="splide__track">
        <ul class="splide__list">
            {# Slides #}
        </ul>
    </div>
</div>

Detail: DmfSplideSlider.

CMS-Integration

Eigene Blöcke und Elemente registrieren: siehe Eigene CMS-Blöcke.

Wiederverwendung von Blöcken (Linked-Blocks, JSON-Import/Export): DmfCmsBlockLibrary.

Asset-Pipeline

Plugin-Assets gehören unter src/Resources/app/storefront/dist/assets/ und werden vom Theme-Compiler ausgeliefert. Pfade in SCSS/Twig:

background-image: url("#{$app-css-relative-asset-path}/acme/banner.png");

<img src="{{ asset('bundles/acmeguppyextension/assets/acme/banner.png') }}" alt="">

Migrationen und Custom-Fields

Eigene Migrationen leben unter src/Migration/. Custom-Fields-Definitionen via services/custom-fields.xml, analog zu DmfGuppyTheme's Custom-Fields-Setup.

Versions-Kompatibilität

Pflicht-Constraint im Plugin:

"require": {
  "dmf/sw6-guppy-theme": "^2.0"
}

^2.0 lässt MINOR- und PATCH-Updates des Themes zu, blockiert MAJOR-Updates (siehe Changelog).

Validierung

Vor Release prüfen:

Check	Befehl
Plugin lädt	bin/console plugin:list | grep AcmeGuppyExtension
Theme kompiliert ohne Fehler	bin/console theme:compile
Storefront rendert ohne JS-Errors	Browser-Konsole prüfen
Linter	make lint (falls vorhanden)
Upgrade-Scan kompatibel	bin/console guppy:upgrade:scan

Verwandt

• Architektur: Vererbungs-Reihenfolge im Detail.
• Variablen & Tokens: verfügbare SCSS-Tokens und Mixins.
• Twig-Overrides: Override-Patterns mit sw_extends.
• Storefront-JS: Plugin-Pattern.
• Eigene CMS-Blöcke: CMS-Integration.