Update
OXID eShop 7.6 wird mit Visual CMS 12 ausgeliefert — keine manuelle Installation erforderlich. Das Content & Medien Bundle wird automatisch mit dem OXID eShop Update über Composer aktualisiert.
Wenn Sie von einer älteren OXID eShop Version aktualisieren, haben Sie vor dem Update zwei Möglichkeiten:
Auf Ihrer aktuellen Bundle Version bleiben — behalten Sie Ihre vorhandene Visual CMS Version und bleiben Sie kompatibel mit Ihren vorhandenen Inhalten.
Auf Visual CMS 12 aktualisieren — erhalten Sie alle neuen Funktionen; je nach Ausgangsversion sind anschließend Migrationsschritte für vorhandene Inhalte bzw. Anpassungen an eigenen Erweiterungen nötig (siehe unten).
Note
Wenn Sie bereits Visual CMS 11 verwenden, können Sie direkt auf Visual CMS 12 aktualisieren; eine Inhaltsmigration ist nicht erforderlich (siehe Migration von Visual CMS 11 auf 12).
Versionskompatibilität
OXID eShop 7.6 wird mit Visual CMS 12 (Content & Medien Bundle 12) ausgeliefert.
Unter OXID eShop 7.6 werden die Visual CMS Versionen 8, 11 und 12 unterstützt; Version 12 ist die Standardauslieferung.
Um auf einer älteren Bundle-Version zu bleiben, geben Sie die Zielversion in Ihren Composer-Einstellungen vor dem Update an. Details finden Sie in der Update-Anleitung der OXID eShop Dokumentation.
Migration von Visual CMS 11 auf 12
Visual CMS 12 ist für OXID eShop 7.6 entwickelt und setzt Visual CMS 11 fort.
Inhalte: Das Speicherformat der Inhalte hat sich nicht geändert — beim Update von Visual CMS 11 auf 12 ist keine Inhaltsmigration erforderlich. Die mit Visual CMS 12 neu eingeführten Dynamischen Blöcke erfordern für bestehende Shops keine Migration. Eine Ausnahme bilden die individuellen Styles — siehe der folgende Abschnitt „Individuelle Styles“.
Individuelle Styles: Beim Wechsel von 11 auf 12 werden die individuellen Styles der CMS-Inhalte (Feld „Individuelles CSS / SCSS“ im Editor) nicht mehr als LESS, sondern als SCSS interpretiert. Bestehende LESS-Syntax (z. B. @variablen, Mixins) kann abweichend kompiliert werden oder fehlschlagen. Prüfen Sie Ihre Inhalte dafür zunächst ohne Schreibzugriff:
./vendor/bin/oe-console ddoevisualcms:migrate:less-to-scss --dry-run
Der Bericht listet alle Inhalte mit LESS-Anteilen. Ohne --dry-run schreibt der Befehl nur um, wenn das SCSS-Kompilat exakt das bisher gerenderte CSS ergibt; alle Abweichungen meldet er als manuell nachzuarbeiten.
Note
Die Mediathek liefert in dieser Bundle-Version ein Platzhalter-Bild als Fallback mit. Bei einem Update (statt einer Erstinstallation) wird es erst angelegt, wenn Sie das Modul einmal aktivieren:
./vendor/bin/oe-console oe:module:activate ddoemedialibrary
Eine selbst konfigurierte Fallback-Einstellung bleibt dabei unverändert.
Warning
Ein nicht angepasstes eigenes Widget bzw. eine nicht angepasste Erweiterung kann direkt nach dem Update zu einem schwerwiegenden Fehler im Shop führen.
Eigene Widgets und Erweiterungen: Visual CMS 12 enthält Code-Änderungen, die nicht abwärtskompatibel sind. Module, die Visual CMS erweitern, müssen angepasst werden:
Der Controller
ddoevisualcmscontentwird jetzt überservices.yamlregistriert und ist nicht mehr über den ``oxNew``-Prozess erweiterbar.Umbenannte Interfaces:
SaveWidgetsRequestInterface→WidgetsRequestInterface(Erzeugung nun überWidgetsRequestFactoryInterface);ContentServiceInterface/ContentService→ContentPersistenceServiceInterface/ContentPersistenceService. Hinweis: Die NamenContentServiceInterface/ContentServicebezeichnen jetzt eine neue, andere Orchestrator-Klasse (delegiert an den Persistence-Service), nicht die alte — passen Sie Ihre Type-Hints auf das gewünschte Ziel an.Die Twig-Blöcke des Style-Editors heißen von
visualcms_less_editor*jetztvisualcms_style_editor*(nur relevant, wenn Sie den Editordialog selbst angepasst hatten). Zur Content-Seite des LESS→SCSS-Wechsels siehe „Individuelle Styles“ oben.Entfernte Interfaces:
GridFromRequestInterface,VetreeExtensionInterfacesowie das temporäreCore\RequestInterfacedes Moduls (verwenden Sie stattdessen das Framework-Interface).Widget-Picker mit Server-Suche (
SelectFromDataOption) laufen nicht mehr über den entfernten Admin-DispatchVisualCmsAdmin::doShortCodeAction(). Der Parameterdata(Methodenname am Shortcode, z. B.searchArticle) wurde durch das Pflicht-ArgumentapiPathmit einem Routen-Präfix (z. B.api/vcms-shortcode/article) ersetzt. Eigene Shortcodes mit dieser Option benötigen einen eigenen Controller mit<apiPath>/search(JSON-Liste bei Eingabe) und<apiPath>/item(einzelnes Objekt odernull).Die Shortcode-Klassen
TreeView,ActionundArticlesind in eigene Namespaces umgezogen (…\ShortCodeCollection\ShortCode\TreeView\TreeViewusw.). Es werden keine Class-Aliasse bereitgestellt – Referenzen im eigenen Code anpassen.Umstellung (wo injiziert) auf die Framework-Interfaces
RequestInterfaceundSessionInterfacestatt der Legacy-KlassenCore\Request/Core\Session— teils bleibtRegistry-basierter Legacy-Zugriff bestehen;Id::generatestattUtilsObject::generateUIdim Content-Edit-Fluss; sowieShopAdapterInterface::translateStringin Shortcodes.Der Browser-Code des Content-Editors wurde weiter auf TypeScript mit Dependency Injection umgestellt:
grid.js→Grid.ts,VisualEditor.js→VisualEditor.ts,main.js→Main.ts, währendtemplate.jsundpanel.jsin Gruppen typisierter Services aufgespalten wurden; dieeditor.js-Bridge entfällt. Die Storefront-Skripte der Widgets (node_build/js/frontend/, z. B.hero.js,fullwidth.js) sind von der Umstellung nicht betroffen.
Weitere Informationen zu den Erweiterungspunkten finden Sie in der Entwicklerdokumentation.
Migration von Visual CMS 10 auf 11
Visual CMS 11 ist für OXID eShop 7.5 entwickelt und ersetzt Visual CMS 10, es handelt sich also um ein Update innerhalb derselben Shop-Version.
Important
Wenn Sie von Visual CMS 8 oder 9 kommen, müssen Sie nicht zuerst auf Visual CMS 10 aktualisieren — Visual CMS 11 enthält dieselben Migrationsbefehle. Aktualisieren Sie direkt auf Visual CMS 11 (beachten Sie die Einschränkungen des Metapackage 7.5.0) und führen Sie anschließend die unter Migration von Visual CMS 8 beschriebene Inhaltsmigration durch.
Bestehende Inhalte müssen nicht migriert werden — das Speicherformat hat sich seit Visual CMS 9 nicht geändert und es gibt keine neuen Datenbankmigrationen. Shops, die Visual CMS im Standard-Auslieferungszustand verwenden, benötigen für die Migration ihrer Inhalte keine weiteren Schritte. Module, die eigene Widgets bereitstellen oder das Visual CMS-Rendering erweitern, müssen wie unten beschrieben angepasst werden.
Warning
Ein nicht angepasstes eigenes Widget führt direkt nach dem Update zu einem schwerwiegenden Fehler im Shop (Declaration ... must be compatible with ...).
Eigene Widgets
prepareTemplateParams() erhält den Render-Kontext als zusätzliches Argument. Fügen Sie es jedem eigenen Widget hinzu, das diese Methode implementiert oder überschreibt, und reichen Sie es an den übergeordneten Aufruf weiter:
// 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, die BaseShortCode erweitern, ohne prepareTemplateParams() zu überschreiben, benötigen keine Änderung. Informationen zum Render-Kontext finden Sie in der Entwicklerdokumentation.
Erweiterungen des Renderings
Der Render-Kontext wird durch die gesamte Grid-Rendering-Kette gereicht. Daher müssen auch Decorators und Ersetzungen dieser Services angepasst werden:
GridRendererFacadeInterface—renderGrid()erhält dasContent-Objekt nicht mehr als Argument, es ist Teil des Render-Kontexts und über$renderContext->getContent()verfügbarGridItemArrayRendererInterface,GridItemRendererInterface,TemplateParamsCalculatorInterface— der Render-Kontext wird als zusätzliches Argument übergebenVetreeLogicInterface,PreviewServiceInterface— die Variablen des auslösenden Templates werden als zusätzliches Argument übergeben
Migration von Visual CMS 8
Wenn Sie von Visual CMS 8 aktualisieren, verwenden Ihre Inhalte das alte parse Format und müssen in das tree Format migriert werden, um mit Visual CMS 11 oder 12 zu funktionieren.
Inhalte, die bereits im tree Format vorliegen (Visual CMS 9 oder neuer), müssen nicht migriert werden — das Speicherformat hat sich seither nicht geändert.
Warning
Führen Sie vor der Migration eine vollständige Sicherung der Datenbank und des Dateisystems durch. So können Sie die Migrationsschritte sofort rückgängig machen, falls unerwartete Probleme auftreten.
Führen Sie nach dem Update diese Migrationsschritte aus:
Visual CMS Inhalte migrieren — konvertieren Sie von parse zu tree Format (siehe Geänderte Codebasis unten).
Medien-URLs zu IDs konvertieren — für Visual CMS und WYSIWYG-Inhalte (siehe Medien-IDs im Visual CMS und Medien-IDs im WYSIWYG Editor unten).
Die folgenden Abschnitte beschreiben jeden Schritt im Detail.
Geänderte Codebasis
Mit Visual CMS 9, eingeführt in OXID eShop 7.4, wurde die Codebasis der Visual CMS Inhalte von parse auf tree umgestellt. Dies verbessert die Speicherstruktur der Inhalte und bietet eine optimierte und stabile Codebasis für zukünftige Updates.
CMS-Inhalte mit der Zeichenkette veparse funktionieren im Frontend des Shops nicht mehr und können zu Fehlern führen. Daher ist es zwingend erforderlich, diese Inhalte von der parse- in die tree-Struktur zu migrieren. Dies ist ganz einfach mit dem folgenden Befehl der OE-Konsole möglich:
./vendor/bin/oe-console ddoevisualcms:migrate:veparse-to-vetree
Der Befehl konvertiert alle Inhalte, die veparse nutzen, zur neue vetree Struktur. Anschließend können diese wie gewohnt im Visual CMS-Editor bearbeitet werden.
Note
Ist der Befehl ddoevisualcms:migrate:veparse-to-vetree nicht bekannt (Meldung „There are no commands defined in the ddoevisualcms:migrate namespace“), aktivieren Sie die Module erneut — danach steht er zur Verfügung.
CMS-Inhalte, die nur aus reinem HTML bestehen, werden nicht in die neue Struktur migriert. Die Option Widgets deaktivieren und nur Text verwenden ist nach dem Update automatisch aktiv. Dadurch wird sichergestellt, dass die Inhalte weiterhin wie vorgesehen funktionieren. Wenn Sie die Inhalte später mit Widgets bearbeiten möchten, können Sie die Option Widgets deaktivieren und nur Text verwenden deaktivieren und diese dann wie gewohnt modifizieren. Nach dem Speichern werden die Inhalte in der neuen tree-Struktur gespeichert.
Warning
Beim Wechsel zum Widget-Editor wird ein leerer Arbeitsbereich geöffnet. Ihre vorherigen Nur-Text-Inhalte werden beim Speichern überschrieben. Sichern Sie deshalb unbedingt den Text, den Sie behalten möchten, bevor Sie den Modus wechseln.
Einführung von Medien-IDs
Mit der Mediathek 4, eingeführt in OXID eShop 7.4, haben wir Dateipfade im WYSIWYG-Editor und Visual CMS zu Medien-IDs geändert. Dadurch wird sichergestellt, dass die Mediendatei auch nach Namens- oder Pfadänderung gefunden wird. Während die Pfaddefinition auch nach dem Update weiterhin funktioniert, empfehlen wir, vorhandene Inhalte zu konvertieren, um die neue ID-Definition zu verwenden und von den Vorteilen zu profitieren.
Medien-IDs im WYSIWYG Editor
Der WYSIWYG-Editor wird für verschiedene Inhalte im OXID eShop verwendet. Sie können vorhandene Inhalte von Medien-URLs zu IDs konvertieren, indem Sie die folgenden Befehle in der OE-Konsole ausführen:
Note
Der Befehl ddoewysiwyg:migrate:urls-to-ids konvertiert Medien-Referenzen sowohl in Bild-src- als auch in Link-href-Attributen (nicht nur in eigens markierten Bildern). Nach dem Lauf gibt er einen Bericht über alle konvertierten und alle nicht auflösbaren Referenzen aus. Bereits konvertierte Referenzen werden dabei übersprungen und nicht als Fehler gewertet; der Befehl kann daher gefahrlos erneut ausgeführt werden. Referenzen, die sich keiner Mediathek-Datei zuordnen lassen, werden nicht importiert, sondern als nicht auflösbar im Bericht geführt. Externe URLs, Pfade außerhalb der Mediathek und data:-URIs bleiben unverändert (kein Mediathek-Eintrag). Mit der Option --report-file <pfad> wird dieser Bericht als CSV-Datei gespeichert.
Hint
Denken Sie daran, alle Felder für alle Sprachen zu konvertieren, z. B. OXCONTENT, OXCONTENT_1, OXCONTENT_2 usw., wie im ersten Beispiel gezeigt.
Allgemeine Inhalte wie CMS-Seiten:
./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 (...)
Produktbeschreibungen:
./vendor/bin/oe-console ddoewysiwyg:migrate:urls-to-ids oxartextends OXLONGDESC
Kategoriebeschreibungen:
./vendor/bin/oe-console ddoewysiwyg:migrate:urls-to-ids oxcategories OXDESC
Zahlugsartbeschreibungen:
./vendor/bin/oe-console ddoewysiwyg:migrate:urls-to-ids oxpayments OXDESC
Sie können andere WYSIWYG-Inhalte, wie z. B. benutzerdefinierte Datenbankfelder, mit dem Befehl migrieren, indem Sie die korrekten Werte für Folgendes übergeben:
Die Datenbanktabelle mit den zu konvertierenden Daten.
Der spezifische Feldname in der ausgewählten Datenbanktabelle.
Der eindeutige ID-Schlüssel (Primärschlüssel) der Tabelle. Der Standardwert ist
OXID.
./vendor/bin/oe-console ddoewysiwyg:migrate:urls-to-ids <table-name> <field-name> <table-id-key>
Medien-IDs im Visual CMS
Das Visual CMS enthält Widgets für Medien, wie das Bild-Widget oder die Galerie. Sie können die Medienpfade in diesen Widgets einfach konvertieren, indem Sie den folgenden Befehl in der OE-Konsole ausführen:
./vendor/bin/oe-console ddoevisualcms:migrate:urls-to-ids
Note
Beim Karussell-Widget referenziert jede Folie zusätzlich einen Link (Format Medien-ID;Link). ddoevisualcms:migrate:urls-to-ids konvertiert die Medien-ID; prüfen Sie Karussells nach der Migration nach.
Alt-Text-Platzhalter im WYSIWYG Editor
Important
Dieser Befehl steht ab WYSIWYG-Editor 7 zur Verfügung — inklusive des mit OXID eShop 7.6 ausgelieferten WYSIWYG-Editors 8. Er wurde nicht auf WYSIWYG-Editor 6 oder ältere Versionen zurückportiert.
Mit WYSIWYG-Editor 7 können Alt-Texte von Medien-Bildern sprachabhängig aus der Mediathek gezogen werden. Der folgende Befehl ersetzt leere oder fehlende Alt-Attribute in bestehenden Inhalten durch den Platzhalter oeMediaAlt:
./vendor/bin/oe-console ddoewysiwyg:migrate:alt-texts <table-name> <field-name> <table-id-key>
Die Argumente sind identisch zu ddoewysiwyg:migrate:urls-to-ids:
Die Datenbanktabelle mit den zu konvertierenden Daten.
Der spezifische Feldname in der ausgewählten Datenbanktabelle.
Der eindeutige ID-Schlüssel (Primärschlüssel) der Tabelle. Der Standardwert ist
OXID.
Hint
Bestehende, manuell vergebene Alt-Texte werden nicht überschrieben. Der Befehl gibt am Ende eine Liste der Bilder aus, die einen benutzerdefinierten Alt-Text enthalten, damit diese bei Bedarf manuell geprüft werden können.