First of all, a big thanks to Shopware for providing us with a documentation! It's very hard to keep the documentation up to date, especially when the product is always evolving. I think they are doing a pretty good job! You think the documentation is not good? Well take a look at a real bad documentation and you will appreciate the good work!

The good thing is you also can take a look at the code. So maybe taking a deeper look into the Shopware Code will help you as well.

I took a detailed look at CMS-Blocks and CMS-Elements and found something which is not documented. So it's time for a PR right?

The CMS-Block and CMS-Element Combination

What's the difference between a CMS-Block and a CMS-Element? That's a bit confusing but still important to know. I already wrote a bit about the Shopware CMS feel free to take a look at it!

The CMS-Block

The block is basically the wrapper element. That means inside of a block you can place an element. This sounds good for layout blocks in which we put our elements right? Now you also can use CMS-Blocks for different other things but they are limited.

You can not give the block a configuration without a workaround for example. The workaround here would be to use the Plugin Configuration which is not good practice.

Imagine having a block like this, you only had one possibility to configure the block and it would always look the same. So you are still limited.

CMS-Block in the administration

We see our block preview on the right side with a selection of our blocks. In the editor in the middle we see our block as the outer wrapper and inside the block is our element.

Now the element has two icons. One for the configuration and one icon to exchange the element within the block. Let's take a look what happens in the frontend.

We see our block as the outer wrapper. The <div class="cms-block pos-0 cms-block-text" style=""> tells us where our block starts and inside of the block we have another <div class="cms-element-text"> which tells us where our element starts

The problem?

In the administration we can easily change the element by clicking on the change icon. Let's do this!

We changed the element within the standard text block to our custom button. It works and we see everything in the frontend but:

Our block is not changing. That could lead to problems if you do scss stylings based on the block class.

The CMS-Element

The element is actually the more interesting part. You have a configuration and you can do a lot more with the element. The configuration comes from the element and you can switch elements within a block which can cause issues.

If you handle it correctly everything will still work as expected. Let's assume the elements will only work if they are placed in the correct block. Maybe because of styling or maybe because of the block conditions in your twig file.

In the shopware documentation we have a configuration object with a couple of options.

Unfortunately we only see the required options in the documentation. What's not mentioned here is that there are other options as well. So let's take a look at the shopware code.

Shopware Code

I saw this index.js in the shopware code

import './component';
import './config';
import './preview';
import './config/components/sw-cms-el-config-product-listing-config-sorting-grid';
import './config/components/sw-cms-el-config-product-listing-config-filter-properties-grid';

/**
 * @private since v6.5.0
 */
Shopware.Service('cmsService').registerCmsElement({
    name: 'product-listing',
    label: 'sw-cms.elements.productListing.label',
    hidden: true,
    removable: false,
    component: 'sw-cms-el-product-listing',
    previewComponent: 'sw-cms-el-preview-product-listing',
    configComponent: 'sw-cms-el-config-product-listing',
    defaultConfig: {
        boxLayout: {
            source: 'static',
            value: 'standard',
        },
        showSorting: {
            source: 'static',
            value: true,
        },
        useCustomSorting: {
            source: 'static',
            value: false,
        },
        availableSortings: {
            source: 'static',
            value: {},
        },
        defaultSorting: {
            source: 'static',
            value: '',
        },
        filters: {
            source: 'static',
            value: 'manufacturer-filter,rating-filter,price-filter,shipping-free-filter,property-filter',
        },
        // eslint-disable-next-line inclusive-language/use-inclusive-words
        propertyWhitelist: {
            source: 'static',
            value: [],
        },
    },
});

Now we have two options here which are not mentioned in the docs:

• hidden
• removable

The hidden option

The hidden option will hide the CMS-Element in the modal. So there is no way to select an element without the related block. We are just going to add a bit of code from our CMS-Element we created in a previous post to see it in action. We adjust our index.js in src/Resources/app/administration/src/module/sw-cms/elements/cms-button/

import './component';
import './config';
import './preview';


Shopware.Service('cmsService').registerCmsElement({
    name: 'cms-button',
    label: 'sw-cms.blocks.text.ninja-cms-button.label',
    component: 'sw-cms-el-cms-button',
    configComponent: 'sw-cms-el-config-cms-button',
    previewComponent: 'sw-cms-el-preview-cms-button',
    hidden: true, // Added --> hide element in switch modal
    defaultConfig: {
        title: {
            source: 'static',
            value: 'ButtonText'
        },
        textColor: {
            source: 'static',
            value: '#fff'
        },
        url: {
            source: 'static',
            value: ''
        },
        newTab: {
            source: 'static',
            value: 'true'
        },
        buttonAlign: {
            source: 'static',
            value: 'center'
        },
        buttonColor: {
            source: 'static',
            value: '#4492ed'
        },
        buttonWidth: {
            source: 'static',
            value: ''
        },
        buttonHeight: {
            source: 'static',
            value: ''
        }
    },

});

As you can see you can not select the element in the modal anymore. But you still can change the element within a block.

The removable option

If you want your block only to be used with the related element there is also a way to do this. You can remove the icon to change the element. That's what the removable option is for. We adjust our index.js once again:

import './component';
import './config';
import './preview';


Shopware.Service('cmsService').registerCmsElement({
    name: 'cms-button',
    label: 'sw-cms.blocks.text.ninja-cms-button.label',
    component: 'sw-cms-el-cms-button',
    configComponent: 'sw-cms-el-config-cms-button',
    previewComponent: 'sw-cms-el-preview-cms-button',
    removable: false, // Added --> disable switching in block
    hidden: true, // hide element in switch modal
    defaultConfig: {
        title: {
            source: 'static',
            value: 'ButtonText'
        },
        textColor: {
            source: 'static',
            value: '#fff'
        },
        url: {
            source: 'static',
            value: ''
        },
        newTab: {
            source: 'static',
            value: 'true'
        },
        buttonAlign: {
            source: 'static',
            value: 'center'
        },
        buttonColor: {
            source: 'static',
            value: '#4492ed'
        },
        buttonWidth: {
            source: 'static',
            value: ''
        },
        buttonHeight: {
            source: 'static',
            value: ''
        }
    },

});

The result:

NOTE: if you only use the removable option it will still be possible to use any block and select your element from the modal!

Recap

Luckily Shopware is an open source project and we can take a look at the code. The documentation is good and if it's not enough for you, simply take a look at the code. We found two options for the CMS-Elements which are not mentioned in the documentation but we can add it to the documentation amazing right?

If you work with Shopware the code is the best documentation, at least in my opinion. So always take a look at it!

| hidden (optional)| The technical name of your element. Will be used for the template loading later on. | | removable (optional| A name to be shown for your element in the User Interface. Preferably as a snippet key. |