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.

Version Compatibility

OXID eShop 7.5 supports three Visual CMS versions in parallel:

Visual CMS 10 — newest (Content & Media Bundle 10, recommended)
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)

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 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.

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.