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:
Stay on your current bundle version — keep your existing Visual CMS version and stay compatible with your existing content.
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
ddoevisualcmscontentcontroller is now registered viaservices.yamland is no longer available for extension through the ``oxNew`` process.Renamed interfaces:
SaveWidgetsRequestInterface→WidgetsRequestInterface(now created with theWidgetsRequestFactoryInterface);ContentServiceInterface/ContentService→ContentPersistenceServiceInterface/ContentPersistenceService. Note: the namesContentServiceInterface/ContentServicenow 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*tovisualcms_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,VetreeExtensionInterfaceand the temporary moduleCore\RequestInterface(use the framework interface instead).Shortcode pickers with remote search (
SelectFromDataOption) no longer run through the removed admin dispatchVisualCmsAdmin::doShortCodeAction(). The option’sdataparameter — which carried the name of a method on the shortcode, e.g.searchArticle— was replaced by a mandatoryapiPathholding 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 ornull) — see Shortcode Search API.The
TreeView,ActionandArticleshortcode classes moved to their own namespaces (…\ShortCodeCollection\ShortCode\TreeView\TreeViewetc.). No class aliases are provided — update references in your code.Switched (where injected) to the framework
RequestInterfaceandSessionInterfaceinstead of the legacyCore\Request/Core\Session— someRegistry-based legacy access remains;Id::generateinstead ofUtilsObject::generateUIdin the content-edit flow; andShopAdapterInterface::translateStringin 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, whiletemplate.jsandpanel.jswere split into groups of typed services; theeditor.jsbridge 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 theContentobject 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 argumentVetreeLogicInterface,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:
Migrate Visual CMS content — convert from parse to tree format (see Changed Storage Format below).
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.
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 (...)
Product descriptions:
./vendor/bin/oe-console ddoewysiwyg:migrate:urls-to-ids oxartextends OXLONGDESC
Category descriptions:
./vendor/bin/oe-console ddoewysiwyg:migrate:urls-to-ids oxcategories OXDESC
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.