useCmsElement()

WARNING

Single File Component (SFC) support for Administration extensions is experimental. It is available since Shopware 6.7.16.0. The APIs described on this page can still change without a deprecation. Try it out and tell us what you find, but do not ship an extension built on it to customers or to the Shopware Store until the API is declared stable (planned for 6.9).

import { useCmsElement } from 'shopware:composables';

function useCmsElement(options: {
    element: () => RuntimeSlot;
    defaultConfig?: () => Record<string, unknown> | null;
}): ReturnType<typeof useCmsState> & {
    cmsElements: ComputedRef<Record<string, CmsElementConfig | undefined>>;
    config: ComputedRef<CmsSlotConfig>;
    getConfigValue: (path: string) => unknown;
    setConfigValue: (path: string, value: unknown) => void;
    getDemoValue: (mappingPath: string) => unknown;
};

The API a CMS element's editor component works against.

const { config, getConfigValue, setConfigValue } = useCmsElement({
    element: () => props.element,
    defaultConfig: () => props.defaultConfig ?? null,
});

function onMediaChange(mediaId: string): void {
    setConfigValue('media.value', mediaId);
}

config is the element's config resolved against the element type's defaultConfig and the inherited slot config, resolved on every read rather than written back into the element. So there is no initialization step, and no lifecycle hook to hang one on.

The element itself is read-only: setConfigValue() goes through the cmsPage store, which is what keeps the rest of the editor in sync. Both config functions take a path relative to the element's config, so a nested value is 'media.value', not 'config.media.value'.

Everything useCmsState() returns comes back as well, because the mixin composed it and components relied on that.

getDemoValue() resolves a mapping path against the demo entity the editor is previewing with.

Replaces the cms-element mixin.