`). + +.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..1b762d8b8b --- /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 {release-version} +: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.