Dashboard Widget Registrierung

Wie registrieren Entwickler eigene CMS-Elemente im Dashboard

Externe Widgets Im CogiDashboard

Ein externes Widget braucht in der Regel nur ein normales CMS-Element plus ein paar Zeilen in registerCmsElement(...).

Das Minimum ist:

1. Ein normales Shopware-CMS-Element registrieren

2. dashboardWidget ergänzen

3. Optional ein eigenes Dashboard-Twig setzen

4. Nur wenn das Twig Daten braucht: normalen CMS-Resolver registrieren

Kurzbeispiel

Shopware.Service('cmsService').registerCmsElement({
    name: 'my-widget',
    label: 'MyPlugin.cms.elements.myWidget.label',
    component: 'sw-cms-el-my-widget',
    configComponent: 'sw-cms-el-config-my-widget',
    previewComponent: 'sw-cms-el-preview-my-widget',

    dashboardWidget: {
        label: 'MyPlugin.cms.elements.myWidget.label',
        icon: 'box',
        defaultSize: { w: 6, h: 4 },
        template: '@MyPlugin/storefront/element/cms-element-my-widget.html.twig',
    },

    defaultConfig: {
        title: {
            source: 'static',
            value: '',
        },
    },
});

Das reicht schon, damit das Element im Dashboard als Widget auftaucht.

Vollständiges Beispiel

Das hier ist absichtlich ausführlich, damit Entwickler einfach Felder rauslöschen können, die sie nicht brauchen.

Shopware.Service('cmsService').registerCmsElement({
    name: 'my-widget',
    label: 'MyPlugin.cms.elements.myWidget.label',
    component: 'sw-cms-el-my-widget',
    configComponent: 'sw-cms-el-config-my-widget',
    previewComponent: 'sw-cms-el-preview-my-widget',

    dashboardWidget: {
        label: 'MyPlugin.cms.elements.myWidget.label',
        icon: 'box',
        defaultSize: { w: 6, h: 4 },

        group: 'my-plugin',
        groupLabel: 'My Plugin',

        template: '@MyPlugin/storefront/element/cms-element-my-widget-dashboard.html.twig',
        component: 'sw-cms-el-my-widget',
        configComponent: 'sw-cms-el-config-my-widget',
        previewComponent: 'sw-cms-el-preview-my-widget',

        defaultConfig: {
            headline: {
                source: 'static',
                value: 'My headline',
            },
            ctaLabel: {
                source: 'static',
                value: 'Open',
            },
            ctaUrl: {
                source: 'static',
                value: '/account/my-page',
            },
        },

        defaultStyle: {
            cardTitle: 'My widget',

            cardHeaderBackgroundPreset: 'dark',
            cardHeaderBackgroundCustom: '',
            cardHeaderTextColorPreset: 'light',
            cardHeaderTextColorCustom: '',
            cardHeaderFontWeight: '700',
            cardHeaderFontSizePreset: 'lg',
            cardHeaderFontSizeCustom: '',
            cardHeaderFontStyle: 'normal',
            cardHeaderTextAlign: 'left',

            cardHeaderIconPreset: 'box',
            cardHeaderIconCustom: '',
            cardHeaderIconColorPreset: 'light',
            cardHeaderIconColorCustom: '',
            cardHeaderIconBackgroundPreset: 'dark',
            cardHeaderIconBackgroundCustom: '',

            cardButtonEnabled: true,
            cardButtonLabel: 'Open',
            cardButtonUrl: '/account/my-page',
            cardButtonBackgroundPreset: 'dark',
            cardButtonBackgroundCustom: '',
            cardButtonTextColorPreset: 'light',
            cardButtonTextColorCustom: '',
            cardButtonFontWeight: '600',
            cardButtonFontSizePreset: 'sm',
            cardButtonFontSizeCustom: '',
            cardButtonFontStyle: 'normal',
            cardButtonBorderWidth: '1px',
            cardButtonBorderStyle: 'solid',
            cardButtonBorderColorPreset: 'dark',
            cardButtonBorderColorCustom: '',
            cardButtonBorderRadius: '8px',
            cardButtonShadowPreset: 'sm',
            cardButtonShadowCustom: '',

            cardBorderRadius: '12px',
            cardShadowPreset: 'md',
            cardShadowCustom: '',
        },
    },

    defaultConfig: {
        headline: {
            source: 'static',
            value: '',
        },
        ctaLabel: {
            source: 'static',
            value: '',
        },
        ctaUrl: {
            source: 'static',
            value: '',
        },
    },
});

Was dashboardWidget Unterstützt

• label: Name im Widget-Katalog

• icon: Icon im Widget-Katalog

• defaultSize: Standardgröße im Dashboard-Grid, z. B. { w: 6, h: 4 }

• group: optionale Gruppen-ID im Katalog

• groupLabel: optionale Gruppenüberschrift im Katalog

• template: eigenes Twig nur für das Dashboard

• component: optional eigener Admin-Component für das Dashboard

• configComponent: optional eigener Config-Component für das Dashboard

• previewComponent: optional eigener Preview-Component für das Dashboard

• defaultConfig: Dashboard-spezifische Default-Config; wird mit defaultConfig des CMS-Elements gemerged

• defaultStyle: Default-Werte für die Dashboard-Card

Alle defaultStyle-Keys

defaultStyle: {
    cardTitle: '',

    cardHeaderBackgroundPreset: '',
    cardHeaderBackgroundCustom: '',
    cardHeaderTextColorPreset: '',
    cardHeaderTextColorCustom: '',
    cardHeaderFontWeight: '',
    cardHeaderFontSizePreset: '',
    cardHeaderFontSizeCustom: '',
    cardHeaderFontStyle: '',
    cardHeaderTextAlign: '',

    cardHeaderIconPreset: '',
    cardHeaderIconCustom: '',
    cardHeaderIconColorPreset: '',
    cardHeaderIconColorCustom: '',
    cardHeaderIconBackgroundPreset: '',
    cardHeaderIconBackgroundCustom: '',

    cardButtonEnabled: false,
    cardButtonLabel: '',
    cardButtonUrl: '',
    cardButtonBackgroundPreset: '',
    cardButtonBackgroundCustom: '',
    cardButtonTextColorPreset: '',
    cardButtonTextColorCustom: '',
    cardButtonFontWeight: '',
    cardButtonFontSizePreset: '',
    cardButtonFontSizeCustom: '',
    cardButtonFontStyle: '',
    cardButtonBorderWidth: '',
    cardButtonBorderStyle: '',
    cardButtonBorderColorPreset: '',
    cardButtonBorderColorCustom: '',
    cardButtonBorderRadius: '',
    cardButtonShadowPreset: '',
    cardButtonShadowCustom: '',

    cardBorderRadius: '',
    cardShadowPreset: '',
    cardShadowCustom: '',
}

Typische Werte

• Icons: box, marker, heart, history, tag, checkmark, check-circle-s, gift, wallet, trophy, megaphone

• Farben: primary, secondary, success, info, warning, danger, light, dark, white, black, body-bg, body-color, gray-100, gray-200, gray-300, custom

• Font-Größen: xs, sm, base, lg, xl, 2xl, custom

• Font-Stile: normal, italic, oblique

• Text-Align: left, center, right

• Border-Stile: none, solid, dashed, dotted, double

• Shadow-Presets: none, sm, md, lg, custom

Was Im Twig Verfügbar Ist

Im Dashboard könnt ihr mit Folgendem rechnen:

• element

• element.config

• element.data, falls ein Resolver Daten gesetzt hat

Womit ihr nicht automatisch rechnen solltet:

• zusätzliche Controller-Variablen

• route-spezifische Request-Attribute

• Seitenkontext aus einer ganz anderen Storefront-Seite

Wenn euer normales CMS-Twig z. B. page.product, page.header.navigation, einen speziellen rewardContext oder eigene Controller-Variablen braucht, ist ein eigenes Dashboard-Twig meistens die sauberste Lösung.

Template-Fallback

Das Dashboard rendert in dieser Reihenfolge:

1. dashboardWidget.template

2. Template aus einem cogi_dashboard.widget_template-Provider

3. @Storefront/storefront/element/cms-element-<type>.html.twig

Für neue Integrationen ist dashboardWidget.template fast immer der einfachste Weg.

Edge Cases

Twig funktioniert auf einer normalen CMS-Seite, aber nicht im Dashboard

Häufiger Grund:

• Das normale Twig erwartet Seitendaten oder Controller-Kontext, den das Dashboard nicht liefert

Typische Kandidaten:

• page.product

• page.cmsPage-Sonderlogik

• Request-Parameter

• eigene Controller-Variablen

Lösung:

• eigenes dashboardWidget.template anlegen

• dort nur den Kontext verwenden, der im Dashboard sicher existiert

defaultConfig verhält sich anders als erwartet

Wichtig:

• dashboardWidget.defaultConfig wird mit dem normalen defaultConfig des CMS-Elements gemerged

• gleiche Keys aus dashboardWidget.defaultConfig überschreiben die normalen Defaults

Das ist praktisch für Dashboard-spezifische Startwerte, kann aber auch bestehende Defaults bewusst ersetzen.