Konzepte

Diese Seite erklärt die Designentscheidungen und mentalen Modelle hinter dem CMS Block Builder. Lesen Sie sie, um zu verstehen, warum das Plugin so funktioniert wie es ist — nicht nur wie man es benutzt.

Das Problem: Shopware CMS-Blöcke sind standardmäßig fest definiert

Shopware 6 liefert eine Reihe vorgefertigter CMS-Blöcke (z. B. zwei Spalten, Bild mit Text, Produkt-Slider). Diese Blöcke werden von Shopware Core oder installierten Plugins als kompilierter Code registriert. Ein Händler, der ein anderes Layout benötigt — etwa einen dreispaltigen Block, bei dem die erste Spalte breiter ist als die anderen — muss:

1. Ein Shopware-Plugin schreiben, das den neuen Block in PHP und JavaScript registriert.
2. Ein Twig-Template für die Storefront erstellen.
3. Das Plugin deployen und die Administration neu bauen.

Das ist eine Entwickleraufgabe, die typischerweise Stunden an Agenturzeit kostet. Der CMS Block Builder eliminiert diese Abhängigkeit, indem er Händlern ermöglicht, neue Block-Typen über die Admin-Benutzeroberfläche zu registrieren.

Was ein eigener Block ist

Ein eigener Block ist ein benanntes, wiederverwendbares Grid-Layout, das aus vorhandenen Shopware-CMS-Elementtypen zusammengesetzt ist. Er besteht aus:

• Einem technischen Namen — der Bezeichner, der zum Block-Typ-String ssd-custom-<technicalName> wird. Dieser ist dauerhaft, weil er in jeder CMS-Seite gespeichert wird, die den Block verwendet.
• Einer Grid-Konfiguration — eine JSON-Beschreibung, welche Bereiche auf dem 12-Spalten-CSS-Grid-Canvas existieren, je Breakpoint.
• Einer Slot-Zuweisung — eine Zuordnung von jeder Bereichs-ID zu einem CMS-Elementtyp (z. B. image, text, product-slider).

Wenn ein Händler den Block auf einer Seite im Erlebniswelten-Editor platziert, speichert Shopware ssd-custom-mein-block als Block-Typ in seiner cms_block-Tabelle. Die eigentlichen Layout-Daten (welches Element wo ist) leben in ssd_custom_block.

Elemente vs. Blöcke

Das Shopware CMS hat zwei Kompositionsebenen:

• Elemente sind individuelle Content-Widgets: ein Textbereich, ein Bild, ein Produkt-Slider. Jedes Element verwaltet seine eigenen Daten und sein Rendering.
• Blöcke sind Layout-Container, die ein oder mehrere Elemente in Spalten oder Bereichen anordnen.

Der CMS Block Builder arbeitet auf der Block-Ebene. Er komponiert Elemente in einem Grid, erstellt aber keine neuen Elementtypen. Jedes Element, das Sie in einen eigenen Block platzieren, ist ein Standard-Shopware-Element mit allen seinen Standard-Konfigurationsoptionen.

Das ist Design-Absicht: Das Plugin erhält alle zukünftigen Shopware-Elementverbesserungen kostenlos, und vorhandene Element-Templates übernehmen das Laden der eigenen Daten, Caching und SEO.

Das 12-Spalten-CSS-Grid-Canvas

Das Grid hat immer 12 Spalten und entspricht dem Bootstrap-12-Spalten-Grid, das Shopwares Storefront verwendet. Die Zeilenanzahl ist konfigurierbar (Standard: 4) und kann erweitert werden.

Bereiche werden durch rowStart, rowEnd, colStart, colEnd definiert — nullbasierte Koordinaten in CSS-Grid-Begriffen. Ein Bereich, der die Spalten 0–6 auf Zeile 0–1 umspannt, belegt die linke Hälfte der ersten Zeile.

Der Admin-Block-Editor rendert dieses Grid direkt als CSS-Grid und lässt Händler Bereiche durch Klicken und Ziehen zeichnen. Das Twig-Storefront-Template übersetzt dieselbe JSON in grid-column- und grid-row-Inline-Styles.

Struktur-Sperrung

Sobald ein eigener Block auf einer oder mehreren CMS-Seiten platziert wurde, ist seine Struktur gesperrt. Das bedeutet:

• Sie können keine Bereiche hinzufügen, entfernen oder umordnen.
• Sie können keine Vorlagen anwenden oder alle Bereiche löschen.
• Sie können die Zeilenanzahl nicht ändern.

Der Grund ist referenzielle Integrität. Jede cms_block-Zeile in der Shopware-Datenbank referenziert den Block-Typ-String und speichert die Element-Konfiguration je Slot-Name. Wenn Sie einen Slot entfernen würden, würde die gespeicherte Element-Konfiguration verwaist. Wenn Sie einen Slot hinzufügen würden, gäbe es keinen Inhalt dafür auf Seiten, die den Block bereits verwenden.

Was Sie bei einem gesperrten Block noch können:

• Elementtypen in vorhandenen Slots tauschen (die Slot-ID bleibt dieselbe).
• Tablet/Mobile-Layout-Positionen anpassen.
• Blockname, Kategorie und Position ändern.

Wenn Sie ein anderes Layout benötigen, erstellen Sie einen neuen Block mit dem aktualisierten Grid und ersetzen Sie dann den alten Block manuell auf jeder betroffenen Seite.

Breakpoints und responsives Design

Jeder Block speichert drei unabhängige Layout-Konfigurationen: Desktop, Tablet und Mobile. Im Desktop-Tab definieren Sie das kanonische Layout und die Element-Zuweisungen. Im Tablet- und Mobile-Tab definieren Sie, wie dieselben Slots für kleinere Bildschirme positioniert werden.

Element-Inhalt wird über Breakpoints geteilt. Nur die Grid-Positionen unterscheiden sich. Dies entspricht der Funktionsweise von responsivem CSS-Grid — derselbe Inhalt wird neu angeordnet, nicht dupliziert.

Die Storefront rendert alle drei Grid-Container in HTML. CSS (aus Bootstrap-Mixins kompiliert) blendet den passenden Container für den aktuellen Viewport ein und aus. Wenn ein Breakpoint-Layout leer ist, dient das Desktop-Layout als Fallback.

Block-Registrierung zur Laufzeit

Eigene Blöcke sind nicht zur Build-Zeit in das Theme eingebacken. Sie werden dynamisch geladen:

• Admin-Seite: Wenn der Erlebniswelten-Editor lädt, ruft eine JavaScript-Überschreibung (ssd-cms-block-registry.js) alle aktiven eigenen Blöcke von der API ab und ruft cmsService.registerCmsBlock() für jeden auf. Damit erscheinen sie im Block-Picker neben integrierten Blöcken.
• Storefront-Seite: CustomBlockRegistrationSubscriber hört auf das CmsPageLoadedEvent. Für jeden ssd-custom-*-Block auf der Seite sucht er die passende ssd_custom_block-Entität und hängt die Grid-Konfiguration als Twig-Erweiterung an. Das generische Template cms-block-ssd-custom-block.html.twig liest diese Erweiterung, um das Grid zu rendern.

Da die Registrierung laufzeit-dynamisch ist, tritt das Aktivieren oder Deaktivieren eines Blocks sofort in Kraft — ohne Cache-Leeren oder Admin-Rebuild.

Unveränderlichkeit des technischen Namens

Der technische Name wird Teil des Block-Typ-Strings ssd-custom-<technicalName>. Dieser String wird in der Shopware-cms_block-Tabelle für jede Instanz des Blocks auf jeder Seite gespeichert. Eine Änderung würde alle bestehenden Verwendungen verwaisen lassen — die Storefront würde nicht wissen, wie Blöcke des alten Typs gerendert werden.

Aus diesem Grund ist das Feld „Technischer Name" nur während der Block-Erstellung editierbar und wird nach dem ersten Speichern schreibgeschützt.

Eindeutigkeitsprüfung

Bei der Erstellung prüft das Plugin den technischen Namen gegen zwei Quellen:

1. Den Shopware-CMS-Block-Registry (Core-Blöcke + Plugin-registrierte Blöcke), um Namenskonflikte mit bestehenden Block-Typen zu vermeiden.
2. Die ssd_custom_block-Datenbanktabelle, um doppelte eigene Blöcke zu verhindern.

Die Prüfung läuft mit einer kurzen Verzögerung beim Tippen, sodass Sie Inline-Feedback sehen, bevor Sie speichern.