From 561463e34daa5a390003be5e35de648f32809aa8 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Fri, 17 Oct 2025 08:58:04 +1000 Subject: [PATCH 1/2] DOC-3305: Update Migration guides for TinyMCE 8. --- modules/ROOT/nav.adoc | 6 +- modules/ROOT/pages/migration-from-4x.adoc | 204 +++++++++++++++ modules/ROOT/pages/migration-from-5x.adoc | 238 +++++++++++++++++ modules/ROOT/pages/migration-from-6x.adoc | 300 ++++++++++++++++++++++ modules/ROOT/pages/migration-guides.adoc | 73 ++++++ 5 files changed, 820 insertions(+), 1 deletion(-) create mode 100644 modules/ROOT/pages/migration-from-4x.adoc create mode 100644 modules/ROOT/pages/migration-from-5x.adoc create mode 100644 modules/ROOT/pages/migration-from-6x.adoc create mode 100644 modules/ROOT/pages/migration-guides.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index e189dcd8be..3bcc3429cf 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -208,7 +208,11 @@ **** xref:bundling-localization.adoc[UI localizations] **** xref:bundling-themes.adoc[Themes] ** xref:upgrading.adoc[Upgrading {productname}] -** xref:migration-from-7x.adoc[Migrating from {productname} 7] +** xref:migration-guides.adoc[Migration guides] +*** xref:migration-from-4x.adoc[Migrating from {productname} 4] +*** xref:migration-from-5x.adoc[Migrating from {productname} 5] +*** xref:migration-from-6x.adoc[Migrating from {productname} 6] +*** xref:migration-from-7x.adoc[Migrating from {productname} 7] ** xref:migration-from-froala.adoc[Migrating from Froala] ** xref:generate-rsa-key-pairs.adoc[Generate public key pairs] ** xref:understanding-editor-loads.adoc[Understanding editor loads] diff --git a/modules/ROOT/pages/migration-from-4x.adoc b/modules/ROOT/pages/migration-from-4x.adoc new file mode 100644 index 0000000000..4a15c57204 --- /dev/null +++ b/modules/ROOT/pages/migration-from-4x.adoc @@ -0,0 +1,204 @@ += Migrating from {productname} 4 to {productname} {release-version} +:navtitle: Migrating from TinyMCE 4 +:description: Guidance for migrating from TinyMCE 4 to TinyMCE 7 +:keywords: migration, considerations, premigration, pre-migration +:release-version: 7.0 + + +== Overview + +{productname} has evolved significantly from version 4 to version {release-version}, introducing major architectural changes, modern UI improvements, enhanced performance, and better security. This guide outlines the critical breaking changes, recommended migration action steps, and top-level configuration adjustments required to upgrade from {productname} v4 to v{release-version}. + +== Key Changes + +=== UI Themes and Skins + +* **Removed**: modern, lightgray, and mobile themes/skins. +* **New**: silver theme with oxide skin (supports light and dark variants). see xref:customize-ui.adoc#themes[customize-ui]. +* **Impact**: Custom v4 skins/themes are incompatible with v{release-version} and must be rewritten using the oxide skin structure. + +.Example: +[source,js] +---- +tinymce.init({ + selector: "textarea", + skin: "oxide-dark", + content_css: "dark", +}); +---- + +=== Plugin Ecosystem + +The {productname} plugin ecosystem was significantly restructured in version 6.0, with several plugins being removed, folded into the {productcorename}, or reclassified as premium features. The following breakdown clarifies the status of each affected plugin. + +* **Removed Plugins** (no longer available as of {productname} 6.0): +** `bbcode`, `fullpage`, `legacyoutput`: Deprecated in 5.9.0. Removed in 6.0. + +* **Integrated into {productcorename}**: +** `paste`, `hr`, `noneditable`, `table`, `print`, `colorpicker` and `contextmenu`: These plugins were absorbed into {productcorename} and no longer require separate installation. +** `contextmenu`: Deprecated in version 5.0 following the integration of context menu functionality into {productcorename} editor. Removed in version 6.0. For more information, see the link:https://www.tiny.cloud/docs/tinymce/latest/contextmenu/[contextmenu documentation]. +** `tabfocus`: Removed in 6.0. Keyboard navigation via Tab is now handled by the browser and {productcorename}. + +* **Now Premium Only**: +** `mediaembed`, `tableofcontents`: These features are available through premium plugins. +** `spellchecker`: Deprecated in 5.9.0. Removed in 6.0. +*** Use `browser_spellcheck: true` or the premium xref:introduction-to-tiny-spellchecker.adoc[Spell Checker] plugin. +** `template`: Removed in {release-version}. Replaced by the premium xref:advanced-templates.adoc[Templates] plugin. +** `imagetools`: Removed in 6.0. Replaced by the premium xref:editimage.adoc[Enhanced Image Editing] feature, available via the `+editimage+` plugin introduced in TinyMCE 6.0. + +==== Plugin Migration Tips + +* `contextmenu` (removed in v6): +** Use browser-native context menus or custom logic. +** Consider using link:https://www.tiny.cloud/docs/tinymce/latest/apis/tinymce.editor.ui.registry/#addContextMenu[editor.ui.registry.addContextMenu] for custom right-click actions. +* `bbcode` (removed in v6): +** Implement custom parsing or server-side processing if BBCode support is required. +* `fullpage` (removed in v6): +** Use custom templates or server-side logic to handle full HTML documents. +* `template` (removed in v{release-version}): +** Use the premium xref:advanced-templates.adoc[advtemplate] plugin or implement custom modal dialogs. +* `textcolor` (removed in v6): +** Use the `forecolor` and `backcolor` toolbar buttons for text color functionality. +* `imagetools`: (removed in v6): +** Use the premium xref:editimage.adoc[Enhanced Image Editing] or xref:uploadcare.adoc[Image Optimizer Powered by Uploadcare] plugin for image editing capabilities. + +==== Toolbar and Menu name changes + +If you used the following toolbar buttons or menu options, they have changed names across major {productname} versions. Please refer to the release notes for each version for complete migration details. + +{productname} 5 → {productname} 6: + +* `formatselect` → `blocks` (toolbar item) +* `blockformats` → `blocks` (menu item) +* `styleselect` → `styles` (toolbar item) +* `formats` → `styles` (menu item) +* `fontselect` → `fontfamily` (toolbar item) +* `fontformats` → `fontfamily` (menu item) +* `fontsizeselect` → `fontsize` (toolbar item) +* `fontsizes` → `fontsize` (menu item) +* `imagetools` → `editimage` (plugin and related toolbar items) +* `toc` → `tableofcontents` (plugin, menu item, and toolbar item) +* `tocupdate` → `tableofcontentsupdate` (toolbar item) + +{productname} 6 → {productname} 7: + +* `InsertOrderedList` and `InsertUnorderedList` commands were removed from {productcorename} and are now provided by the `lists` plugin. +* Default text pattern triggers were updated to activate on `Space` instead of `Enter`. A `trigger` property was added to configure block-level text pattern behavior. + +Refer to the latest release notes at link:https://www.tiny.cloud/docs/tinymce/latest/release-notes/[latest release notes] for further details. + +TIP: Always refer to the latest plugin documentation at xref:plugins.adoc[plugins] for up-to-date availability and migration guidance. + +.Example of Toolbar Changes: +[source,js] +---- +tinymce.init({ + selector: "textarea", + toolbar: "undo redo | forecolor backcolor | bold italic | alignleft aligncenter alignright alignjustify", + plugins: ["lists link image table code"] +}); +---- + +=== Content Structure + +* **Removed**: `forced_root_block: false`. +** **Requirement**: All editor content must be enclosed in block elements (e.g., `

`). + +.Example: +[source,js] +---- +tinymce.init({ + selector: "textarea", + forced_root_block: "p" +}); +---- + +=== Configuration Changes + +* **Removed in {productname} 6.0**: Legacy mobile theme was removed, but mobile-specific configuration is still supported through the `mobile` option. +* **Default Changes in TinyMCE 7.0**: +** xref:content-filtering.adoc#sandbox-iframes[`sandbox iframes`]: Now defaults to `true` (adds sandbox attribute to iframes) +** xref:content-filtering.adoc#convert-unsafe-embeds[`convert_unsafe_embeds`]: Now defaults to `true` (converts object/embed elements to safer alternatives) +** xref:accessibility.adoc#highlight_on_focus[`highlight_on_focus`]: Now defaults to `true` (adds focus outline to editors) +* **New Options in {productname} 7.0**: +** xref:license-key.adoc[`license_key`]: Must be set to `gpl` or a valid license key +** xref:content-filtering.adoc#sandbox-iframes-exclusions[`sandbox_iframes_exclusions`]: List of URL hosts to exclude from iframe sandboxing + +.Example: +[source,js] +---- +tinymce.init({ + selector: "textarea", + toolbar: "undo redo | blocks | bold italic | alignleft aligncenter alignright alignjustify | outdent indent | removeformat", + toolbar_mode: "floating", + // Required in TinyMCE 7.0 if self-hosting + license_key: "gpl", + // Security options now enabled by default in TinyMCE 7.0 + sandbox_iframes: true, + convert_unsafe_embeds: true, + // Optional: exclude specific domains from iframe sandboxing + sandbox_iframes_exclusions: ["youtube.com", "vimeo.com"], + // Accessibility improvement, now enabled by default + highlight_on_focus: true +}); +---- + +=== Licensing Changes (GPL v2+ and Commercial) + +* **Legacy License**: {productname} 4 was licensed under LGPL 2.1. +* **New License**: {productname} {release-version} is licensed under GPL v2+ or a commercial license. +* **Impact**: The xref:license-key.adoc[License key] option is required as part of your editor configuration if self-hosting {productname}. This requirement does not apply if you are loading {productname} from the cloud. + +.Example: +[source,js] +---- +tinymce.init({ + selector: "textarea", + license_key: "your-license-key" +}); +---- + +== Migration Tips + +. **Backup and Prepare**: Ensure comprehensive backups before upgrading. +. **Update Core Initialization**: +.. Update `theme`, `skin`, and to refect the new oxide theme and skin. +... In {productname} 4, there were multiple themes available including 'modern', 'inlite', and 'mobile'. These themes were removed in {productname} 5 and combined into a single responsive theme called "Silver". +.. Update `forced_root_block: false` options to `forced_root_block: "p"`. +.. Consolidate toolbars. +.. Review new v{release-version} defaults for security settings. +. **Plugin Migration**: +.. Remove deprecated plugins from your configuration. +.. Update renamed plugins (e.g., `spellchecker` → `tinymcespellchecker`). +.. Verify premium plugins for compatibility. +. **Custom Code Updates**: +.. Rewrite custom plugins using the `editor.ui.registry.*` API. see link:https://www.tiny.cloud/docs/tinymce/latest/apis/tinymce.editor.ui.registry/[editor.ui.registry]. +.. Replace v4 API methods like `editor.addButton`, `editor.addMenuItem`, `editor.windowManager.open`. +.. Update media embed handling (`media_url_resolver` API changes). see xref:media.adoc#media_url_resolver[media_url_resolver]. +. **CSS Updates**: +.. Update custom styles to align with the new Oxide standard. While many `+.mce-*+` classes have been replaced with `+.tox-*+` classes, some `+.mce-*+` prefixes remain in use. Review your CSS to ensure compatibility. +. **Testing and Deployment**: +.. Thoroughly test your updated configuration before production deployment. +.. Validate media, iframe, and content security settings. + +== Additional Resources + +* link:https://www.tiny.cloud/docs/tinymce/latest/[{productname} {release-version} Documentation] +* Paid users can link:https://www.tiny.cloud/contact/[contact our Technical Support] team for help. +* xref:license-key.adoc[License Key Setup] +* link:https://community.tiny.cloud/[Community Forum] +* link:https://github.com/tinymce/tinymce/issues[GitHub Issues] + +== Helpful Links + +To make your upgrade smooth, check the following version-specific migration guides: + +* link:https://www.tiny.cloud/docs/tinymce/5/migration-from-4x/[Migrating from {productname} 4 to {productname} 5] +* link:https://www.tiny.cloud/docs/tinymce/6/migration-from-5x/[Migrating from {productname} 5 to {productname} 6] +* link:https://www.tiny.cloud/docs/tinymce/latest/migration-from-6x/[Migrating from {productname} 6 to {productname} {release-version}] + +These include deeper configuration notes, plugin replacements, and examples. + +== Next Steps + +Ensure you follow the migration steps carefully to avoid common issues like missing plugins, broken UI, and unexpected formatting changes. Consider running your updated editor in a staging environment for a complete verification before final deployment. diff --git a/modules/ROOT/pages/migration-from-5x.adoc b/modules/ROOT/pages/migration-from-5x.adoc new file mode 100644 index 0000000000..6ccbed6713 --- /dev/null +++ b/modules/ROOT/pages/migration-from-5x.adoc @@ -0,0 +1,238 @@ += Migrating from {productname} 5 to {productname} {release-version} +:navtitle: Migrating from TinyMCE 5 +:description: Guidance for migrating from TinyMCE 5 to TinyMCE 7 +:keywords: migration, considerations, premigration, pre-migration +:release-version: 7.0 + +== Overview + +{productname} has evolved significantly from version 5 to version {release-version}, introducing architectural improvements, modern UI enhancements, stricter security defaults, and updated plugin structures. This guide outlines the critical breaking changes, recommended migration action steps, and top-level configuration adjustments required to upgrade from {productname} v5 to v{release-version}. + +== Key Changes + +=== UI Themes and Skins + +* **Minor Adjustments**: Oxide-based skins from v5 remain mostly compatible but may require small CSS adjustments for v{release-version}. +* **Impact**: Test custom skins visually, as minor DOM changes can affect layout and styling. +* **Browser Support**: Internet Explorer 11 is no longer supported in v{release-version} (dropped in v6), requiring modern browsers. + +.Example: +[source,js] +---- +tinymce.init({ + selector: "textarea", + skin: "oxide-dark", + content_css: "dark", +}); +---- + +=== Plugin Ecosystem + +The {productname} plugin ecosystem underwent a significant overhaul starting in version 6.0, with many plugins either removed, integrated into the core, or made premium-only. The following summarizes these changes. + +* **Removed Plugins** (no longer available as of {productname} 6.0): +** `bbcode`, `fullpage`, `legacyoutput`: Deprecated in 5.9.0. Removed in 6.0. + +* **Integrated into {productcorename}**: +** `paste`, `hr`, `table`, `noneditable`, `nonbreaking`, `print`, `colorpicker` and `contextmenu`: These plugins were absorbed into {productcorename} and no longer require separate installation. +** `contextmenu`: Deprecated in version 5.0 following the integration of context menu functionality into {productcorename} editor. Removed in version 6.0. For more information, see the link:https://www.tiny.cloud/docs/tinymce/latest/contextmenu/[contextmenu documentation]. +** `tabfocus`: Removed in 6.0. Keyboard navigation via Tab is now handled by the browser and {productcorename}. + +* **Now Premium Only**: +** `mediaembed`, `tableofcontents`: These features are available through premium plugins. +** `spellchecker`: Deprecated in 5.9.0. Removed in 6.0. +*** Use `browser_spellcheck: true` or the premium xref:introduction-to-tiny-spellchecker.adoc[Spell Checker] plugin. +** `template`: Removed in {release-version}. Replaced by the premium xref:advanced-templates.adoc[Templates] plugin. +** `imagetools`: Removed in 6.0. Replaced by the premium xref:editimage.adoc[Enhanced Image Editing] feature, available via the `+editimage+` plugin introduced in TinyMCE 6.0. +** `toc`: Renamed to `tableofcontents` and now premium. +** `advtemplate`: Replaces the `template` plugin for advanced templating use cases. + +==== Plugin Migration Examples + +* `contextmenu` (removed in v6): +** Use browser-native context menus or custom logic. +** Consider using link:https://www.tiny.cloud/docs/tinymce/latest/apis/tinymce.editor.ui.registry/#addContextMenu[editor.ui.registry.addContextMenu] for custom right-click actions. +* `bbcode` (removed in v6): +** Implement custom parsing or server-side processing if BBCode support is required. +* `fullpage` (removed in v6): +** Use custom templates or server-side logic to handle full HTML documents. +* `template` (removed in v{release-version}): +** Use the premium xref:advanced-templates.adoc[advtemplate] plugin or implement custom modal dialogs. +* `textcolor` (removed in v6): +** Use the `forecolor` and `backcolor` toolbar buttons for text color functionality. +* `imagetools`: (removed in v6): +** Use the premium xref:editimage.adoc[Enhanced Image Editing] or xref:uploadcare.adoc[Image Optimizer Powered by Uploadcare] plugin for image editing capabilities. + +==== Toolbar and Menu name changes + +If you used the following toolbar buttons or menu options, they have changed names across major {productname} versions. Please refer to the release notes for each version for complete migration details. + +{productname} 5 → {productname} 6: + +* `formatselect` → `blocks` (toolbar item) +* `blockformats` → `blocks` (menu item) +* `styleselect` → `styles` (toolbar item) +* `formats` → `styles` (menu item) +* `fontselect` → `fontfamily` (toolbar item) +* `fontformats` → `fontfamily` (menu item) +* `fontsizeselect` → `fontsize` (toolbar item) +* `fontsizes` → `fontsize` (menu item) +* `imagetools` → `editimage` (plugin and related toolbar items) +* `toc` → `tableofcontents` (plugin, menu item, and toolbar item) +* `tocupdate` → `tableofcontentsupdate` (toolbar item) + +{productname} 6 → {productname} 7: + +* `InsertOrderedList` and `InsertUnorderedList` commands were removed from {productcorename} and are now provided by the `lists` plugin. +* Default text pattern triggers were updated to activate on `Space` instead of `Enter`. A `trigger` property was added to configure block-level text pattern behavior. + +Refer to the latest release notes at link:https://www.tiny.cloud/docs/tinymce/latest/release-notes/[latest release notes] for further details. + +TIP: Always refer to the latest plugin documentation at xref:plugins.adoc[plugins] for up-to-date availability and migration guidance. + +.Example of Toolbar Changes: +[source,js] +---- +tinymce.init({ + selector: "textarea", + toolbar: "undo redo | forecolor backcolor | bold italic | alignleft aligncenter alignright alignjustify", + plugins: ["lists link image table code"] +}); +---- + +=== Content Structure + +* **Removed**: `forced_root_block: false`. +** **Requirement**: All editor content must be enclosed in block elements (e.g., `

`). + +.Example: +[source,js] +---- +tinymce.init({ + selector: "textarea", + forced_root_block: "p" +}); +---- + +=== Configuration Changes + +* **Removed in {productname} 6.0**: Legacy mobile theme was removed, but mobile-specific configuration is still supported through the `mobile` option. + +* **UI API Updates**: +** Update custom plugins to use `+editor.ui.registry.*+`. +** Replace deprecated methods like `+editor.addButton+`, `+editor.addMenuItem+`, and `+editor.windowManager.open+`. + +* **Promise-Based Methods**: +** `media_url_resolver` now requires a `Promise` return for asynchronous handling. + +* **Removed Options**: +** `force_hex_color` has been removed. Use standard CSS color declarations. +** `table_responsive_width` replaced by `table_sizing_mode`. + +* **Default Changes in TinyMCE 7.0**: +** xref:content-filtering.adoc#sandbox-iframes[`sandbox iframes`]: Now defaults to `true` (adds sandbox attribute to iframes) +** xref:content-filtering.adoc#convert-unsafe-embeds[`convert_unsafe_embeds`]: Now defaults to `true` (converts object/embed elements to safer alternatives) +** xref:accessibility.adoc#highlight_on_focus[`highlight_on_focus`]: Now defaults to `true` (adds focus outline to editors) + +* **New Options in {productname} 7.0**: +** xref:license-key.adoc[`license_key`]: Must be set to `gpl` or a valid license key +** xref:content-filtering.adoc#sandbox-iframes-exclusions[`sandbox_iframes_exclusions`]: List of URL hosts to exclude from iframe sandboxing + +.Example: +[source,js] +---- +tinymce.init({ + selector: "textarea", + toolbar: "undo redo | blocks | bold italic | alignleft aligncenter alignright alignjustify | outdent indent | removeformat", + toolbar_mode: "floating", + license_key: "gpl", // Required in TinyMCE 7.0 if self-hosting + // Security options now enabled by default in TinyMCE 7.0 + sandbox_iframes: true, + convert_unsafe_embeds: true, + // Optional: exclude specific domains from iframe sandboxing + sandbox_iframes_exclusions: ["youtube.com", "vimeo.com"], + // Accessibility improvement, now enabled by default + highlight_on_focus: true +}); +---- + +TIP: For up-to-date plugin availability and configuration references, see link:https://www.tiny.cloud/docs/plugins/. + +[NOTE] +==== +Refer to version-specific release notes for changes in toolbar button names and command availability across versions 5, 6, and 7. For example: + +{productname} 5 → {productname} 6: + +* `formatselect` → `blocks` +* `styleselect` → `styles` +* `fontselect` → `fontfamily` +* `fontsizeselect` → `fontsize` +* `imagetools` → `editimage` +* `toc` → `tableofcontents` + +{productname} 6 → {productname} 7: + +* `InsertOrderedList` / `InsertUnorderedList` commands removed from {productcorename} (use `lists` plugin). +* Default text pattern triggers updated from `Enter` to `Space`, configurable via `trigger`. +==== + +=== Licensing Changes (GPL v2+ and Commercial) + +* **Legacy License**: {productname} 5 was licensed under LGPL 2.1. +* **New License**: {productname} {release-version} is licensed under GPL v2+ or a commercial license. +* **Impact**: The xref:license-key.adoc[License key] option is required as part of your editor configuration if self-hosting {productname}. This requirement does not apply if you are loading {productname} from the cloud. + +.Example: +[source,js] +---- +tinymce.init({ +selector: "textarea", +license_key: "your-license-key" +}); +---- + +== Migration Tips + +. **Backup and Prepare**: Ensure comprehensive backups before upgrading. +. **Update Core Initialization**: +.. Update `theme`, `skin`, and to refect the new oxide theme and skin. +... In {productname} 4, there were multiple themes available including 'modern', 'inlite', and 'mobile'. These themes were removed in {productname} 5 and combined into a single responsive theme called "Silver". +.. Update `forced_root_block: false` options to `forced_root_block: "p"`. +.. Consolidate toolbars. +.. Review new v{release-version} defaults for security settings. +. **Plugin Migration**: +.. Remove deprecated plugins from your configuration. +.. Update renamed plugins (e.g., `spellchecker` → `tinymcespellchecker`). +.. Verify premium plugins for compatibility. +. **Custom Code Updates**: +.. Rewrite custom plugins using the `editor.ui.registry.*` API. +.. Replace v5 API methods like `editor.addButton`, `editor.addMenuItem`, `editor.windowManager.open`. +.. Update media embed handling (`media_url_resolver` API changes). see xref:media.adoc#media_url_resolver[media_url_resolver]. +. **CSS Updates**: +.. Update custom styles to align with the new Oxide standard. While many `+.mce-*+` classes have been replaced with `+.tox-*+` classes, some `+.mce-*+` prefixes remain in use. Review your CSS to ensure compatibility. +. **Testing and Deployment**: +.. Thoroughly test your updated configuration before production deployment. +.. Validate media, iframe, and content security settings. + +== Additional Resources + +* link:https://www.tiny.cloud/docs/tinymce/latest/[{productname} {release-version} Documentation] +* Paid users can link:https://www.tiny.cloud/contact/[contact our Technical Support] team for help. +* xref:license-key.adoc[License Key Setup] +* link:https://community.tiny.cloud/[Community Forum] +* link:https://github.com/tinymce/tinymce/issues[GitHub Issues] + +== Helpful Links + +To make your upgrade smooth, check the following version-specific migration guides: + +* link:https://www.tiny.cloud/docs/tinymce/5/migration-from-4x/[Migrating from {productname} 4 to {productname} 5] +* link:https://www.tiny.cloud/docs/tinymce/6/migration-from-5x/[Migrating from {productname} 5 to {productname} 6] +* link:https://www.tiny.cloud/docs/tinymce/latest/migration-from-6x/[Migrating from {productname} 6 to {productname} {release-version}] + +These include deeper configuration notes, plugin replacements, and examples. + +== Next Steps + +Ensure you follow the migration steps carefully to avoid common issues like missing plugins, broken UI, and unexpected formatting changes. Consider running your updated editor in a staging environment for a complete verification before final deployment. diff --git a/modules/ROOT/pages/migration-from-6x.adoc b/modules/ROOT/pages/migration-from-6x.adoc new file mode 100644 index 0000000000..3ba9531ac5 --- /dev/null +++ b/modules/ROOT/pages/migration-from-6x.adoc @@ -0,0 +1,300 @@ += Migrating from {productname} 6 to {productname} {release-version} +:navtitle: Migrating from TinyMCE 6 +:description: Guidance for migrating from TinyMCE 6 to TinyMCE 7 +:keywords: migration, considerations, premigration, pre-migration +:release-version: 7.0 + +The process for setting up a basic {productname} {release-version} instance is the same as {productname} 6. + +Most configuration changes in {productname} {release-version} only affect complex use cases, such as custom plugins and customized user interface components. + +This documentation details the changes in {productname} {release-version} that integrators using {productname} 6 should consider when upgrading. + +NOTE: For support related to migration, please contact https://support.tiny.cloud/hc/en-us/requests/new[Tiny Support]. + +Open Source users: please report issues in the https://github.com/tinymce/tinymce/[TinyMCE GitHub Repository]. + +[[overview]] +== Overview + +* xref:commands-and-apis[Commands and APIs] +* xref:options[Options] +* xref:plugins[Plugins] +* xref:ui-and-ux[UI and UX] +* xref:security[Security] + +[[tinymce-70-core-changes]] +== {productname} {productmajorversion} core changes. + +For additional details on {productname} {release-version} changes, see xref:7.0-release-notes.adoc[{productname} {release-version} release notes]. + + +[[commands-and-apis]] +== Commands and APIs + +This section documents the core changes made to {productname} 7.0. + +=== Changed + +==== Removed `InsertOrderedList` and `InsertUnorderedList` commands from {productname} core. + +Previously, native list commands were executable through various text patterns, leading to undefined browser behavior due to the embedded list code. + +In {productname} 7.0, these commands are only available in the xref:lists.adoc[*Lists plugin*]. + +.Example adding list plugin +[source, js] +---- +tinymce.init({ + selector: "textarea", + plugins: [ + "lists" + ], + toolbar: "bullist numlist", +}); +---- + +[[remove-trailing-brs-property-removal-from-domparser]] +==== `remove_trailing_brs` property removal from DomParser + +The `remove_trailing_brs` setting was removed from the xref:apis/tinymce.html.domparser.adoc[`DomParser` API], after being deprecated in link:https://www.tiny.cloud/docs/tinymce/6/6.5.1-release-notes/#inserting-two-tables-consecutively-without-focus-in-the-editor-resulted-in-the-second-table-being-inserted-at-the-wrong-position[{productname} 6.5]. + +[[changes-to-text-pattern-defaults-to-trigger-on-space-key-press]] +==== Changes to `text-pattern` defaults to trigger on `Space` key press. + +Applying basic formats such as headings, lists, bold and italic from typing them out in Markdown syntax is considered a must-have for WYSIWYG Editor's. In previous versions, {productname} would only apply these formats once the user presses the `Enter` key. + +{productname} {release-version} updates the default behavior of the `text-patterns` option to apply these formats when the user presses the `Space` key. + +[NOTE] +The previous default `text_patterns` behavior, applying the format on an `Enter` key press, can be configured by replacing the `trigger` property with the value `'space'`. Learn more about how you can configure `text_patterns` in the xref:7.0-release-notes.adoc#a-new-trigger-property-for-block-text-pattern-configurations-allowing-pattern-activation-with-either-space-or-enter-keys[{release-version} Release notes] + +.Updated default text patterns +[source, ts] +---- +default: [ + { start: '#', format: 'h1', trigger: 'space' }, + { start: '##', format: 'h2', trigger: 'space' }, + { start: '###', format: 'h3', trigger: 'space' }, + { start: '####', format: 'h4', trigger: 'space' }, + { start: '#####', format: 'h5', trigger: 'space' }, + { start: '######', format: 'h6', trigger: 'space' }, + { start: '1.', cmd: 'InsertOrderedList', trigger: 'space' }, + { start: '*', cmd: 'InsertUnorderedList', trigger: 'space' }, + { start: '-', cmd: 'InsertUnorderedList', trigger: 'space' }, + { start: '>', cmd: 'mceBlockQuote', trigger: 'space' }, + { start: '---', cmd: 'InsertHorizontalRule', trigger: 'space' }, +] +---- + +For information on the **text_patterns**, see xref:content-behavior-options.adoc#text_patterns[Text Patterns]. + +=== Removed + +==== The autocompleter `ch` configuration property has been removed. Use the `trigger` property instead. +// #TINY-8929 + +Previously, the `ch` configuration property was used to specify the character that would trigger the autocompleter. + +This property was deprecated in link:https://www.tiny.cloud/docs/tinymce/6/6.2-release-notes/#deprecated[{productname} 6.2] and has been removed in {productname} 7.0. Instead, use the `trigger` property to specify the `string` that will trigger the autocompleter. + +If `+editor.ui.registry.addAutocompleter(name, options)+` was used in your configuration, updating your configuration from `ch: '',` to `trigger: '',` is required. + +NOTE: The new `trigger` option can handle multiple character strings as the trigger. + +For more information, visit the updated xref:autocompleter.adoc[Autocompleter] documentation. + +[[options]] +== Options + +=== Changed + +[[highlight-on-focus]] +==== `highlight_on_focus` + +Previously, the default value for the editor configuration option `highlight_on_focus` was set to `false` by default. In {productname} {release-version} this option is now by default set to `true`. + +As a result, the focus outline for the editor will by default be displayed when the focus is on the editor. + +Customers who have created their own custom skins, or have implemented their own outline and do not intend to use the default will need to add `highlight_on_focus: false` to their {productname} configuration. + +[NOTE] +This change does not impact editors using inline mode. + +=== Removed + +[[force-hex-color]] +==== `force_hex_color` + +Previously in {productname} 6, all colors in the content HTML were set to use `rgb` values by default. As the common practice is using `hex` values, this change has been reverted. + +.Example +[source, html] +---- + +// RGB value +

Hello red color

+// RGBA value +

Hello red color

+// HSL value +

Hello red color

+// RGB value with alpha parameter +

Hello red color

+// RGB value with calculation +

Hello red color

+ + +

Hello red color

+

Hello red color

+

Hello red color

+// non-absolute values and absolute values with calculation will not be converted to HEX color +

Hello red color

+

Hello red color

+---- + +In {productname} 7.0, only RGB values in absolute value like `rgb(255, 255, 255)` are converted to HEX values. Other RGB formats such as those with non-absolute values, and color options such as RGBA and HSL remain unchanged. The `forced_hex_color` option has been removed. + +[[plugins]] +== Plugins + +=== Changed + +==== Changed the `media_url_resolver` option to use promises. +// #TINY-9154 + +In {productname} 6 and earlier, the `media_url_resolver` option provided `resolve` and `reject` callbacks, rather than a Promise. In certain circumstances this implementation resulted in unexpected behavior. + +In {productname} 7, the `media_url_resolver` option now requires a Promise to be returned. + +.Old expected value implementing callbacks +[source,js] +---- +tinymce.init({ + selector: 'textarea', // change this value according to your HTML + plugins: 'media', + toolbar: 'media', + media_url_resolver: (data, resolve, reject) => { + if (data.url.indexOf('YOUR_SPECIAL_VIDEO_URL') !== -1) { + const embedHtml = ``; + resolve({ html: embedHtml }); + } else { + resolve({ html: '' }); + } + } +}); +---- + +.New expected value returning a Promise +[source,js] +---- +tinymce.init({ + selector: 'textarea', // change this value according to your HTML + plugins: 'media', + toolbar: 'media', + media_url_resolver: (data) => { + return new Promise((resolve) => { + if (data.url.indexOf('YOUR_SPECIAL_VIDEO_URL') !== -1) { + const embedHtml = ``; + resolve({ html: embedHtml }); + } else { + resolve({ html: '' }); + } + }); + } +}); +---- + +[NOTE] +Integrators will be required to update there configuration to the reflect the new `media_url_resolver` changes. + +For more information on using `+media_url_resolver+`, see xref:media.adoc#media_url_resolver[media_url_resolver] + + +[[removed-plugins]] +=== Removed Plugins + +In {productname} {release-version} the below plugin has been removed. + +[[removed-plugins-template-plugin]] +==== Removed open-source `Template` plugin + +The open-source `Template` plugin and associated config options have been removed in {productname} 7.0. + +Customers using the `template` plugin are recommended to upgrade to the premium **Templates** plugin which provides enhanced template functionality. For more information on the **Templates** plugin, see: xref:advanced-templates.adoc[Templates] for more details. + +Removed **Template** options: + +* `template_cdate_classes` +* `template_cdate_format` +* `template_mdate_classes` +* `template_mdate_format` +* `template_replace_values` +* `template_preview_replace_values` +* `template_selected_content_classes` + + +[[ui-and-ux]] +== UI and UX + +=== Changed + +[[ui-and-ux-improved-how-styles-are-applied-when-resizing-rows-and-columns-for-tables]] +==== Changed how cell and row heights are applied to tables. + +Previously, {productname} added numerous `height` styles when resizing table rows such as on the `table` element, `tr` elements, and `td` elements. This resulted in unnecessarily verbose HTML output. + +{productname} {release-version} addresses this by making a couple of changes: + +* The height input field has been removed from the "Cell Properties" dialog. Now, the "Row Properties" dialog is the only way to update row heights. +* When a table is resized using the resize handles or the "Row properties" dialog, existing `height` styles will be stripped from `td/th` elements where applicable and only applied to the `table` element and `tr` elements. + +[NOTE] +{productname} {release-version} does not provide any fallback to revert to the old behavior. + +=== Removed + +[[ui-and-ux-force-notifications-to-have-a-close-button]] +==== Force notifications to have a close button + +In previous versions of {productname}, xref:creating-custom-notifications.adoc[notifications] were able to be displayed without a close button (`X`). Accessibility is an important component of the editor, and when this button is not in a notification, that notification cannot be closed via keyboard navigation. + +As of {productname} 7.0, the `closeButton` property has been removed from the xref:creating-custom-notifications.adoc[notification API], with all notifications now displaying a visible `closeButton`. This is to allow notifications to be closed using the `Tab` key. + +[[security]] +== Security + +=== Changed + +[[sandbox-iframes-option]] +==== `sandbox_iframes` + +In {productname} 6.8.1, the xref:content-filtering.adoc#sandbox-iframes[sandbox iframes] editor option was introduced to allow iframes to be sandboxed by default when inserted into the editor. + +In {productname} 7.0, the default for `+sandbox_iframes+` will change from `false` to `true`, meaning that all `+iframe+` elements inserted into the editor will be given the `sandbox=""` attribute by default, preventing most actions, including scripting and same-origin access, which may break existing editor content or produce undesirable effects. + +To prevent any expected iframes from being sandboxed, we recommend adding the source domains of such iframes to the new xref:content-filtering.adoc#sandbox-iframes-exclusions[`+sandbox_iframes_exclusions+`] option list, and including the domains in the default list where necessary. To prevent all iframes from being sandboxed, set the option `+sandbox_iframes+` to `+false+` in your editor configuration. + +For further details on the `+sandbox_iframes+` option, see the xref:content-filtering.adoc#sandbox-iframes[the content filtering options], or refer to the xref:security.adoc#sandbox-iframes[security guide], or the link:https://www.tiny.cloud/docs/tinymce/6/6.8.1-release-notes/#new-sandbox_iframes-option-that-controls-whether-iframe-elements-will-be-added-a-sandbox-attribute-to-mitigate-malicious-intent[{productname} 6.8.1 release notes]. + + +[[convert-unsafe-embeds-option]] +==== `convert_unsafe_embeds` + +In {productname} 6.8.1, xref:content-filtering.adoc#convert-unsafe-embeds[convert_unsafe_embeds] editor option was introduced to allow `+object+` and `+embed+` elements to be converted by default to the correct element, respective of the MIME type, automatically when inserted into the editor. + +In {productname} 7.0, the default value for `+convert_unsafe_embeds+` will change from `false` to `true`, meaning that all `+object+` and `+embed+` tags will automatically be converted to different elements when inserted to the editor. + +{productname} has a configuration option that converts object tags to modern equivalents such as `,