Custom CMS Blocks

Shopware's Shopping Experiences support custom CMS blocks and elements. This page covers three layered paths:

1. Manual registration of a CMS block via an admin component plus a storefront template.
2. Generator-driven with /create-element from DmfCmsCustomElements.
3. Reuse through DmfCmsBlockLibrary (saved blocks, linked blocks).

• Block vs. element vs. section
• Path 1: Manual registration
  • Admin component
  • Storefront template
  • SCSS
  • Build
• Path 2: Generator (/create-element)
• Path 3: Reuse with DmfCmsBlockLibrary
• Use a block inside a custom grid
• Splide slider inside custom elements
• Related

Block vs. element vs. section

Shopware uses three hierarchy levels:

Level	What it is
Section	Outermost container of a CMS page (default, sidebar, …)
Block	Layout container inside a section (e.g. image-text)
Element	Actual content of a slot inside a block (e.g. image, text)

DmfCmsCustomGrids and DmfCmsDynamicGrid provide blocks. DmfCmsCustomElements and DmfGuppyEmotionworldElements provide elements.

Path 1: Manual registration

Admin component

In your 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

Path 2: Generator (/create-element)

DmfCmsCustomElements ships a generator that scaffolds the boilerplate for CMS elements. Three patterns:

Pattern	Use case	Reference element
simple	Single item with media, text, toggles	hero-banner
array	Multiple items with add/remove/sort	hero-product-grid
slider	Splide carousel with autoplay	banner-slider

/create-element call-to-action -- Background image with overlay, headline, description, and CTA button
/create-element timeline --pattern array -- Timeline entries with date, title, description, and optional image
/create-element testimonial-slider --pattern slider -- Testimonial carousel with quote, author, company, and avatar

After generation:

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

Detail: DmfCmsCustomElements.

Path 3: Reuse with DmfCmsBlockLibrary

DmfCmsBlockLibrary turns any CMS block into a reusable entry:

• Saved blocks: save a block from any Shopping Experience and insert it into any other (new UUIDs).
• Linked blocks: saved instance that stays in live sync with the library entry.
• JSON import/export: move library content between systems.

For your own blocks: no special handling required, once registered as a regular cms_block, they can be saved and reused.

Detail: DmfCmsBlockLibrary.

Use a block inside a custom grid

If you need custom layouts beyond the bundled blocks:

• Static: DmfCmsCustomGrids.
• Dynamic (visual per-viewport editor): DmfCmsDynamicGrid.

Splide slider inside custom elements

Slider-based elements (slider pattern) consume DmfSplideSlider:

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

Detail: DmfSplideSlider and Storefront JS → Splide configuration.

Related

• DmfCmsCustomElements: generator and patterns.
• DmfCmsBlockLibrary: reusable blocks.
• DmfCmsCustomGrids and DmfCmsDynamicGrid: grid layouts.
• Twig Overrides: template patterns.