Update

OXID eShop 7.6 comes with Visual CMS 12 out of the box — no manual installation needed. The Content & Media Bundle updates automatically with your OXID eShop update via Composer.

If you are updating from an older OXID eShop version, you have two options before the update:

  1. Stay on your current bundle version — keep your existing Visual CMS version and stay compatible with your existing content.

  2. Update to Visual CMS 12 — get all new features; depending on your starting version, migration steps for existing content or adjustments to custom extensions are needed afterward (see below).

Note

If you are already on Visual CMS 11, you can update directly to Visual CMS 12 without content migration (see Migration from Visual CMS 11 to 12).

Version Compatibility

OXID eShop 7.6 comes with Visual CMS 12 (Content & Media Bundle 12) out of the box.

On OXID eShop 7.6 the Visual CMS versions 8, 11 and 12 are supported; version 12 is the default.

To stay on an older bundle version, specify the target version in your Composer settings before updating. For details, see the Update guide in the OXID eShop documentation.

Migration from Visual CMS 11 to 12

Visual CMS 12 is built for OXID eShop 7.6 and continues Visual CMS 11.

Does this affect you?

  • Standard shop — no custom widgets/extensions and no custom styles in CMS content: nothing to do. The update is automatic and needs no content migration.

  • Custom CSS/SCSS in CMS content: check it for the LESS→SCSS change — see Individual Styles below.

  • Custom widgets, or extensions of the Visual CMS rendering: adjust them for the breaking changes — see Custom widgets and extensions below.

Content: The content storage format has not changed — updating from Visual CMS 11 to 12 requires no content migration. The Dynamic Blocks feature introduced with Visual CMS 12 requires no migration for existing shops. Individual styles are the exception — see “Individual Styles” below.

Individual Styles: When moving from 11 to 12, the CMS contents’ individual styles (the “Custom CSS / SCSS” field in the editor) are no longer interpreted as LESS but as SCSS. Existing LESS syntax (e.g. @variables, mixins) may compile differently or fail. Check your content first without writing to it:

./vendor/bin/oe-console ddoevisualcms:migrate:less-to-scss --dry-run

The report lists all contents containing LESS parts. Without --dry-run the command only rewrites a content when the SCSS compilation produces exactly the CSS rendered before; any deviations are reported for manual rework.

Warning

A custom widget or extension that is not adjusted can break the shop with a fatal error right after the update.

Custom widgets and extensions: Visual CMS 12 contains code changes that are not backwards compatible. Modules extending Visual CMS have to be adjusted:

  • The ddoevisualcmscontent controller is now registered via services.yaml and is no longer available for extension through the ``oxNew`` process.

  • Renamed interfaces: SaveWidgetsRequestInterface → WidgetsRequestInterface (now created with the WidgetsRequestFactoryInterface); ContentServiceInterface / ContentService → ContentPersistenceServiceInterface / ContentPersistenceService. Note: the names ContentServiceInterface / ContentService now denote a new, different orchestrator class (delegating to the persistence service), not the old one — update type hints to the intended target.

  • The style editor’s Twig blocks were renamed from visualcms_less_editor* to visualcms_style_editor* (relevant only if you customized the editor dialog itself). For the content side of the LESS→SCSS switch, see “Individual Styles” above.

  • Removed interfaces: GridFromRequestInterface, VetreeExtensionInterface and the temporary module Core\RequestInterface (use the framework interface instead).

  • Shortcode pickers with remote search (SelectFromDataOption) no longer run through the removed admin dispatch VisualCmsAdmin::doShortCodeAction(). The option’s data parameter — which carried the name of a method on the shortcode, e.g. searchArticle — was replaced by a mandatory apiPath holding a route prefix (e.g. api/vcms-shortcode/article). Custom shortcodes using this option must provide their own Symfony controller exposing <apiPath>/search (JSON list while typing) and <apiPath>/item (a single object or null) — see Shortcode Search API.

  • The TreeView, Action and Article shortcode classes moved to their own namespaces (…\ShortCodeCollection\ShortCode\TreeView\TreeView etc.). No class aliases are provided — update references in your code.

  • Switched (where injected) to the framework RequestInterface and SessionInterface instead of the legacy Core\Request / Core\Session — some Registry-based legacy access remains; Id::generate instead of UtilsObject::generateUId in the content-edit flow; and ShopAdapterInterface::translateString in shortcodes.

  • The browser code of the content editor was further converted to TypeScript with dependency injection: grid.js → Grid.ts, VisualEditor.js → VisualEditor.ts, main.js → Main.ts, while template.js and panel.js were split into groups of typed services; the editor.js bridge was removed. The widgets’ storefront scripts (node_build/js/frontend/, e.g. hero.js, fullwidth.js) are not affected.

See Developer Information for the extension points.

Migration from Visual CMS 10 to 11

Visual CMS 11 is built for OXID eShop 7.5 and replaces Visual CMS 10, so this is an update within the same shop version.

Important

Coming from Visual CMS 8 or 9, there is no need to update to Visual CMS 10 first — Visual CMS 11 ships the same migration commands. Update directly to Visual CMS 11 (check for 7.5.0 metapackage limitations) and run the content migration described in Migration from Visual CMS 8 afterwards.

Existing content does not need to be migrated — the storage format has not changed since Visual CMS 9 and there are no new database migrations. Shops using Visual CMS as delivered can update without further steps for migrating their content. Modules providing custom widgets or extending the Visual CMS rendering have to be adjusted as described below.

Warning

A custom widget that is not adjusted breaks the shop with a fatal error (Declaration ... must be compatible with ...) right after the update.

Custom Widgets

prepareTemplateParams() receives the render context as an additional argument. Add it to every custom widget implementing or overriding this method and pass it on to the parent call:

// Visual CMS 10
public function prepareTemplateParams(GridItemInterface $gridItem): array
{
    $params = parent::prepareTemplateParams($gridItem);

    // ...
}

// Visual CMS 11
public function prepareTemplateParams(
    GridItemInterface $gridItem,
    GridRenderContextInterface $renderContext
): array {
    $params = parent::prepareTemplateParams($gridItem, $renderContext);

    // ...
}

Widgets extending BaseShortCode without overriding prepareTemplateParams() need no change. See Render Context for what the render context provides.

Extensions of the Rendering

The render context is passed through the whole grid rendering chain, so decorators and replacements of these services have to be adjusted as well:

  • GridRendererFacadeInterface — renderGrid() does not receive the Content object anymore, it is a part of the render context and available via $renderContext->getContent()

  • GridItemArrayRendererInterface, GridItemRendererInterface, TemplateParamsCalculatorInterface — the render context is passed as an additional argument

  • VetreeLogicInterface, PreviewServiceInterface — the variables of the triggering template are passed as an additional argument

Migration from Visual CMS 8

If you are updating from Visual CMS 8, your content uses the old parse format and must be migrated to the tree format to work with Visual CMS 11 or 12.

Content already in the tree format (Visual CMS 9 or newer) does not need to be migrated — the storage format has not changed since.

Warning

Do a full database and filesystem backup before running the migration. This allows for immediate reversal if you encounter unexpected issues.

After updating, run these migration steps:

  1. Migrate Visual CMS content — convert from parse to tree format (see Changed Storage Format below).

  2. Convert media URLs to IDs — for Visual CMS and WYSIWYG content (see Media IDs in Visual CMS and Media IDs in WYSIWYG below).

The following sections describe each step in detail.

Changed Storage Format

With Visual CMS 9 (introduced in OXID eShop 7.4), widget configuration storage changed from parse to tree format. Widgets are now stored as structured data in database tables instead of a parsed string.

CMS contents containing the veparse string must be migrated to the tree format to work in Visual CMS 11 or 12. Run this command:

./vendor/bin/oe-console ddoevisualcms:migrate:veparse-to-vetree

The command converts all contents using veparse to the new vetree structure. Afterwards, widgets can be configured as usual through the Visual CMS editor interface.

Note

If the ddoevisualcms:migrate:veparse-to-vetree command is not available (“There are no commands defined in the ddoevisualcms:migrate namespace”), re-activate the modules and it will be registered.

CMS contents consisting of plain HTML only (no veparse) do not require migration. Such contents are left untouched and are automatically flagged with the Disable widgets and use only text option after the update, so they continue to work as before. If you want to use widgets in these contents later, deactivate that option and edit them in the Visual CMS editor. After saving, the content will be stored in the new tree format.

Warning

Switching to the widget editor will open an empty workspace, as the existing plain HTML is not represented as widgets. Your text-only content will be permanently lost as soon as you save. Be sure to copy any text you wish to keep before switching modes.

Introduction of Media IDs

With Media Library 4, introduced in OXID eShop 7.4, simple filepaths were replaced with media IDs in WYSIWYG Editor and Visual CMS. This ensures media files can still be found even after renaming or moving them. While the old path-based references still work after the update, migrating existing contents to use media IDs is recommended to take full advantage of this feature.

Note

The migration commands below write to your content in the database. Do a database backup first. The conversion is idempotent — already-converted references are skipped and unresolvable ones are only reported (not changed) — so a command can be re-run safely.

Media IDs in WYSIWYG Editor

The WYSIWYG editor is used for several content pieces in the OXID eShop. You can update existing contents from media URLs to IDs by running the following commands using OE Console:

Note

The ddoewysiwyg:migrate:urls-to-ids command converts media references in both image src and link href attributes (not only in specifically marked images). After running, it reports every converted and every unresolvable reference. Already converted references are skipped and not treated as an error, so the command can be run again safely. References that cannot be matched to a Media Library file are not imported; they are listed as unresolvable in the report. External URLs, paths outside the Media Library and data: URIs are left unchanged (no Media Library entry). Use the --report-file <path> option to write that report as a CSV file instead of printing it.

Hint

Remember to convert all fields for all languages, e.g. OXCONTENT, OXCONTENT_1, OXCONTENT_2 etc. as shown in the first example.

  1. General contents like CMS pages:

    ./vendor/bin/oe-console ddoewysiwyg:migrate:urls-to-ids oxcontents OXCONTENT
    ./vendor/bin/oe-console ddoewysiwyg:migrate:urls-to-ids oxcontents OXCONTENT_1
    ./vendor/bin/oe-console ddoewysiwyg:migrate:urls-to-ids oxcontents OXCONTENT_2
    (...)
    
  2. Product descriptions:

    ./vendor/bin/oe-console ddoewysiwyg:migrate:urls-to-ids oxartextends OXLONGDESC
    
  3. Category descriptions:

    ./vendor/bin/oe-console ddoewysiwyg:migrate:urls-to-ids oxcategories OXDESC
    
  4. Payment descriptions:

    ./vendor/bin/oe-console ddoewysiwyg:migrate:urls-to-ids oxpayments OXDESC
    

You can migrate other WYSIWYG contents, such as custom database fields, with the command by passing the correct values for:

  • The database table containing the data to convert.

  • The specific field name in the selected database table.

  • The table’s unique ID key (primary key). The default value is OXID.

./vendor/bin/oe-console ddoewysiwyg:migrate:urls-to-ids <table-name> <field-name> <table-id-key>

Media IDs in Visual CMS

The Visual CMS includes widgets that deal with media, such as the image widget or the gallery. To convert media paths in these widgets, run the following command using OE Console:

./vendor/bin/oe-console ddoevisualcms:migrate:urls-to-ids

Note

In the carousel widget, each slide also references a link (format mediaId;link). ddoevisualcms:migrate:urls-to-ids converts the media ID; review carousels after the migration.

Alt-Text Placeholders in WYSIWYG Editor

Important

This command is available from WYSIWYG Editor 7 onwards — including the WYSIWYG Editor 8 shipped with OXID eShop 7.6. It was not backported to WYSIWYG Editor 6 or older versions.

With WYSIWYG Editor 7, alt texts for media images can be pulled from the Media Library in a language-dependent manner. The following command replaces empty or missing alt attributes in existing content with the oeMediaAlt placeholder:

./vendor/bin/oe-console ddoewysiwyg:migrate:alt-texts <table-name> <field-name> <table-id-key>

The arguments are identical to ddoewysiwyg:migrate:urls-to-ids:

  • The database table containing the data to convert.

  • The specific field name in the selected database table.

  • The table’s unique ID key (primary key). The default value is OXID.

Hint

Existing, manually assigned alt texts are not overwritten. The command prints a list of images with custom alt texts after completion, for manual review.