diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index e189dcd8be..0b0b7f7f1f 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -208,8 +208,17 @@ **** 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-from-froala.adoc[Migrating from Froala] +** xref:migration-guides.adoc[Migration guides] +*** Direct Migration Guides to Latest Major Version (8) +**** xref:migration-from-4x-to-8x.adoc[Migrating from 4 to 8] +**** xref:migration-from-5x-to-8x.adoc[Migrating from 5 to 8] +**** xref:migration-from-6x-to-8x.adoc[Migrating from 6 to 8] +**** xref:migration-from-7x.adoc[Migrating from 7 to 8] +*** Legacy Step-by-Step Migration Guides +**** xref:migration-from-4x.adoc[Migrating from 4 to 7] +**** xref:migration-from-5x.adoc[Migrating from 5 to 7] +**** xref:migration-from-6x.adoc[Migrating from 6 to 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] * xref:examples.adoc[Examples] diff --git a/modules/ROOT/pages/creating-an-icon-pack.adoc b/modules/ROOT/pages/creating-an-icon-pack.adoc index 4ec946f9cd..05e0093e3a 100644 --- a/modules/ROOT/pages/creating-an-icon-pack.adoc +++ b/modules/ROOT/pages/creating-an-icon-pack.adoc @@ -31,7 +31,7 @@ An icon pack only **requires** the custom icons to be included; the default {pro {productname} loads icon packs from the path `+TINYMCE_BASE/icons/${iconPackName}/icons.js+`, where: * `TINYMCE_BASE` is the {productname} root directory (the directory containing `tinymce.min.js`). -* `${iconPackName}` is the name of the icon pack. +* `+${iconPackName}+` is the name of the icon pack. **Example Directory Structure:** ---- diff --git a/modules/ROOT/pages/migration-from-4x-to-8x.adoc b/modules/ROOT/pages/migration-from-4x-to-8x.adoc new file mode 100644 index 0000000000..2a45b591c3 --- /dev/null +++ b/modules/ROOT/pages/migration-from-4x-to-8x.adoc @@ -0,0 +1,721 @@ += Migrating from {productname} 4 to {productname} {productmajorversion} +:navtitle: Migrating from TinyMCE 4 to 8 +:description: Guidance for migrating from TinyMCE 4 to TinyMCE 8 +:keywords: migration, considerations, premigration, pre-migration +:release-version: 8.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 comprehensive 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}. + +This guide provides a complete migration path from TinyMCE 4 to TinyMCE 8, covering all changes across versions 5, 6, 7, and 8 in a single comprehensive document. + +== 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 across versions 5, 6, and 7, with several plugins being removed, folded into the {productname} core, 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. +** `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. +** `textcolor`: Removed in 6.0. Use the premium Color Picker plugin instead. + +* **Integrated into {productname} core**: +** `paste`, `hr`, `noneditable`, `table`, `print`, `colorpicker` and `contextmenu`: These plugins were absorbed into {productname} core and no longer require separate installation. See xref:copy-and-paste.adoc[Copy and Paste], xref:non-editable-content-options.adoc[Non-editable Content], xref:table.adoc[Table], and xref:contextmenu.adoc[Context Menu] for more information. +** `contextmenu`: Deprecated in version 5.0 following the integration of context menu functionality into {productname} core 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 {productname} core. + +* **Now Premium Only**: +** `mediaembed`, `tableofcontents`: These features are available through premium plugins. See xref:introduction-to-mediaembed.adoc[Media Embed] and xref:tableofcontents.adoc[Table of Contents] for more information. +** `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. +** `advtemplate`: Replaces the `template` plugin for advanced templating use cases. +** `template`: Removed in 7.0. Replaced by the premium xref:advanced-templates.adoc[Templates] plugin. + +==== 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 v7): +** 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 {productname} core and are now provided by the xref:lists.adoc[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. + +{productname} 7 → {productname} 8: + +* Several API methods have been deprecated or removed (see the API Changes section below for details) +* License key system has been updated with new format requirements +* DOMPurify sanitization has been strengthened + +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 +* **New Options in {productname} 8.0**: +** Enhanced license key system with new format requirements +** Stricter DOMPurify sanitization with `SAFE_FOR_XML` enabled by default +** New `crossorigin` configuration option for cross-origin resource loading + +.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 8.0 if self-hosting + license_key: "T8LK:...", // New format required + // 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, + // New in TinyMCE 8.0: Cross-origin resource loading + crossorigin: (url, resourceType) => 'anonymous' +}); +---- + +=== 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. + +[IMPORTANT] +==== +**License Key System Update in TinyMCE 8** + +TinyMCE 8 introduces a new license key system that requires immediate attention: + +* **New Format**: License keys now use the prefix `T8LK:` for commercial licenses or `GPL+T8LK:` for GPL with Premium Features +* **Mandatory Requirement**: Self-hosted deployments now require a valid license key; without one, the editor will be set to `readonly` +* **License Key Manager**: Self-hosted commercial deployments require the new License Key Manager addon + +For complete details, see xref:migration-from-7x.adoc#license-key-system-update[License Key System Update] in the 7→8 migration guide. +==== + +.Example: +[source,js] +---- +tinymce.init({ + selector: "textarea", + license_key: "T8LK:your-license-key" // New format required +}); +---- + +=== API Changes + +Several API methods have been deprecated or removed across versions 5-8. Key changes include: + +==== Deprecated in TinyMCE 8 + +===== editor.selection.setContent +// #TINY-12109 + +The `editor.selection.setContent` API has been deprecated and will be removed in {productname} 9. + +*Impact*: This change simplifies content manipulation by consolidating insertion methods. + +**Migration steps:** + + +To replace `editor.selection.setContent`, use `editor.insertContent` instead. The new method is more consistent with other content manipulation methods in {productname}. + +.Example Usage +[source,javascript] +---- +// Deprecated in TinyMCE 8, will be removed in 9 +editor.selection.setContent('

New content

'); + +// Recommended replacement +editor.insertContent('

New content

'); +---- + +===== fire() method +// #TINY-12012, ref TINY-8102 + +The `fire()` method has been replaced by `dispatch()` for event handling. The `fire()` method will be removed in {productname} 9 to avoid confusion with its name. + +[source, javascript] +---- +// Deprecated in TinyMCE 8, will be removed in 9 +// Old approach for dispatching custom events +editor.fire('someEvent'); + +// New approach for dispatching custom events +editor.dispatch('someEvent'); +---- + +===== editor.documentBaseUrl +// #TINY-12182 + +The undocumented `editor.documentBaseUrl` property has been removed. + +.Example Usage +[source,javascript] +---- +// Removed in TinyMCE 8 +console.log('documentBaseUrl', editor.documentBaseUrl); + +// Use this instead +console.log('documentBaseURI', editor.documentBaseURI.getURI()); +---- + +TIP: Use `editor.documentBaseURI.getURI()` for all base URL operations. + +===== skipFocus and skip_focus Consolidation (v8) + +The `skipFocus` and `skip_focus` options for the `ToggleToolbarDrawer` command have been consolidated into a single, more consistent argument in TinyMCE 8.0. + +**Impact:** + + +* Reduces API complexity +* Clarifies intended behavior +* Requires updating command calls + +**Migration Steps:** + +1. Locate all instances of `ToggleToolbarDrawer` command usage +2. Replace `skip_focus` with `skipFocus` in command parameters +3. Test toolbar drawer behavior + +.Example: +[source,js] +---- +// Old TinyMCE 7 usage +editor.execCommand('ToggleToolbarDrawer', false, null, { skip_focus: true }); + +// New TinyMCE 8 usage +editor.execCommand('ToggleToolbarDrawer', false, { skipFocus: true }); +---- + +==== Removed Methods + +===== Legacy API Methods (removed in v6) +** `editor.addButton`, `editor.addMenuItem`, `editor.windowManager.open` (replaced by `editor.ui.registry.*` API) + +===== Autocompleter `ch` property (removed in v7) +// #TINY-8929 + +The `ch` configuration property was removed in {productname} 7.0. Use the `trigger` property instead. + +[source, javascript] +---- +// Old approach (removed in v7) +editor.ui.registry.addAutocompleter('myAutocompleter', { + ch: '@', + // ... other options +}); + +// New approach +editor.ui.registry.addAutocompleter('myAutocompleter', { + trigger: '@', + // ... other options +}); +---- + +===== remove_trailing_brs property (removed in v7) + +The `remove_trailing_brs` setting was removed from the DomParser API in {productname} 7.0, after being deprecated in {productname} 6.5. + +===== Text Pattern Changes (v7) + +TinyMCE 7.0 updated the default behavior of `text_patterns` to apply formats when the user presses the `Space` key instead of `Enter`. + +**Impact:** + +* Markdown-style formatting now triggers on Space key press +* Previous Enter key behavior can be restored by configuring `trigger: 'enter'` +* This affects all text patterns including headings, lists, blockquotes, and horizontal rules + +**Migration Steps:** + +1. Test existing text pattern behavior +2. Update configurations if Enter key triggering is required +3. Review user experience with new Space key triggering +4. Consider updating user documentation about text pattern behavior + +.Example: +[source,js] +---- +// Default TinyMCE 7+ behavior (Space key trigger) +tinymce.init({ + selector: "textarea", + text_patterns: [ + { start: '#', format: 'h1', trigger: 'space' }, + { start: '##', format: 'h2', trigger: 'space' }, + { start: '1.', cmd: 'InsertOrderedList', trigger: 'space' }, + { start: '*', cmd: 'InsertUnorderedList', trigger: 'space' }, + { start: '>', cmd: 'mceBlockQuote', trigger: 'space' } + ] +}); + +// Restore previous behavior (Enter key trigger) +tinymce.init({ + selector: "textarea", + text_patterns: [ + { start: '#', format: 'h1', trigger: 'enter' }, + { start: '##', format: 'h2', trigger: 'enter' }, + { start: '1.', cmd: 'InsertOrderedList', trigger: 'enter' }, + { start: '*', cmd: 'InsertUnorderedList', trigger: 'enter' }, + { start: '>', cmd: 'mceBlockQuote', trigger: 'enter' } + ] +}); +---- + +===== Autocompleter Configuration Changes (v7) + +The `ch` configuration property for autocompleters has been removed. Use the `trigger` property instead. + +**Migration Steps:** + +1. Replace `ch: ''` with `trigger: ''` in autocompleter configurations +2. Test autocompleter functionality +3. Update any custom autocompleter implementations + +.Example: +[source,js] +---- +// Old TinyMCE 6 configuration +editor.ui.registry.addAutocompleter('myautocompleter', { + ch: '@', + minChars: 2, + fetch: function(pattern) { + return Promise.resolve(['item1', 'item2']); + } +}); + +// New TinyMCE 7+ configuration +editor.ui.registry.addAutocompleter('myautocompleter', { + trigger: '@', + minChars: 2, + fetch: function(pattern) { + return Promise.resolve(['item1', 'item2']); + } +}); +---- + +===== force_hex_color option (removed in v7) + +The `force_hex_color` option has been removed. Only RGB values in absolute format like `rgb(255, 255, 255)` are now converted to HEX values. + +===== Text Pattern Changes (v7) + +TinyMCE 7.0 updated the default behavior of `text_patterns` to apply formats when the user presses the `Space` key instead of `Enter`. + +**Impact:** + +* Markdown-style formatting now triggers on Space key press +* Previous Enter key behavior can be restored by configuring `trigger: 'enter'` +* This affects all text patterns including headings, lists, blockquotes, and horizontal rules + +**Migration Steps:** + +1. Test existing text pattern behavior +2. Update configurations if Enter key triggering is required +3. Review user experience with new Space key triggering +4. Consider updating user documentation about text pattern behavior + +.Example: +[source,js] +---- +// Default TinyMCE 7+ behavior (Space key trigger) +tinymce.init({ + selector: "textarea", + text_patterns: [ + { start: '#', format: 'h1', trigger: 'space' }, + { start: '##', format: 'h2', trigger: 'space' }, + { start: '1.', cmd: 'InsertOrderedList', trigger: 'space' }, + { start: '*', cmd: 'InsertUnorderedList', trigger: 'space' }, + { start: '>', cmd: 'mceBlockQuote', trigger: 'space' } + ] +}); + +// Restore previous behavior (Enter key trigger) +tinymce.init({ + selector: "textarea", + text_patterns: [ + { start: '#', format: 'h1', trigger: 'enter' }, + { start: '##', format: 'h2', trigger: 'enter' }, + { start: '1.', cmd: 'InsertOrderedList', trigger: 'enter' }, + { start: '*', cmd: 'InsertUnorderedList', trigger: 'enter' }, + { start: '>', cmd: 'mceBlockQuote', trigger: 'enter' } + ] +}); +---- + +The `table_responsive_width` option has been replaced by `table_sizing_mode` in TinyMCE 7.0. + +**Migration Steps:** + +1. Replace `table_responsive_width` with `table_sizing_mode` in your configuration +2. Update the option value to match the new API +3. Test table responsive behavior + +.Example: +[source,js] +---- +// Old TinyMCE 6 configuration +tinymce.init({ + selector: "textarea", + table_responsive_width: true +}); + +// New TinyMCE 7+ configuration +tinymce.init({ + selector: "textarea", + table_sizing_mode: "responsive" +}); +---- + +For complete API migration details, see xref:migration-from-7x.adoc#core-api-changes[Core API Changes] in the 7→8 migration guide. + +=== Plugin Changes + +==== Template Plugin Removal (v7) + +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` + +==== Media URL Resolver Changes (v7) +// #TINY-9154 + +In {productname} 6 and earlier, the `media_url_resolver` option provided `resolve` and `reject` callbacks, rather than a Promise. 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', + 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', + 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: '' }); + } + }); + } +}); +---- + +=== UI and UX Changes + +==== Table Height Changes (v7) + +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} 7.0 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} 7.0 does not provide any fallback to revert to the old behavior. + +==== Notification Close Button (v7) + +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. + +==== Split Button Changes (v8) +// #TINY-8665 + +{productname} 8.0, xref:custom-split-toolbar-button.adoc[split toolbar buttons] now render as two distinct components: one for the primary action and one for the dropdown chevron. + +This structural change modifies the DOM layout of split buttons and may break custom CSS rules that rely on the previous structure. + +**Impact**: This change only affects integrators using *custom skins*. + +**Migration Guide:** + + + +If your implementation includes a custom skin, follow these steps to ensure compatibility: + +* [ ] Confirm whether your project uses a custom skin. +* [ ] **Rebuild your custom skin** using the {productname} 8.0 codebase. See xref:creating-a-skin.adoc[Creating a Skin] for instructions. +* [ ] **Update your split button usage** to align with the new structure, including support for the `chevronTooltip` option. Refer to xref:custom-split-toolbar-button.adoc[Split Toolbar Buttons] for updated configuration details. +* [ ] **Test the rendering and interaction** of split buttons in your editor to verify expected behavior. + +=== Security Changes + +==== Sandbox Iframes (v7) + +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. + +==== Convert Unsafe Embeds (v7) + +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. + +.Example of before/after conversion. +[source, html] +---- + + + + + +---- + +==== DOMPurify Update (v8) +// #TINY-12056 + +{productname} 8.0 updates the DOMPurify dependency to version 3.2.6 and enables the `SAFE_FOR_XML` flag by default. This is a breaking change: content that previously passed sanitization in {productname} 7 may now be stripped or altered during the sanitization process. + +[IMPORTANT] +==== +This change improves security and aligns with DOMPurify's recommended defaults. However, existing content and integrations that relied on the previous, less strict sanitization behavior may be impacted. +==== + +**Key Changes**: + +* **DOMPurify upgraded to 3.2.6** +* **`SAFE_FOR_XML` enabled** — This setting enforces stricter handling of comments and attribute values, preventing certain XSS vectors. +* **Content Impact** — HTML comments containing tags, Internet Explorer conditional comments, and attributes with HTML-like values may now be removed during sanitization. Content that was previously allowed may be stripped. + +**Migration Steps:** + + +* Review workflows and test content that previously relied on relaxed sanitization. +* {productname} now provides the xref:content-filtering.adoc#allow_html_in_comments[Content Filtering: allow_html_in_comments option] option. Enabling this option allows HTML tags in comments with sanitization still enabled. + +[WARNING] +Using `allow_html_in_comments` increases the risk of XSS vulnerabilities. xref:security.adoc#allow_html_in_comments[allow_html_in_comments] is not recommended for production use unless you fully understand the implications and have appropriate security measures in place. + +=== Service Changes + +==== Java Swing Integration Deprecation (v8) +// #DOC-3304 + +{productname}'s Java Swing integration has been deprecated in {productname} 8.0 and will reach end-of-life as of December 31, 2025. + +**Impact**: Customers using the Java Swing integration need to plan for migration to alternative solutions before the end-of-life date. + +**Migration checklist:** + + +* [ ] Evaluate alternative integration options +* [ ] Plan migration timeline to complete before December 31, 2025 + +==== Transition from Java WAR Files to Containerized Services (v8) +// #EPIC-247 + +{productname} 8.0 no longer includes Java WAR files for backend services like the spell checker. Customers are required to migrate to modern Docker/OCI containers for self-hosted deployments. + +**Impact**: This reduces infrastructure complexity and aligns with modern DevOps practices. + +**Migration checklist:** + + +* [ ] Inventory current WAR file deployments +* [ ] Review containerization requirements for your environment +* [ ] Plan transition timeline to containerized services +* [ ] Set up container infrastructure (Docker/Kubernetes) +* [ ] Deploy and test containerized services +* [ ] Update service connection configurations +* [ ] Contact link:{supporturl}/[{supportname}] if legacy WAR files are still needed + +== Migration Tips + +. **Backup and Prepare**: Ensure comprehensive backups before upgrading. +. **Update Core Initialization**: +.. Update `theme`, `skin`, and to reflect 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. +.. Update license key to new format if self-hosting. +. **Plugin Migration**: +.. Remove deprecated plugins from your configuration. +.. Update renamed plugins (e.g., `spellchecker` → `tinymcespellchecker`). +.. Verify premium plugins for compatibility. +.. Install License Key Manager addon if using commercial license. +. **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]. +.. Replace deprecated API methods (`editor.selection.setContent`, `editor.fire()`, etc.). +. **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. +.. Update split button CSS if using custom skins (TinyMCE 8 change). +. **Testing and Deployment**: +.. Thoroughly test your updated configuration before production deployment. +.. Validate media, iframe, and content security settings. +.. Test license key functionality and premium features. +.. Verify DOMPurify sanitization behavior with your content. + +== 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] +* xref:migration-from-6x.adoc[Migrating from {productname} 6 to {productname} 7] +* xref:migration-from-7x.adoc[Migrating from {productname} 7 to {productname} 8] + +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. + +[IMPORTANT] +==== +**Migration Checklist** + +Before deploying to production, verify: + +* [ ] License key is updated to new format (`T8LK:` prefix) +* [ ] License Key Manager addon is installed (commercial licenses) +* [ ] All deprecated API methods have been replaced (`editor.selection.setContent`, `editor.fire()`, etc.) +* [ ] Custom skins have been rebuilt for TinyMCE 8 compatibility +* [ ] DOMPurify sanitization behavior is tested with your content +* [ ] Cross-origin resource loading is configured if needed +* [ ] All premium features are working correctly +* [ ] Media URL resolver has been updated to use Promises +* [ ] Autocompleter configuration uses `trigger` instead of `ch` +* [ ] Template plugin has been replaced with premium Templates plugin if needed +* [ ] Language pack files are updated to RFC5646 format +* [ ] Accessibility checker configurations are updated for W3C standards +* [ ] Empty file references are removed from build processes +* [ ] Java Swing integration migration is planned (if applicable) +* [ ] Medical English dictionary references are removed +* [ ] WAR file deployments are migrated to containerized services +* [ ] Split button CSS is updated for custom skins +* [ ] Table height handling is tested +* [ ] Notification close button behavior is verified +* [ ] Sandbox iframes configuration is reviewed +* [ ] Convert unsafe embeds behavior is tested +==== diff --git a/modules/ROOT/pages/migration-from-4x.adoc b/modules/ROOT/pages/migration-from-4x.adoc new file mode 100644 index 0000000000..193eebef19 --- /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 {productname} core, 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 {productname} core**: +** `paste`, `hr`, `noneditable`, `table`, `print`, `colorpicker` and `contextmenu`: These plugins were absorbed into {productname} core and no longer require separate installation. +** `contextmenu`: Deprecated in version 5.0 following the integration of context menu functionality into {productname} core 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 {productname} core. + +* **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 {productname} core 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-to-8x.adoc b/modules/ROOT/pages/migration-from-5x-to-8x.adoc new file mode 100644 index 0000000000..40feb3c55d --- /dev/null +++ b/modules/ROOT/pages/migration-from-5x-to-8x.adoc @@ -0,0 +1,669 @@ += Migrating from {productname} 5 to {productname} {productmajorversion} +:navtitle: Migrating from TinyMCE 5 to 8 +:description: Guidance for migrating from TinyMCE 5 to TinyMCE 8 +:keywords: migration, considerations, premigration, pre-migration +:release-version: 8.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 comprehensive 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}. + +This guide provides a complete migration path from TinyMCE 5 to TinyMCE 8, covering all changes across versions 6, 7, and 8 in a single comprehensive document. + +== 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. +* **Split Button Changes**: TinyMCE 8 introduces structural changes to split buttons that may affect custom skins. + +.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. +** `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. +** `textcolor`: Removed in 6.0. Use the premium Color Picker plugin instead. + +* **Integrated into {productname} core**: +** `paste`, `hr`, `table`, `noneditable`, `nonbreaking`, `print`, `colorpicker` and `contextmenu`: These plugins were absorbed into {productname} core and no longer require separate installation. See xref:copy-and-paste.adoc[Copy and Paste], xref:table.adoc[Table], xref:non-editable-content-options.adoc[Non-editable Content], and xref:contextmenu.adoc[Context Menu] for more information. +** `contextmenu`: Deprecated in version 5.0 following the integration of context menu functionality into {productname} core 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 {productname} core. + +* **Now Premium Only**: +** `mediaembed`, `tableofcontents`: These features are available through premium plugins. See xref:introduction-to-mediaembed.adoc[Media Embed] and xref:tableofcontents.adoc[Table of Contents] for more information. +** `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. +** `advtemplate`: Replaces the `template` plugin for advanced templating use cases. +** `template`: Removed in 7.0. Replaced by the premium xref:advanced-templates.adoc[Templates] plugin. +** `toc`: Renamed to `tableofcontents` and now premium. + +==== 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 v7): +** 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 {productname} core and are now provided by the xref:lists.adoc[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. + +{productname} 7 → {productname} 8: + +* Several API methods have been deprecated or removed (see the API Changes section below for details) +* License key system has been updated with new format requirements +* DOMPurify sanitization has been strengthened + +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"] // Note: xref:lists.adoc[Lists], xref:link.adoc[Link], xref:image.adoc[Image], xref:table.adoc[Table], and xref:code.adoc[Code] plugins +}); +---- + +=== 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. + +==== Text Pattern Changes (v7) + +TinyMCE 7.0 updated the default behavior of `text_patterns` to apply formats when the user presses the `Space` key instead of `Enter`. + +**Impact:** + +* Markdown-style formatting now triggers on Space key press +* Previous Enter key behavior can be restored by configuring `trigger: 'enter'` +* This affects all text patterns including headings, lists, blockquotes, and horizontal rules + +**Migration Steps:** + +1. Test existing text pattern behavior +2. Update configurations if Enter key triggering is required +3. Review user experience with new Space key triggering +4. Consider updating user documentation about text pattern behavior + +.Example: +[source,js] +---- +// Default TinyMCE 7+ behavior (Space key trigger) +tinymce.init({ + selector: "textarea", + text_patterns: [ + { start: '#', format: 'h1', trigger: 'space' }, + { start: '##', format: 'h2', trigger: 'space' }, + { start: '1.', cmd: 'InsertOrderedList', trigger: 'space' }, + { start: '*', cmd: 'InsertUnorderedList', trigger: 'space' }, + { start: '>', cmd: 'mceBlockQuote', trigger: 'space' } + ] +}); + +// Restore previous behavior (Enter key trigger) +tinymce.init({ + selector: "textarea", + text_patterns: [ + { start: '#', format: 'h1', trigger: 'enter' }, + { start: '##', format: 'h2', trigger: 'enter' }, + { start: '1.', cmd: 'InsertOrderedList', trigger: 'enter' }, + { start: '*', cmd: 'InsertUnorderedList', trigger: 'enter' }, + { start: '>', cmd: 'mceBlockQuote', trigger: 'enter' } + ] +}); +---- + +The `remove_trailing_brs` setting was removed from the DomParser API in {productname} 7.0, after being deprecated in {productname} 6.5. + +==== Autocompleter Configuration Changes (v7) + +The `ch` configuration property for autocompleters has been removed. Use the `trigger` property instead. + +**Migration Steps:** + +1. Replace `ch: ''` with `trigger: ''` in autocompleter configurations +2. Test autocompleter functionality +3. Update any custom autocompleter implementations + +.Example: +[source,js] +---- +// Old TinyMCE 6 configuration +editor.ui.registry.addAutocompleter('myautocompleter', { + ch: '@', + minChars: 0, + fetch: function(pattern) { + return [ + { value: 'john@example.com', text: 'John Doe' }, + { value: 'jane@example.com', text: 'Jane Smith' } + ]; + } +}); + +// New TinyMCE 7+ configuration +editor.ui.registry.addAutocompleter('myautocompleter', { + trigger: '@', + minChars: 0, + fetch: function(pattern) { + return [ + { value: 'john@example.com', text: 'John Doe' }, + { value: 'jane@example.com', text: 'Jane Smith' } + ]; + } +}); +---- + +==== table_responsive_width replaced by table_sizing_mode (v7) + +.Example: +[source,js] +---- +// Old TinyMCE 6 configuration +editor.ui.registry.addAutocompleter('myautocompleter', { + ch: '@', + minChars: 2, + fetch: function(pattern) { + return Promise.resolve(['item1', 'item2']); + } +}); + +// New TinyMCE 7+ configuration +editor.ui.registry.addAutocompleter('myautocompleter', { + trigger: '@', + minChars: 2, + fetch: function(pattern) { + return Promise.resolve(['item1', 'item2']); + } +}); +---- +** `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 + +* **New Options in {productname} 8.0**: +** Enhanced license key system with new format requirements +** Stricter DOMPurify sanitization with `SAFE_FOR_XML` enabled by default +** New `crossorigin` configuration option for cross-origin resource loading + +.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: "T8LK:...", // New format required in TinyMCE 8.0 + // 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, + // New in TinyMCE 8.0: Cross-origin resource loading + crossorigin: (url, resourceType) => 'anonymous' +}); +---- + +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, 7, and 8. 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 {productname} core (use `lists` plugin). +* Default text pattern triggers updated from `Enter` to `Space`, configurable via `trigger`. + +{productname} 7 → {productname} 8: + +* `editor.selection.setContent` → `editor.insertContent` +* `editor.fire()` → `editor.dispatch()` +* `editor.documentBaseUrl` → `editor.documentBaseURI.getURI()` +==== + +=== 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. + +[IMPORTANT] +==== +**License Key System Update in TinyMCE 8** + +TinyMCE 8 introduces a new license key system that requires immediate attention: + +* **New Format**: License keys now use the prefix `T8LK:` for commercial licenses or `GPL+T8LK:` for GPL with Premium Features +* **Mandatory Requirement**: Self-hosted deployments now require a valid license key; without one, the editor will be set to `readonly` +* **License Key Manager**: Self-hosted commercial deployments require the new License Key Manager addon + +For complete details, see xref:migration-from-7x.adoc#license-key-system-update[License Key System Update] in the 7→8 migration guide. +==== + +.Example: +[source,js] +---- +tinymce.init({ +selector: "textarea", +license_key: "T8LK:your-license-key" // New format required +}); +---- + +=== API Changes + +Several API methods have been deprecated or removed across versions 6-8. Key changes include: + +* **Deprecated in TinyMCE 8**: +** `editor.selection.setContent` → Use `editor.insertContent` instead +** `editor.fire()` → Use `editor.dispatch()` instead +** `editor.documentBaseUrl` → Use `editor.documentBaseURI.getURI()` instead + +==== skipFocus and skip_focus Consolidation (v8) + +The `skipFocus` and `skip_focus` options for the `ToggleToolbarDrawer` command have been consolidated into a single, more consistent argument in TinyMCE 8.0. + +**Impact:** + +* Reduces API complexity +* Clarifies intended behavior +* Requires updating command calls + +**Migration Steps:** + +1. Locate all instances of `ToggleToolbarDrawer` command usage +2. Replace `skip_focus` with `skipFocus` in command parameters +3. Test toolbar drawer behavior + +.Example: +[source,js] +---- +// Old TinyMCE 7 usage +editor.execCommand('ToggleToolbarDrawer', false, null, { skip_focus: true }); + +// New TinyMCE 8 usage +editor.execCommand('ToggleToolbarDrawer', false, { skipFocus: true }); +---- + +* **Removed Methods**: +** `editor.addButton`, `editor.addMenuItem`, `editor.windowManager.open` (replaced by `editor.ui.registry.*` API) + +For complete API migration details, see xref:migration-from-7x.adoc#core-api-changes[Core API Changes] in the 7→8 migration guide. + +=== Plugin Changes + +==== Template Plugin Removal + +The `template` plugin was removed in TinyMCE 7.0. If you were using this plugin, you need to migrate to the premium Templates plugin. + +**Migration Steps:** + +1. Remove `template` from your plugins list +2. Add `templates` to your plugins list +3. Update your configuration to use the new Templates plugin API +4. Ensure you have a valid commercial license for the Templates plugin + +.Example: +[source,js] +---- +// Old TinyMCE 5/6/7 configuration +tinymce.init({ + selector: "textarea", + plugins: "template", + templates: [ + {title: 'Test template 1', content: 'Test 1'}, + {title: 'Test template 2', content: 'Test 2'} + ] +}); + +// New TinyMCE 8 configuration +tinymce.init({ + selector: "textarea", + plugins: "templates", + templates: [ + {title: 'Test template 1', content: 'Test 1'}, + {title: 'Test template 2', content: 'Test 2'} + ] +}); +---- + +==== Media URL Resolver Changes (v7) + +The `media_url_resolver` option now requires a Promise-based implementation instead of synchronous callbacks. + +.Example: +[source,js] +---- +// Old TinyMCE 5/6 implementation +tinymce.init({ + selector: "textarea", + media_url_resolver: function (data, resolve) { + resolve({ + html: '' + }); + } +}); + +// New TinyMCE 7+ implementation +tinymce.init({ + selector: "textarea", + media_url_resolver: function (data) { + return new Promise(function (resolve) { + resolve({ + html: '' + }); + }); + } +}); +---- + +=== UI and UX Changes + +==== Table Height Changes (v7) + +TinyMCE 7.0 changed how table heights are handled. Tables now use `min-height` instead of `height` for better responsive behavior. + +**Impact:** + +* Existing table height configurations may need adjustment +* Custom CSS targeting table heights should be reviewed +* Responsive table behavior may change + +==== Split Button Changes (v8) + +TinyMCE 8.0 introduces structural changes to split buttons that may affect custom skins and CSS. + +**Changes:** +* Split button DOM structure has been updated +* CSS selectors for split buttons may need adjustment +* Custom skins should be tested for split button compatibility + +**Testing:** +* Verify split button functionality in custom skins +* Check CSS compatibility with new split button structure +* Test split button interactions and dropdowns + +=== Security Changes + +==== DOMPurify Update + +{productname} 8.0 updates the DOMPurify dependency to version 3.2.6 and enables the `SAFE_FOR_XML` flag by default. This is a breaking change: content that previously passed sanitization in {productname} 7 may now be stripped or altered during the sanitization process. + +**Impact:** + +* Stricter content sanitization +* Some previously allowed content may be stripped +* XML-specific sanitization rules are now applied + +**Migration Steps:** + +1. Test content sanitization behavior with your specific content +2. Review any custom sanitization configurations +3. Update content if necessary to comply with stricter rules + +.Example: +[source,js] +---- +// Content that may be affected by stricter sanitization +const content = '

'; + +// Test sanitization behavior +const sanitized = editor.dom.sanitize(content); +console.log('Sanitized content:', sanitized); +---- + +==== Cross-Origin Resource Loading + +**Migration Steps:** + +1. Test existing content for sanitization changes +2. Review custom sanitization configurations +3. Update any content that relies on previous sanitization behavior + +==== Cross-Origin Resource Loading + +TinyMCE 8.0 introduces stricter controls for cross-origin resource loading. + +**New Configuration:** + +* `crossorigin` attribute support for external resources +* Enhanced security for loading external content +* Better control over resource loading policies + +**Migration Steps:** + +1. Review external resource loading configurations +2. Add `crossorigin` attributes where appropriate +3. Test cross-origin resource loading behavior + +=== Service Changes + +==== Java Swing Integration Deprecation + +Java Swing integration has been deprecated in TinyMCE 8.0 and will reach end-of-life as of December 31, 2025. + +**Impact:** + +* Java Swing-based integrations need migration planning +* Alternative integration methods should be considered +* Legacy Java integrations may stop working + +**Migration Steps:** + +1. Identify Java Swing integrations in your application +2. Plan migration to modern integration methods +3. Test alternative integration approaches + +==== Medical English Dictionary Discontinuation + +The "Medical English (UK)" dictionary has been discontinued. + +**Impact:** + +* Applications using this dictionary need to switch to alternatives +* Spell checking configurations may need updates +* Language pack references should be updated + +**Migration Steps:** + +1. Remove references to "Medical English (UK)" dictionary +2. Switch to alternative English dictionaries +3. Update spell checking configurations + +==== Service Version Decoupling + +TinyMCE services are now decoupled from the editor version, allowing for independent updates. + +**Benefits:** +* Services can be updated independently +* Better security and performance updates +* Reduced dependency on editor version updates + +**Migration Steps:** + +1. Review service integration configurations +2. Update service endpoints if needed +3. Test service functionality with TinyMCE 8 + +==== WAR File to Container Migration + +TinyMCE services are transitioning from Java WAR files to containerized services. + +**Impact:** + +* Deployment methods need to be updated +* Service configurations may change +* Infrastructure requirements may be different + +**Migration Steps:** + +1. Plan migration from WAR file deployments +2. Update deployment infrastructure +3. Test containerized service deployments + +== Migration Tips + +. **Backup and Prepare**: Ensure comprehensive backups before upgrading. +. **Update Core Initialization**: +.. Update `theme`, `skin`, and to reflect 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. +.. Update license key to new format if self-hosting. +. **Plugin Migration**: +.. Remove deprecated plugins from your configuration. +.. Update renamed plugins (e.g., `spellchecker` → `tinymcespellchecker`). +.. Verify premium plugins for compatibility. +.. Install License Key Manager addon if using commercial license. +. **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]. +.. Replace deprecated API methods (`editor.selection.setContent`, `editor.fire()`, etc.). +. **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. +.. Update split button CSS if using custom skins (TinyMCE 8 change). +. **Testing and Deployment**: +.. Thoroughly test your updated configuration before production deployment. +.. Validate media, iframe, and content security settings. +.. Test license key functionality and premium features. +.. Verify DOMPurify sanitization behavior with your content. + +== 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] +* xref:migration-from-6x.adoc[Migrating from {productname} 6 to {productname} 7] +* xref:migration-from-7x.adoc[Migrating from {productname} 7 to {productname} 8] + +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. + +[IMPORTANT] +==== +**Migration Checklist** + +Before deploying to production, verify: + +* [ ] License key is updated to new format (`T8LK:` prefix) +* [ ] License Key Manager addon is installed (commercial licenses) +* [ ] All deprecated API methods have been replaced (`editor.selection.setContent`, `editor.fire()`, etc.) +* [ ] Custom skins have been rebuilt for TinyMCE 8 compatibility +* [ ] DOMPurify sanitization behavior is tested with your content +* [ ] Cross-origin resource loading is configured if needed +* [ ] All premium features are working correctly +* [ ] Media URL resolver has been updated to use Promises +* [ ] Template plugin has been replaced with premium Templates plugin if needed +* [ ] Language pack files are updated to RFC5646 format +* [ ] Accessibility checker configurations are updated for W3C standards +* [ ] Empty file references are removed from build processes +* [ ] Java Swing integration migration is planned (if applicable) +* [ ] Medical English dictionary references are removed +* [ ] WAR file deployments are migrated to containerized services +* [ ] Split button CSS is updated for custom skins +* [ ] Table height handling is tested +* [ ] Notification close button behavior is verified +* [ ] Sandbox iframes configuration is reviewed +* [ ] Convert unsafe embeds behavior is tested +==== diff --git a/modules/ROOT/pages/migration-from-5x.adoc b/modules/ROOT/pages/migration-from-5x.adoc new file mode 100644 index 0000000000..d66c0a7147 --- /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 {productname} core**: +** `paste`, `hr`, `table`, `noneditable`, `nonbreaking`, `print`, `colorpicker` and `contextmenu`: These plugins were absorbed into {productname} core and no longer require separate installation. +** `contextmenu`: Deprecated in version 5.0 following the integration of context menu functionality into {productname} core 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 {productname} core. + +* **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 {productname} core 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 {productname} core (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-to-8x.adoc b/modules/ROOT/pages/migration-from-6x-to-8x.adoc new file mode 100644 index 0000000000..8907377f90 --- /dev/null +++ b/modules/ROOT/pages/migration-from-6x-to-8x.adoc @@ -0,0 +1,668 @@ += Migrating from {productname} 6 to {productname} {productmajorversion} +:navtitle: Migrating from TinyMCE 6 to 8 +:description: Guidance for migrating from TinyMCE 6 to TinyMCE 8 +:keywords: migration, considerations, premigration, pre-migration +:release-version: 8.0 + +== Overview + +The process for setting up a basic {productname} {release-version} instance is similar to {productname} 6, but there are important changes across versions 7 and 8 that require attention. + +Most configuration changes in {productname} {release-version} affect complex use cases, such as custom plugins and customized user interface components, but some breaking changes require immediate attention. + +This documentation details the changes in {productname} {release-version} that integrators using {productname} 6 should consider when upgrading. + +This guide provides a complete migration path from TinyMCE 6 to TinyMCE 8, covering all changes across versions 7 and 8 in a single comprehensive document. + +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]. + +== Key Changes + +=== UI Themes and Skins + +The theme and skin system has been updated across versions 7 and 8: + +* **Modern Theme**: Replaced by the `silver` theme with `oxide` skin +* **Lightgray Theme**: Replaced by the `silver` theme with `oxide` skin +* **Mobile Theme**: Replaced by the `silver` theme with `oxide` skin + +**Migration Steps:** + +1. Update theme configuration to use `silver` theme +2. Update skin configuration to use `oxide` skin +3. Test UI appearance and functionality + +.Example: +[source,js] +---- +// Old TinyMCE 6 configuration +tinymce.init({ + selector: "textarea", + theme: "modern", + skin: "lightgray" +}); + +// New TinyMCE 7+ configuration +tinymce.init({ + selector: "textarea", + theme: "silver", + skin: "oxide" +}); +---- + +=== Plugin Ecosystem + +The {productname} plugin ecosystem underwent changes starting in version 7.0, with several plugins being removed or reclassified. + +* **Removed Plugins** (no longer available as of {productname} 7.0): +** `template`: Removed in 7.0. Replaced by the premium xref:advanced-templates.adoc[Templates] plugin. + +* **Now Premium Only**: +** `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. +** `textcolor`: Removed in 6.0. Use the premium Color Picker plugin instead. + +==== Plugin Migration Examples + +* `template` (removed in v7): +** Use the premium xref:advanced-templates.adoc[Templates] plugin or implement custom modal dialogs. +** Consider using xref:advanced-templates.adoc[Advanced Templates] for complex templating needs. + +* `imagetools` (removed in v6): +** Use the premium xref:editimage.adoc[Enhanced Image Editing] feature. +** Ensure you have a valid commercial license for the Enhanced Image Editing feature. + +* `textcolor` (removed in v6): +** Use the premium Color Picker plugin. +** Ensure you have a valid commercial license for the Color Picker feature. + +=== Content Structure + +The content structure requirements have been updated: + +* **Requirement**: All editor content must be enclosed in block elements (e.g., `

`). + +=== Configuration Changes + +Several configuration options have been updated across versions 7 and 8: + +* **New Defaults**: +** xref:accessibility.adoc#highlight_on_focus[`highlight_on_focus`]: Now defaults to `true` (adds focus outline to editors) +** xref:content-filtering.adoc#convert-unsafe-embeds[`convert_unsafe_embeds`]: Now defaults to `true` (converts object/embed elements to safer alternatives) +** xref:content-filtering.adoc#sandbox-iframes[`sandbox_iframes`]: Now defaults to `true` (adds sandbox attribute to iframes) +** xref:content-filtering.adoc#sandbox-iframes-exclusions[`sandbox_iframes_exclusions`]: List of URL hosts to exclude from iframe sandboxing +** xref:license-key.adoc[`license_key`]: Must be set to `gpl` or a valid license key +** New `crossorigin` configuration option for cross-origin resource loading + +.Example: +[source,js] +---- +tinymce.init({ + selector: "textarea", + highlight_on_focus: true, + convert_unsafe_embeds: true, + sandbox_iframes: true, + sandbox_iframes_exclusions: ["youtube.com", "vimeo.com"], + license_key: "T8LK:...", // New format required + crossorigin: (url, resourceType) => 'anonymous' +}); +---- + +=== Licensing Changes (GPL v2+ and Commercial) + +{productname} 8.0 introduces significant changes to the licensing system: + +* **New Format**: License keys now use the prefix `T8LK:` for commercial licenses or `GPL+T8LK:` for GPL with Premium Features +* **License Key Manager**: Self-hosted commercial deployments require the new License Key Manager addon +* **Mandatory License Key**: All deployments now require a valid license key + +.Example: +[source,js] +---- +tinymce.init({ + selector: "textarea", + license_key: "T8LK:your-license-key" // New format required +}); +---- + +== API Changes + +=== Deprecated in TinyMCE 8 + +==== editor.selection.setContent + +The `editor.selection.setContent` API has been deprecated and will be removed in {productname} 9. + +**Migration Steps:** + +1. Replace `editor.selection.setContent` with `editor.insertContent` +2. Update custom plugins that use the old method +3. Test content insertion in your editor instances + +.Example: +[source,js] +---- +// Deprecated in TinyMCE 8, will be removed in 9 +editor.selection.setContent('

New content

'); + +// New approach +editor.insertContent('

New content

'); +---- + +==== fire() method + +The `fire()` method has been replaced by `dispatch()` for event handling. The `fire()` method will be removed in {productname} 9 to avoid confusion with its name. + +**Migration Steps:** + +1. Search codebase for all uses of the `fire()` method +2. Replace each instance with `dispatch()` +3. Review and update third-party plugins +4. Test all custom event handling + +.Example: +[source,js] +---- +// Deprecated in TinyMCE 8, will be removed in 9 +editor.fire('someEvent'); + +// New approach +editor.dispatch('someEvent'); +---- + +==== addButton, addMenuItem, and windowManager.open + +The `addButton`, `addMenuItem`, and `windowManager.open` methods have been replaced by the `editor.ui.registry.*` API. + +**Migration Steps:** + +1. Replace all instances of `editor.addButton` with `editor.ui.registry.addButton` +2. Replace all instances of `editor.addMenuItem` with `editor.ui.registry.addMenuItem` +3. Replace all instances of `editor.windowManager.open` with `editor.windowManager.open` +4. Update custom plugins that use the old methods +5. Test button and menu functionality in your editor instances + +.Example: +[source,js] +---- +// Deprecated in TinyMCE 8, will be removed in 9 +editor.addButton('myButton', { + text: 'My Button', + onclick: function() { + editor.insertContent('Hello World!'); + } +}); + +// New approach +editor.ui.registry.addButton('myButton', { + text: 'My Button', + onAction: function() { + editor.insertContent('Hello World!'); + } +}); +---- + +==== editor.documentBaseUrl + +The `editor.documentBaseUrl` property has been removed. Use `editor.editorManager.documentBaseURI.getURI()` instead. + +**Migration Steps:** + +1. Search your codebase for all instances of `editor.documentBaseUrl` +2. Replace them with `tinymce.activeEditor.documentBaseURI.getURI()` (or `editor.documentBaseURI.getURI()` if you have an `editor` reference) +3. Test any functionality that depends on document base URL + +.Example: +[source,js] +---- +// Deprecated in TinyMCE 8, will be removed in 9 +const baseUrl = editor.documentBaseUrl; + +// New approach +const baseUrl = editor.documentBaseURI.getURI(); +---- + +==== skipFocus and skip_focus Consolidation (v8) + +The `skipFocus` and `skip_focus` options for the `ToggleToolbarDrawer` command have been consolidated into a single, more consistent argument in TinyMCE 8.0. + +**Impact:** + +* Reduces API complexity +* Clarifies intended behavior +* Requires updating command calls + +**Migration Steps:** + +1. Locate all instances of `ToggleToolbarDrawer` command usage +2. Replace `skip_focus` with `skipFocus` in command parameters +3. Test toolbar drawer behavior + +.Example: +[source,js] +---- +// Old approach +editor.execCommand('ToggleToolbarDrawer', false, { skip_focus: true }); + +// New approach +editor.execCommand('ToggleToolbarDrawer', false, { skipFocus: true }); +---- + +=== Removed Methods + +==== Legacy API Methods (removed in v6) + +* `InsertOrderedList` and `InsertUnorderedList` commands were removed from {productname} core and are now provided by the xref:lists.adoc[Lists] plugin. + +==== Autocompleter `ch` property (removed in v7) + +The `ch` configuration property for autocompleters has been removed. Use the `trigger` property instead. + +**Migration Steps:** + +1. Replace `ch: ''` with `trigger: ''` in autocompleter configurations +2. Test autocompleter functionality +3. Update any custom autocompleter implementations + +.Example: +[source,js] +---- +// Old TinyMCE 6 configuration +editor.ui.registry.addAutocompleter('myautocompleter', { + ch: '@', + minChars: 0, + fetch: function(pattern) { + return [ + { value: 'john@example.com', text: 'John Doe' }, + { value: 'jane@example.com', text: 'Jane Smith' } + ]; + } +}); + +// New TinyMCE 7+ configuration +editor.ui.registry.addAutocompleter('myautocompleter', { + trigger: '@', + minChars: 0, + fetch: function(pattern) { + return [ + { value: 'john@example.com', text: 'John Doe' }, + { value: 'jane@example.com', text: 'Jane Smith' } + ]; + } +}); +---- + +==== remove_trailing_brs property (removed in v7) + +The `remove_trailing_brs` setting was removed from the DomParser API in {productname} 7.0, after being deprecated in {productname} 6.5. + +**Impact:** + +* DomParser no longer supports the `remove_trailing_brs` option +* This affects custom DomParser configurations +* May impact content parsing behavior + +**Migration Steps:** + +1. Remove `remove_trailing_brs` from DomParser configurations +2. Test content parsing behavior +3. Update any custom DomParser implementations + +==== Text Pattern Changes (v7) + +TinyMCE 7.0 updated the default behavior of `text_patterns` to apply formats when the user presses the `Space` key instead of `Enter`. + +**Impact:** + +* Markdown-style formatting now triggers on Space key press +* Previous Enter key behavior can be restored by configuring `trigger: 'enter'` +* This affects all text patterns including headings, lists, blockquotes, and horizontal rules + +**Migration Steps:** + +1. Test existing text pattern behavior +2. Update configurations if Enter key triggering is required +3. Review user experience with new Space key triggering +4. Consider updating user documentation about text pattern behavior + +.Example: +[source,js] +---- +// Default TinyMCE 7+ behavior (Space key trigger) +tinymce.init({ + selector: "textarea", + text_patterns: [ + { start: '#', format: 'h1', trigger: 'space' }, + { start: '##', format: 'h2', trigger: 'space' }, + { start: '1.', cmd: 'InsertOrderedList', trigger: 'space' }, + { start: '*', cmd: 'InsertUnorderedList', trigger: 'space' }, + { start: '>', cmd: 'mceBlockQuote', trigger: 'space' } + ] +}); + +// Restore previous behavior (Enter key trigger) +tinymce.init({ + selector: "textarea", + text_patterns: [ + { start: '#', format: 'h1', trigger: 'enter' }, + { start: '##', format: 'h2', trigger: 'enter' }, + { start: '1.', cmd: 'InsertOrderedList', trigger: 'enter' }, + { start: '*', cmd: 'InsertUnorderedList', trigger: 'enter' }, + { start: '>', cmd: 'mceBlockQuote', trigger: 'enter' } + ] +}); +---- + +==== table_responsive_width replaced by table_sizing_mode (v7) + +The `table_responsive_width` option has been replaced by `table_sizing_mode` in TinyMCE 7.0. + +**Migration Steps:** + +1. Replace `table_responsive_width` with `table_sizing_mode` in your configuration +2. Update the option value to match the new API +3. Test table responsive behavior + +.Example: +[source,js] +---- +// Old TinyMCE 6 configuration +tinymce.init({ + selector: "textarea", + table_responsive_width: true +}); + +// New TinyMCE 7+ configuration +tinymce.init({ + selector: "textarea", + table_sizing_mode: "responsive" +}); +---- + +==== force_hex_color option (removed in v7) + +The `force_hex_color` option has been removed. Only RGB values in absolute format like `rgb(255, 255, 255)` are now converted to HEX values. + +== Plugin Changes + +=== Template Plugin Removal (v7) + +The `template` plugin was removed in TinyMCE 7.0. If you were using this plugin, you need to migrate to the premium Templates plugin. + +**Migration Steps:** +1. Remove `template` from your plugins list +2. Add `templates` to your plugins list +3. Update your configuration to use the new Templates plugin API + +=== Image Tools Plugin Removal + +The `imagetools` plugin was removed in TinyMCE 6.0. If you were using this plugin, you need to migrate to the premium Enhanced Image Editing feature. + +**Migration Steps:** +1. Remove `imagetools` from your plugins list +2. Add `editimage` to your plugins list (premium feature) +3. Ensure you have a valid commercial license for the Enhanced Image Editing feature +4. Update any custom image editing configurations + +.Example: +[source,js] +---- +// Old TinyMCE 5 configuration +tinymce.init({ + selector: "textarea", + plugins: "imagetools", + imagetools_toolbar: "rotateleft rotateright | flipv fliph | editimage imageoptions" +}); + +// New TinyMCE 6+ configuration +tinymce.init({ + selector: "textarea", + plugins: "editimage", // Premium feature + editimage_toolbar: "rotateleft rotateright | flipv fliph | editimage imageoptions" +}); +---- + +=== Text Color Plugin Removal + +The `textcolor` plugin was removed in TinyMCE 6.0. If you were using this plugin, you need to migrate to the premium Color Picker plugin. + +**Migration Steps:** +1. Remove `textcolor` from your plugins list +2. Add `colorpicker` to your plugins list (premium feature) +3. Ensure you have a valid commercial license for the Color Picker feature +4. Update any custom color picker configurations + +.Example: +[source,js] +---- +// Old TinyMCE 5 configuration +tinymce.init({ + selector: "textarea", + plugins: "textcolor", + toolbar: "forecolor backcolor" +}); + +// New TinyMCE 6+ configuration +tinymce.init({ + selector: "textarea", + plugins: "colorpicker", + toolbar: "forecolor backcolor" +}); +---- + +=== Media URL Resolver Changes (v7) + +In {productname} 6 and earlier, the `media_url_resolver` option provided `resolve` and `reject` callbacks, rather than a Promise. In {productname} 7, the `media_url_resolver` option now requires a Promise to be returned. + +**Migration Steps:** + +1. Update `media_url_resolver` implementations to return Promises +2. Test media URL resolution functionality +3. Update any custom media handling logic + +.Example: +[source,js] +---- +// Old TinyMCE 6 approach +tinymce.init({ + selector: "textarea", + media_url_resolver: function(data, resolve, reject) { + // Custom logic here + resolve(data.url); + } +}); + +// New TinyMCE 7+ approach +tinymce.init({ + selector: "textarea", + media_url_resolver: function(data) { + return new Promise(function(resolve, reject) { + // Custom logic here + resolve(data.url); + }); + } +}); +---- + +== UI and UX Changes + +=== Table Height Changes (v7) + +In {productname} 7.0, the way cell and row heights are applied to tables has been changed: + +* 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. + +=== Notification Close Button (v7) + +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. + +In {productname} 7.0, notifications are now forced to have a close button to improve accessibility. + +=== Split Button Changes (v8) + +In {productname} 8.0, xref:custom-split-toolbar-button.adoc[split toolbar buttons] now render as two distinct components: one for the primary action and one for the dropdown chevron. + +This structural change modifies the DOM layout of split buttons and may break custom CSS rules that rely on the previous structure. + +**Migration Steps:** + +1. **Update your split button usage** to align with the new structure, including support for the `chevronTooltip` option. Refer to xref:custom-split-toolbar-button.adoc[Split Toolbar Buttons] for updated configuration details. +2. **Test the rendering and interaction** of split buttons in your editor to verify expected behavior. + +== Security Changes + +=== Sandbox Iframes (v7) + +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. + +=== Convert Unsafe Embeds (v7) + +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. + +=== DOMPurify Update (v8) + +{productname} 8.0 updates the DOMPurify dependency to version 3.2.6 and enables the `SAFE_FOR_XML` flag by default. This is a breaking change: content that previously passed sanitization in {productname} 7 may now be stripped or altered during the sanitization process. + +**Impact:** + +* Stricter content sanitization +* Some previously allowed content may be stripped +* XML-specific sanitization rules are now applied + +**Migration Steps:** + +1. Test content sanitization behavior with your specific content +2. Review any custom sanitization configurations +3. Update content if necessary to comply with stricter rules + +.Example: +[source,js] +---- +// Content that may be affected by stricter sanitization +const content = '
'; + +// Test sanitization behavior +const sanitized = editor.dom.sanitize(content); +console.log('Sanitized content:', sanitized); +---- + +=== Cross-Origin Resource Loading + +TinyMCE 8.0 introduces stricter controls for cross-origin resource loading. + +**New Configuration:** + +* `crossorigin` attribute support for external resources +* Enhanced security for loading external content +* Better control over resource loading policies + +**Migration Steps:** + +1. Review external resource loading configurations +2. Add `crossorigin` attributes where appropriate +3. Test cross-origin resource loading behavior + +== Service Changes + +=== Java Swing Integration Deprecation (v8) + +{productname}'s Java Swing integration has been deprecated in {productname} 8.0 and will reach end-of-life as of December 31, 2025. + +**Migration Steps:** + +1. Evaluate alternative integration options +2. Plan migration timeline to complete before December 31, 2025 + +=== Medical English Dictionary Discontinuation + +The "Medical English (UK)" dictionary has been discontinued and is no longer available in {productname} 8.0. + +**Migration Steps:** + +1. Remove "Medical English (UK)" from spellchecker configurations +2. Remove any custom dictionary integrations related to Medical English +3. Test spellchecker functionality with remaining dictionaries +4. Configure alternative medical dictionary if required + +=== Transition from Java WAR Files to Containerized Services (v8) + +{productname} 8.0 no longer includes Java WAR files for backend services like the spell checker. Customers are required to migrate to modern Docker/OCI containers for self-hosted deployments. + +**Migration Steps:** + +1. Inventory current WAR file deployments +2. Review containerization requirements for your environment +3. Plan transition timeline to containerized services +4. Set up container infrastructure (Docker/Kubernetes) +5. Deploy and test containerized services +6. Update service connection configurations +7. Contact link:{supporturl}/[{supportname}] if legacy WAR files are still needed + +== Migration Tips + +=== License Migration checklist: + +* [ ] Contact support for new {productname} {release-version} license key or use GPL for the open source version +* [ ] Install license key manager addon for commercial licenses +* [ ] Update configuration with new license key format +* [ ] Test editor functionality with new license +* [ ] Verify all premium features are working + +=== Custom Skin Migration checklist: + +* [ ] Confirm whether your project uses a custom skin. +* [ ] **Rebuild your custom skin** using the {productname} {productmajorversion} codebase. See xref:creating-a-skin.adoc[Creating a Skin] for instructions. +* [ ] **Update your split button usage** to align with the new structure, including support for the `chevronTooltip` option. Refer to xref:custom-split-toolbar-button.adoc[Split Toolbar Buttons] for updated configuration details. +* [ ] **Test the rendering and interaction** of split buttons in your editor to verify expected behavior. + +=== General Migration checklist: + +* [ ] License key is updated to new format (`T8LK:` prefix) +* [ ] License Key Manager addon is installed (commercial licenses) +* [ ] All deprecated API methods have been replaced (`editor.selection.setContent`, `editor.fire()`, etc.) +* [ ] Custom skins have been rebuilt for TinyMCE 8 compatibility +* [ ] DOMPurify sanitization behavior is tested with your content +* [ ] Cross-origin resource loading is configured if needed +* [ ] All premium features are working correctly +* [ ] Media URL resolver has been updated to use Promises +* [ ] Autocompleter configuration uses `trigger` instead of `ch` +* [ ] Template plugin has been replaced with premium Templates plugin if needed +* [ ] Language pack files are updated to RFC5646 format +* [ ] Accessibility checker configurations are updated for W3C standards +* [ ] Empty file references are removed from build processes +* [ ] Java Swing integration migration is planned (if applicable) +* [ ] Medical English dictionary references are removed +* [ ] WAR file deployments are migrated to containerized services +* [ ] Split button CSS is updated for custom skins +* [ ] Table height handling is tested +* [ ] Notification close button behavior is verified +* [ ] Sandbox iframes configuration is reviewed +* [ ] Convert unsafe embeds behavior is tested + +== 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/6/migration-from-5x/[Migrating from {productname} 5 to {productname} 6] +* xref:migration-from-6x.adoc[Migrating from {productname} 6 to {productname} 7] + +These include deeper configuration notes, plugin replacements, and examples. + +== Next Steps + +After completing your migration: + +* Test all functionality thoroughly +* Update your documentation +* Train your team on any new features +* Consider upgrading to the latest {productname} version for ongoing support \ No newline at end of file diff --git a/modules/ROOT/pages/migration-from-6x.adoc b/modules/ROOT/pages/migration-from-6x.adoc new file mode 100644 index 0000000000..c9f5ddb38a --- /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 the latest release notes at link:https://www.tiny.cloud/docs/tinymce/latest/release-notes/[latest 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'`. See the Text Pattern Changes section below for more details. + +.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 `,