Eigene CMS-Blöcke

Shopwares Shopping Experiences erlauben eigene CMS-Blöcke und -Elemente. Diese Seite zeigt drei aufeinander aufbauende Pfade:

1. Manuelle Registrierung eines CMS-Blocks via Admin-Komponente plus Storefront-Template.
2. Generator-gestützt mit /create-element aus DmfCmsCustomElements.
3. Wiederverwendung über DmfCmsBlockLibrary (gespeicherte Blöcke, Linked-Blocks).

• Block vs. Element vs. Section
• Pfad 1: Manuelle Registrierung
  • Admin-Komponente
  • Storefront-Template
  • SCSS
  • Build
• Pfad 2: Generator (/create-element)
• Pfad 3: Wiederverwendung mit DmfCmsBlockLibrary
• Block in Custom-Grid verwenden
• Splide-Slider in Custom-Elements
• Verwandt

Block vs. Element vs. Section

Shopware unterscheidet drei Hierarchie-Ebenen:

Ebene	Was es ist
Section	äußerster Container einer CMS-Seite (default, sidebar, …)
Block	Layout-Container innerhalb einer Section (z. B. image-text)
Element	tatsächlicher Inhalt eines Slots im Block (z. B. image, text)

DmfCmsCustomGrids und DmfCmsDynamicGrid liefern Blöcke. DmfCmsCustomElements und DmfGuppyEmotionworldElements liefern Elemente.

Pfad 1: Manuelle Registrierung

Admin-Komponente

Im Plugin (src/Resources/app/administration/):

// src/main.js
import './module/sw-cms/blocks/text/my-call-to-action';

// src/module/sw-cms/blocks/text/my-call-to-action/index.js
import './component';
import './preview';

Shopware.Service('cmsService').registerCmsBlock({
    name: 'my-call-to-action',
    label: 'My Call to Action',
    category: 'text',
    component: 'sw-cms-block-my-call-to-action',
    previewComponent: 'sw-cms-preview-my-call-to-action',
    defaultConfig: {
        marginBottom: '20px',
        marginTop: '20px',
        marginLeft: '20px',
        marginRight: '20px',
        sizingMode: 'boxed'
    },
    slots: {
        headline: 'text',
        cta: { type: 'text', default: { config: { content: { source: 'static', value: 'Click me' } } } }
    }
});

Storefront-Template

{# src/Resources/views/storefront/block/cms-block-my-call-to-action.html.twig #}
{% block block_my_call_to_action %}
    <div class="cms-block cms-block-my-call-to-action">
        <div class="cms-block-container">
            <div class="cms-block-container-row row">
                <div class="col-12">
                    {% block block_my_call_to_action_headline %}
                        {% sw_include '@Storefront/storefront/element/cms-element-text.html.twig' with {
                            element: block.slots.getSlot('headline')
                        } %}
                    {% endblock %}

                    {% block block_my_call_to_action_cta %}
                        {% sw_include '@Storefront/storefront/element/cms-element-text.html.twig' with {
                            element: block.slots.getSlot('cta')
                        } %}
                    {% endblock %}
                </div>
            </div>
        </div>
    </div>
{% endblock %}

SCSS

// src/Resources/app/storefront/src/scss/base.scss
.cms-block-my-call-to-action {
    background-color: $sw-color-gray-100;
    padding: $spacer * 2;
    text-align: center;
}

Build

./bin/build-administration.sh
./bin/build-storefront.sh
bin/console cache:clear

Pfad 2: Generator (/create-element)

DmfCmsCustomElements liefert einen Generator, der die Boilerplate für CMS-Elemente erzeugt. Drei Patterns:

Pattern	Use-Case	Referenz-Element
simple	einzelnes Item mit Media, Text, Toggles	hero-banner
array	mehrere Items mit Add/Remove/Sort	hero-product-grid
slider	Splide-Karussell mit Autoplay	banner-slider

/create-element call-to-action -- Hintergrundbild mit Overlay, Headline, Beschreibung und CTA-Button
/create-element timeline --pattern array -- Timeline-Einträge mit Datum, Titel, Beschreibung und optionalem Bild
/create-element testimonial-slider --pattern slider -- Testimonial-Karussell mit Zitat, Autor, Firma und Avatar

Nach der Generierung:

./bin/build-administration.sh
./bin/build-storefront.sh
bin/console cache:clear

Detail: DmfCmsCustomElements.

Pfad 3: Wiederverwendung mit DmfCmsBlockLibrary

DmfCmsBlockLibrary macht aus jedem CMS-Block einen wiederverwendbaren Eintrag:

• Saved Blocks: Block in beliebiger Erlebniswelt speichern, in jeder anderen einfügen (neue UUIDs).
• Linked Blocks: gespeicherte Instanz, die live mit dem Bibliothekseintrag synchron bleibt.
• JSON-Import/Export: Bibliothek-Inhalte transportieren.

Für eigene Blöcke gilt: keine Sonderbehandlung nötig, sobald sie als regulärer cms_block registriert sind, lassen sie sich speichern und wiederverwenden.

Detail: DmfCmsBlockLibrary.

Block in Custom-Grid verwenden

Wenn du eigene Layouts brauchst, statt nur die mitgelieferten Blöcke:

• Statisch: DmfCmsCustomGrids.
• Dynamisch (visueller Editor pro Viewport): DmfCmsDynamicGrid.

Splide-Slider in Custom-Elements

Slider-basierte Elements (Pattern slider) konsumieren DmfSplideSlider:

{% sw_include '@DmfSplideSlider/storefront/component/splide.html.twig' with {
    slides: element.config.items.value,
    options: {
        type: 'loop',
        perPage: 1,
        autoplay: true
    }
} %}

Detail: DmfSplideSlider und Storefront-JS → Splide-Konfiguration.

Verwandt

• DmfCmsCustomElements: Generator und Patterns.
• DmfCmsBlockLibrary: wiederverwendbare Blöcke.
• DmfCmsCustomGrids und DmfCmsDynamicGrid: Grid-Layouts.
• Twig-Overrides: Template-Patterns.