DOC-3202: Add migration guides for users migrating from TinyMCE 4 | 5 to v7

antora.yml

@@ -40,6 +40,7 @@ asciidoc:
     supportname: Tiny Support
     contactsales: Contact Sales
     betaprogram: Tiny Insights Program
+    productcorename: TinyMCE Core (Open Source)
     #### some plugin names
     prem_skins_icons: Enhanced Skins & Icon Packs
     #### Plan names

modules/ROOT/nav.adoc

@@ -209,6 +209,8 @@
 **** xref:bundling-localization.adoc[UI localizations]
 **** xref:bundling-themes.adoc[Themes]
 ** xref:upgrading.adoc[Upgrading {productname}]
+** 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-froala.adoc[Migrating from Froala]
 ** xref:generate-rsa-key-pairs.adoc[Generate public key pairs]

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 {release-version}
+: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., `<p>`).
+
+.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.