|
| 1 | += Migrating from {productname} 4 to {productname} {release-version} |
| 2 | +:navtitle: Migrating from TinyMCE 4 |
| 3 | +:description: Guidance for migrating from TinyMCE 4 to TinyMCE {release-version} |
| 4 | +:keywords: migration, considerations, premigration, pre-migration |
| 5 | +:release-version: 7.0 |
| 6 | + |
| 7 | + |
| 8 | +== Overview |
| 9 | + |
| 10 | +{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}. |
| 11 | + |
| 12 | +== Key Changes |
| 13 | + |
| 14 | +=== UI Themes and Skins |
| 15 | + |
| 16 | +* **Removed**: modern, lightgray, and mobile themes/skins. |
| 17 | +* **New**: silver theme with oxide skin (supports light and dark variants). see xref:customize-ui.adoc#themes[customize-ui]. |
| 18 | +* **Impact**: Custom v4 skins/themes are incompatible with v{release-version} and must be rewritten using the oxide skin structure. |
| 19 | + |
| 20 | +.Example: |
| 21 | +[source,js] |
| 22 | +---- |
| 23 | +tinymce.init({ |
| 24 | + selector: "textarea", |
| 25 | + skin: "oxide-dark", |
| 26 | + content_css: "dark", |
| 27 | +}); |
| 28 | +---- |
| 29 | + |
| 30 | +=== Plugin Ecosystem |
| 31 | + |
| 32 | +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. |
| 33 | + |
| 34 | +* **Removed Plugins** (no longer available as of {productname} 6.0): |
| 35 | +** `bbcode`, `fullpage`, `legacyoutput`: Deprecated in 5.9.0. Removed in 6.0. |
| 36 | + |
| 37 | +* **Integrated into {productcorename}**: |
| 38 | +** `paste`, `hr`, `noneditable`, `table`, `print`, `colorpicker` and `contextmenu`: These plugins were absorbed into {productcorename} and no longer require separate installation. |
| 39 | +** `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]. |
| 40 | +** `tabfocus`: Removed in 6.0. Keyboard navigation via Tab is now handled by the browser and {productcorename}. |
| 41 | + |
| 42 | +* **Now Premium Only**: |
| 43 | +** `mediaembed`, `tableofcontents`: These features are available through premium plugins. |
| 44 | +** `spellchecker`: Deprecated in 5.9.0. Removed in 6.0. |
| 45 | +*** Use `browser_spellcheck: true` or the premium xref:introduction-to-tiny-spellchecker.adoc[Spell Checker] plugin. |
| 46 | +** `template`: Removed in {release-version}. Replaced by the premium xref:advanced-templates.adoc[Templates] plugin. |
| 47 | +** `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. |
| 48 | + |
| 49 | +==== Plugin Migration Tips |
| 50 | + |
| 51 | +* `contextmenu` (removed in v6): |
| 52 | +** Use browser-native context menus or custom logic. |
| 53 | +** 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. |
| 54 | +* `bbcode` (removed in v6): |
| 55 | +** Implement custom parsing or server-side processing if BBCode support is required. |
| 56 | +* `fullpage` (removed in v6): |
| 57 | +** Use custom templates or server-side logic to handle full HTML documents. |
| 58 | +* `template` (removed in v{release-version}): |
| 59 | +** Use the premium xref:advanced-templates.adoc[advtemplate] plugin or implement custom modal dialogs. |
| 60 | +* `textcolor` (removed in v6): |
| 61 | +** Use the `forecolor` and `backcolor` toolbar buttons for text color functionality. |
| 62 | +* `imagetools`: (removed in v6): |
| 63 | +** Use the premium xref:editimage.adoc[Enhanced Image Editing] or xref:uploadcare.adoc[Image Optimizer Powered by Uploadcare] plugin for image editing capabilities. |
| 64 | + |
| 65 | +==== Toolbar and Menu name changes |
| 66 | + |
| 67 | +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. |
| 68 | + |
| 69 | +{productname} 5 → {productname} 6: |
| 70 | + |
| 71 | +* `formatselect` → `blocks` (toolbar item) |
| 72 | +* `blockformats` → `blocks` (menu item) |
| 73 | +* `styleselect` → `styles` (toolbar item) |
| 74 | +* `formats` → `styles` (menu item) |
| 75 | +* `fontselect` → `fontfamily` (toolbar item) |
| 76 | +* `fontformats` → `fontfamily` (menu item) |
| 77 | +* `fontsizeselect` → `fontsize` (toolbar item) |
| 78 | +* `fontsizes` → `fontsize` (menu item) |
| 79 | +* `imagetools` → `editimage` (plugin and related toolbar items) |
| 80 | +* `toc` → `tableofcontents` (plugin, menu item, and toolbar item) |
| 81 | +* `tocupdate` → `tableofcontentsupdate` (toolbar item) |
| 82 | + |
| 83 | +{productname} 6 → {productname} 7: |
| 84 | + |
| 85 | +* `InsertOrderedList` and `InsertUnorderedList` commands were removed from {productcorename} and are now provided by the `lists` plugin. |
| 86 | +* 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. |
| 87 | + |
| 88 | +Refer to the latest release notes at link:https://www.tiny.cloud/docs/tinymce/latest/release-notes/[latest release notes] for further details. |
| 89 | + |
| 90 | +TIP: Always refer to the latest plugin documentation at xref:plugins.adoc[plugins] for up-to-date availability and migration guidance. |
| 91 | + |
| 92 | +.Example of Toolbar Changes: |
| 93 | +[source,js] |
| 94 | +---- |
| 95 | +tinymce.init({ |
| 96 | + selector: "textarea", |
| 97 | + toolbar: "undo redo | forecolor backcolor | bold italic | alignleft aligncenter alignright alignjustify", |
| 98 | + plugins: ["lists link image table code"] |
| 99 | +}); |
| 100 | +---- |
| 101 | + |
| 102 | +=== Content Structure |
| 103 | + |
| 104 | +* **Removed**: `forced_root_block: false`. |
| 105 | +** **Requirement**: All editor content must be enclosed in block elements (e.g., `<p>`). |
| 106 | + |
| 107 | +.Example: |
| 108 | +[source,js] |
| 109 | +---- |
| 110 | +tinymce.init({ |
| 111 | + selector: "textarea", |
| 112 | + forced_root_block: "p" |
| 113 | +}); |
| 114 | +---- |
| 115 | + |
| 116 | +=== Configuration Changes |
| 117 | + |
| 118 | +* **Removed in {productname} 6.0**: Legacy mobile theme was removed, but mobile-specific configuration is still supported through the `mobile` option. |
| 119 | +* **Default Changes in TinyMCE 7.0**: |
| 120 | +** xref:content-filtering.adoc#sandbox-iframes[`sandbox iframes`]: Now defaults to `true` (adds sandbox attribute to iframes) |
| 121 | +** xref:content-filtering.adoc#convert-unsafe-embeds[`convert_unsafe_embeds`]: Now defaults to `true` (converts object/embed elements to safer alternatives) |
| 122 | +** xref:accessibility.adoc#highlight_on_focus[`highlight_on_focus`]: Now defaults to `true` (adds focus outline to editors) |
| 123 | +* **New Options in {productname} 7.0**: |
| 124 | +** xref:license-key.adoc[`license_key`]: Must be set to `gpl` or a valid license key |
| 125 | +** xref:content-filtering.adoc#sandbox-iframes-exclusions[`sandbox_iframes_exclusions`]: List of URL hosts to exclude from iframe sandboxing |
| 126 | + |
| 127 | +.Example: |
| 128 | +[source,js] |
| 129 | +---- |
| 130 | +tinymce.init({ |
| 131 | + selector: "textarea", |
| 132 | + toolbar: "undo redo | blocks | bold italic | alignleft aligncenter alignright alignjustify | outdent indent | removeformat", |
| 133 | + toolbar_mode: "floating", |
| 134 | + // Required in TinyMCE 7.0 if self-hosting |
| 135 | + license_key: "gpl", |
| 136 | + // Security options now enabled by default in TinyMCE 7.0 |
| 137 | + sandbox_iframes: true, |
| 138 | + convert_unsafe_embeds: true, |
| 139 | + // Optional: exclude specific domains from iframe sandboxing |
| 140 | + sandbox_iframes_exclusions: ["youtube.com", "vimeo.com"], |
| 141 | + // Accessibility improvement, now enabled by default |
| 142 | + highlight_on_focus: true |
| 143 | +}); |
| 144 | +---- |
| 145 | + |
| 146 | +=== Licensing Changes (GPL v2+ and Commercial) |
| 147 | + |
| 148 | +* **Legacy License**: {productname} 4 was licensed under LGPL 2.1. |
| 149 | +* **New License**: {productname} {release-version} is licensed under GPL v2+ or a commercial license. |
| 150 | +* **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. |
| 151 | + |
| 152 | +.Example: |
| 153 | +[source,js] |
| 154 | +---- |
| 155 | +tinymce.init({ |
| 156 | + selector: "textarea", |
| 157 | + license_key: "your-license-key" |
| 158 | +}); |
| 159 | +---- |
| 160 | + |
| 161 | +== Migration Tips |
| 162 | + |
| 163 | +. **Backup and Prepare**: Ensure comprehensive backups before upgrading. |
| 164 | +. **Update Core Initialization**: |
| 165 | +.. Update `theme`, `skin`, and to refect the new oxide theme and skin. |
| 166 | +... 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". |
| 167 | +.. Update `forced_root_block: false` options to `forced_root_block: "p"`. |
| 168 | +.. Consolidate toolbars. |
| 169 | +.. Review new v{release-version} defaults for security settings. |
| 170 | +. **Plugin Migration**: |
| 171 | +.. Remove deprecated plugins from your configuration. |
| 172 | +.. Update renamed plugins (e.g., `spellchecker` → `tinymcespellchecker`). |
| 173 | +.. Verify premium plugins for compatibility. |
| 174 | +. **Custom Code Updates**: |
| 175 | +.. 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]. |
| 176 | +.. Replace v4 API methods like `editor.addButton`, `editor.addMenuItem`, `editor.windowManager.open`. |
| 177 | +.. Update media embed handling (`media_url_resolver` API changes). see xref:media.adoc#media_url_resolver[media_url_resolver]. |
| 178 | +. **CSS Updates**: |
| 179 | +.. 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. |
| 180 | +. **Testing and Deployment**: |
| 181 | +.. Thoroughly test your updated configuration before production deployment. |
| 182 | +.. Validate media, iframe, and content security settings. |
| 183 | + |
| 184 | +== Additional Resources |
| 185 | + |
| 186 | +* link:https://www.tiny.cloud/docs/tinymce/latest/[{productname} {release-version} Documentation] |
| 187 | +* Paid users can link:https://www.tiny.cloud/contact/[contact our Technical Support] team for help. |
| 188 | +* xref:license-key.adoc[License Key Setup] |
| 189 | +* link:https://community.tiny.cloud/[Community Forum] |
| 190 | +* link:https://github.com/tinymce/tinymce/issues[GitHub Issues] |
| 191 | + |
| 192 | +== Helpful Links |
| 193 | + |
| 194 | +To make your upgrade smooth, check the following version-specific migration guides: |
| 195 | + |
| 196 | +* link:https://www.tiny.cloud/docs/tinymce/5/migration-from-4x/[Migrating from {productname} 4 to {productname} 5] |
| 197 | +* link:https://www.tiny.cloud/docs/tinymce/6/migration-from-5x/[Migrating from {productname} 5 to {productname} 6] |
| 198 | +* link:https://www.tiny.cloud/docs/tinymce/latest/migration-from-6x/[Migrating from {productname} 6 to {productname} {release-version}] |
| 199 | + |
| 200 | +These include deeper configuration notes, plugin replacements, and examples. |
| 201 | + |
| 202 | +== Next Steps |
| 203 | + |
| 204 | +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. |
0 commit comments