Update

OXID eShop 7.5 comes with Visual CMS 10 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 (e.g. 7.3 with VCMS Bundle 8), you have two options before the update:

Stay on your current bundle version — keep Visual CMS 8 or 9 and stay compatible with your existing content.
Update to Visual CMS 10 — get all new features, but you need to migrate your existing content afterward (see below).

Note

If you are already on OXID eShop 7.4.x with Visual CMS 9, you can update directly to Visual CMS 10 without content migration.

Hint

Visual CMS 11 is available for OXID eShop 7.5 as well although not covered by metapackage 7.5.0 PE/EE. When planning the update to Visual CMS 10, read the notes in Migration from Visual CMS 10 to 11 too and do both in one step.

Version Compatibility

OXID eShop 7.5 supports four Visual CMS versions in parallel:

Visual CMS 11 — newest (Content & Media Bundle 11, recommended)
Visual CMS 10 — stay on your current version (Content & Media Bundle 10)
Visual CMS 9.2 — stay on your current version (Content & Media Bundle 9)
Visual CMS 8.0 — stay on your current version (Content & Media Bundle 8)

Note

The OXID eShop 7.5.0 PE and EE Metapackages are only compatible with Visual CMS 8.0.2/9.2.1/10.0.1. Visual CMS 11 continues Visual CMS 10 for the same shop version. It brings the improvements that could not become a part of Visual CMS 10, as they are not backwards compatible on the code level. The stored content is the same in both versions, so no content migration is involved — see Migration from Visual CMS 10 to 11. In order to install VCMS 11 beside 7.5.0 Metapackage PE/EE you need to either alias it to 10.0.1 or build an own root composer.json.

To stay on Bundle 8 or 9, 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 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 needs to be migrated to work with Visual CMS 9 or 10.

If you are updating from Visual CMS 9 to 10, no content migration is needed — the storage format is already the new tree format.

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 work in Visual CMS 10. 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.

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. If command is not known, it is likely fixed by reactivation of the modules.

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.

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:

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

Alt-Text Placeholders in WYSIWYG Editor

Important

This command is only available in WYSIWYG Editor 7 (Content & Media Bundle 10). It has not been backported to WYSIWYG Editor 6 (Bundle 9) 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.