You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
542 lines
20 KiB
542 lines
20 KiB
= Migrating from {productname} 7 to {productname} {productmajorversion}
|
|
:navtitle: Migrating from TinyMCE 7
|
|
:description: Guidance for migrating from TinyMCE 7 to TinyMCE 8
|
|
:keywords: migration, considerations, premigration, pre-migration
|
|
:release-version: 8.0
|
|
:page-toclevels: 3
|
|
|
|
== Introduction
|
|
|
|
This guide provides a comprehensive overview of the breaking changes introduced in {productname} {release-version}, along with the necessary steps to migrate from {productname} 7.x. It covers key updates to APIs, plugins, and service configurations, including deprecated methods, renamed components, and removed features. These changes are designed to enhance performance, simplify configuration, and align with modern web standards, ensuring a smoother transition and continued compatibility for your integrations.
|
|
|
|
[IMPORTANT]
|
|
.Breaking Changes Quick Reference
|
|
====
|
|
The following table summarizes all breaking changes in {productname} {release-version}. Each item links to detailed information further in the guide.
|
|
|
|
Any items marked **"High"** level require immediate attention during migration.
|
|
|
|
[cols="2,3,1",options="header"]
|
|
|===
|
|
|Breaking Change |Impact |Level
|
|
|xref:license-key-system-update[License Key System Update]
|
|
|Self-hosted deployments now require a new license key format and license key manager. Old keys are **not compatible**.
|
|
|High
|
|
|
|
|xref:pagebreak-split-block-default[pagebreak_split_block Default Value]
|
|
|The default value changed from `false` to `true`, affecting how page breaks interact with block elements.
|
|
|Low
|
|
|
|
|xref:editor-selection-setcontent-deprecated[editor.selection.setContent] Deprecated
|
|
|Method deprecated. Use `editor.insertContent` instead.
|
|
|Medium
|
|
|
|
|xref:editor-documentbaseurl-removal[editor.documentBaseUrl] Removal
|
|
|Undocumented property removed. Use `editor.editorManager.documentBaseURI` instead.
|
|
|Low
|
|
|
|
|xref:skipfocus-consolidation[skipFocus and skip_focus] Consolidation
|
|
|Options consolidated to `skipFocus` in `ToggleToolbarDrawer`.
|
|
|Low
|
|
|
|
|xref:fire-method-deprecation[fire()] Method Deprecation
|
|
|Method deprecated. Use `dispatch()` for event handling.
|
|
|Medium
|
|
|===
|
|
====
|
|
|
|
[[license-key-system-update]]
|
|
=== Transition from Version 7 License Keys to Version {release-version} License Keys
|
|
// #EPIC-192
|
|
|
|
[IMPORTANT]
|
|
====
|
|
This section applies to self-hosted installations only. For cloud deployments, license key management is handled automatically.
|
|
====
|
|
|
|
{productname} {release-version} introduces an enhanced license key system that requires specific attention during migration. The complete licensing documentation xref:license-key.adoc[License Key Management] covers:
|
|
|
|
* Detailed explanations of all license types (GPL, Commercial, GPL with Premium Features)
|
|
* Time-based vs Version-locked license key differences
|
|
* License states (Active, Grace Period, Expired, Invalid)
|
|
* Deployment options (Cloud-only, Self-hosted, Hybrid)
|
|
* Step-by-step configuration examples for each setup
|
|
* Commercial License Key Manager setup and requirements
|
|
* Troubleshooting and FAQ
|
|
|
|
==== Key Migration Considerations
|
|
|
|
* *License Key Format Change:* Version 7 keys are **not compatible** with {productname} {release-version}. New keys use the prefix `T8LK:` for commercial licenses or `GPL+T8LK:` for GPL with Premium Features.
|
|
* *Mandatory Key Requirement:* Self-hosted deployments now **require** a valid license key; without one, the editor will be set to readonly.
|
|
* *Commercial License Manager:* Self-hosted commercial deployments **require** the new license key manager addon.
|
|
|
|
==== Migration Steps
|
|
|
|
. *Obtain New License Key:*
|
|
** link:https://www.tiny.cloud/contact/[Contact us] to obtain a new {productname} {release-version} license key, or use `gpl` for the open source version. See: xref:license-key.adoc#setting-the-license[setting the license] for details.
|
|
|
|
. *Update Configuration:*
|
|
+
|
|
[source, javascript]
|
|
----
|
|
// Old TinyMCE 7 configuration
|
|
tinymce.init({
|
|
selector: '#editor',
|
|
// No license key required
|
|
});
|
|
|
|
// New TinyMCE 8 configuration
|
|
tinymce.init({
|
|
selector: '#editor',
|
|
license_key: 'T8LK:...' // New format required
|
|
});
|
|
----
|
|
|
|
==== License Key Manager Setup
|
|
|
|
When migrating to TinyMCE {release-version} with a commercial license, the license key manager addon is required for the editor to operate. The setup varies based on your deployment method:
|
|
|
|
. *CDN/Static Hosting:*
|
|
** Ensure the supplied `licensekeymanager` folder is in your {productname} plugins directory:
|
|
+
|
|
[tree]
|
|
----
|
|
your-site/
|
|
├── tinymce/
|
|
│ └── plugins/
|
|
│ ├── licensekeymanager/ # Add this folder
|
|
│ │ ├── plugin.min.js
|
|
│ │ └── index.js
|
|
│ └── ... other plugins
|
|
----
|
|
|
|
. *NPM/Module Bundler:*
|
|
** Install TinyMCE and ensure the license key manager is imported:
|
|
+
|
|
[source, javascript]
|
|
----
|
|
// Import TinyMCE
|
|
import tinymce from 'tinymce';
|
|
|
|
// Import the license key manager
|
|
import 'tinymce/plugins/licensekeymanager';
|
|
|
|
tinymce.init({
|
|
selector: '#editor',
|
|
license_key: 'T8LK:...' // New format required
|
|
});
|
|
----
|
|
|
|
. *React/Next.js:*
|
|
** When using the `@tinymce/tinymce-react` package:
|
|
+
|
|
[source, javascript]
|
|
----
|
|
import { Editor } from '@tinymce/tinymce-react';
|
|
import 'tinymce/plugins/licensekeymanager';
|
|
|
|
export default function MyEditor() {
|
|
return (
|
|
<Editor
|
|
init={{
|
|
license_key: 'T8LK:...'
|
|
}}
|
|
/>
|
|
);
|
|
}
|
|
----
|
|
|
|
. *PHP/Laravel:*
|
|
** Ensure the license key manager is included when publishing {productname} assets:
|
|
+
|
|
[source, php]
|
|
----
|
|
<script src="{{ asset('path/to/tinymce/tinymce.min.js') }}"></script>
|
|
<script src="{{ asset('path/to/tinymce/plugins/licensekeymanager/plugin.min.js') }}"></script>
|
|
<script>
|
|
tinymce.init({
|
|
selector: '#editor',
|
|
license_key: 'T8LK:...'
|
|
});
|
|
</script>
|
|
----
|
|
|
|
[IMPORTANT]
|
|
====
|
|
* The license key manager is automatically included when using Tiny Cloud.
|
|
* The plugin does not need to be added to the `plugins` configuration option.
|
|
* For bundled applications, the license key manager must be loaded before {productname} initialization.
|
|
* For bundled applications, ensure the license key manager is not excluded during build optimization.
|
|
====
|
|
|
|
For complete details on license key manager setup and troubleshooting, see xref:license-key.adoc##setting-up-the-commercial-license-key-manager[Setting up the Commercial License Key Manager].
|
|
|
|
**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
|
|
|
|
== Core API Changes
|
|
|
|
[discrete]
|
|
=== Breaking Changes Overview
|
|
|
|
IMPORTANT: The following sections detail critical changes that require updates to your code. Please review each section carefully.
|
|
|
|
=== Removed Methods
|
|
|
|
[[editor-selection-setcontent-deprecated]]
|
|
==== editor.selection.setContent
|
|
[.discrete]
|
|
// #TINY-12109
|
|
|
|
The `editor.selection.setContent` API has been deprecated and will be removed in {productname} 9.
|
|
|
|
.Example Usage
|
|
[source,javascript]
|
|
----
|
|
// Deprecated in TinyMCE 8, will be removed in 9
|
|
editor.selection.setContent('<p>New content</p>');
|
|
|
|
// Recommended replacement
|
|
editor.insertContent('<p>New content</p>');
|
|
----
|
|
|
|
*Impact*: This change simplifies content manipulation by consolidating insertion methods.
|
|
|
|
**Migration checklist:**
|
|
|
|
* [ ] Replace all instances of `editor.selection.setContent` with `editor.insertContent`
|
|
* [ ] Update custom plugins that use the old method
|
|
* [ ] Test content insertion in your editor instances
|
|
|
|
'''
|
|
|
|
[[editor-documentbaseurl-removal]]
|
|
==== editor.documentBaseUrl
|
|
[.discrete]
|
|
// #TINY-12236
|
|
|
|
The undocumented `editor.documentBaseUrl` property has been removed.
|
|
|
|
.Example Usage
|
|
[source,javascript]
|
|
----
|
|
// Removed in TinyMCE 8
|
|
console.log(editor.documentBaseUrl);
|
|
|
|
// Use this instead
|
|
console.log(editor.editorManager.documentBaseURI);
|
|
----
|
|
|
|
TIP: Use `editor.editorManager.documentBaseURI` for all base URL operations.
|
|
|
|
.Required Changes
|
|
* Update all base URL references to use `editor.editorManager.documentBaseURI`
|
|
|
|
For more information regarding URL handling, see: xref:url-handling.adoc#document_base_uri[document_base_uri].
|
|
|
|
'''
|
|
|
|
[[skipfocus-consolidation]]
|
|
==== skipFocus and skip_focus
|
|
// #TINY-12044
|
|
|
|
The `skipFocus` and `skip_focus` options for the `ToggleToolbarDrawer` command have been consolidated into a single, more consistent argument. This reduces API complexity and clarifies the intended behavior.
|
|
|
|
[source, javascript]
|
|
----
|
|
// Old approach (Deprecated) in TinyMCE 8
|
|
editor.execCommand('ToggleToolbarDrawer', { skip_focus: false }, { skipFocus: true });
|
|
|
|
// New approach (Recommended)
|
|
editor.execCommand('ToggleToolbarDrawer', false, { skipFocus: true });
|
|
----
|
|
|
|
**Impact**: This change simplifies focus management, reducing the risk of confusion and unexpected behavior.
|
|
|
|
**Migration checklist:**
|
|
|
|
* [ ] Locate all instances of `ToggleToolbarDrawer` command usage
|
|
* [ ] Replace `skip_focus` with `skipFocus` in command options
|
|
* [ ] Update any custom plugins using this command
|
|
* [ ] Test toolbar drawer behavior after changes
|
|
|
|
|
|
=== Deprecated Methods
|
|
|
|
[[fire-method-deprecation]]
|
|
==== `fire()`
|
|
// #TINY-11692
|
|
|
|
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');
|
|
----
|
|
|
|
**Impact**: This change aligns {productname} with modern event handling conventions, making the API more intuitive for developers.
|
|
|
|
**Migration checklist:**
|
|
|
|
* [ ] Search codebase for all uses of the `fire()` method
|
|
* [ ] Replace each instance with `dispatch()`
|
|
* [ ] Review and update third-party plugins
|
|
* [ ] Test all custom event handling
|
|
|
|
|
|
=== Plugin Updates
|
|
|
|
==== List Plugin Updates
|
|
// #TINY-11937
|
|
|
|
The list plugin now includes configurable indentation level restrictions to prevent excessive nesting of list items. This change helps maintain cleaner document structure and improves compatibility with various export formats.
|
|
|
|
[source, javascript]
|
|
----
|
|
// Configure maximum list indentation levels
|
|
tinymce.init({
|
|
max_list_indent: 3 // Restricts list indentation to 3 levels
|
|
});
|
|
----
|
|
|
|
**Impact**: Lists will no longer indent beyond the configured maximum level.
|
|
|
|
**Migration checklist:**
|
|
|
|
* [ ] Audit existing content for deeply nested lists
|
|
* [ ] Determine appropriate maximum indentation level for your use case
|
|
* [ ] Configure `max_list_indent` setting
|
|
* [ ] Test list behavior with existing content
|
|
|
|
==== Language Pack Filename Changes
|
|
// #TINY-12090
|
|
|
|
Language pack filenames have been standardized to follow the RFC5646 format. This change ensures consistent language handling across different platforms and improves internationalization support.
|
|
|
|
**Impact**: Custom language packs using the old naming format will need to be updated.
|
|
|
|
**Migration checklist:**
|
|
|
|
* [ ] Identify all language pack files in your deployment
|
|
* [ ] Rename files to RFC5646 format (e.g., `en_GB.js` → `en-GB.js`)
|
|
* [ ] Update configuration references to language files
|
|
* [ ] Update build scripts that handle language files
|
|
* [ ] Test language switching in your application
|
|
* [ ] Update custom translation files to new format
|
|
|
|
[source, javascript]
|
|
----
|
|
// Old configuration
|
|
language_url: '/langs/en_GB.js'
|
|
|
|
// New configuration
|
|
language_url: '/langs/en-GB.js'
|
|
----
|
|
|
|
==== Update to Image and Accessibility Checker Plugins
|
|
// #TINY-12235
|
|
|
|
The Image and Accessibility Checker plugins now follow the latest W3C standards for decorative images, requiring an empty alt attribute rather than a `+role="presentation"+` attribute. This change helps improve accessibility support.
|
|
|
|
**Impact**: Customers using these plugins will need to update their configurations to ensure continued compliance with accessibility standards.
|
|
|
|
**Migration checklist:**
|
|
|
|
* [ ] Identify images previously using `role="presentation"` for decorative purposes in your content
|
|
* [ ] Replace those with empty alt attributes (`alt=""`)
|
|
* [ ] Update image plugin configuration if customized
|
|
* [ ] Test accessibility checker with updated content
|
|
|
|
|
|
==== Page Break plugin update for Export PDF/Word Compatibility
|
|
// #TINY-12013
|
|
|
|
The Page Break plugin has been updated to work out-of-the-box with the xref:exportpdf.adoc[Export to PDF] and xref:exportword.adoc[Export to Word] plugins, addressing a common pain point for developers.
|
|
|
|
**Impact**: This change improves the export experience by providing more predictable page break behavior.
|
|
|
|
**Migration steps:**
|
|
|
|
* If the old behavior is preferred, explicitly set the `pagebreak_separator` option:
|
|
|
|
[source, javascript]
|
|
----
|
|
pagebreak_separator: '<!-- my page break -->'
|
|
----
|
|
|
|
The default value has been changed to produce a page break in both the xref:exportpdf.adoc[Export to PDF] and xref:exportword.adoc[Export to Word] service, such as:
|
|
|
|
.Example
|
|
[source, javascript]
|
|
----
|
|
pagebreak_separator: '<div style="break-after: page"></div>'
|
|
----
|
|
|
|
==== `pagebreak_split_block` plugin option defualt has been updated
|
|
// #TINY-12462
|
|
|
|
The default value of the xref:pagebreak.adoc#pagebreak_split_block[`pagebreak_split_block`] option has changed from `false` to `true`. This means that by default, inserting a page break will now automatically split block elements (such as paragraphs, lists, or tables) at the cursor position.
|
|
|
|
**Impact**: This change affects how page breaks interact with block elements, providing a more intuitive editing experience.
|
|
|
|
**Migration steps:**
|
|
|
|
* If you want to maintain the previous behavior where page breaks do not automatically split block elements, add the following to your configuration:
|
|
|
|
[source, javascript]
|
|
----
|
|
tinymce.init({
|
|
// ...other configuration options...
|
|
pagebreak_split_block: false
|
|
});
|
|
----
|
|
|
|
=== Technical Improvements and Cleanup
|
|
|
|
==== Cross-Origin Resource Loading Configuration
|
|
// #TINY-12228, TINY-12326
|
|
|
|
When upgrading to {productname} 8, you will need to review and possibly update how your integration handles cross-origin resource loading. {productname} 8 provides a new configuration option for controlling the `crossorigin` attribute on loaded resources.
|
|
|
|
**What to check:**
|
|
|
|
. If you're using {cloudname}:
|
|
+
|
|
* Ensure your script tag includes both required attributes:
|
|
+
|
|
[source, html]
|
|
----
|
|
<script src="{cdnurl}" referrerpolicy="origin" crossorigin="anonymous"></script>
|
|
----
|
|
+
|
|
. If your application loads resources (scripts or stylesheets) from different domains:
|
|
+
|
|
* Configure the new crossorigin function in your `tinymce.init`:
|
|
+
|
|
[source, javascript]
|
|
----
|
|
tinymce.init({
|
|
selector: "textarea",
|
|
crossorigin: (url, resourceType) => {
|
|
// Returning 'anonymous' or 'use-credentials' here would explicitly set the attribute
|
|
// return 'anonymous';
|
|
// return 'use-credentials';
|
|
return undefined; // Omit the 'crossorigin' attribute for all resources by returning undefined
|
|
},
|
|
});
|
|
----
|
|
+
|
|
. If you're using content_css from a different domain:
|
|
|
|
* The `content_css_cors` option takes precedence for stylesheets.
|
|
* Review your `content_css` configuration if you use cross-origin stylesheets.
|
|
|
|
**Migration checklist:**
|
|
|
|
* [ ] Verify script tag attributes for Cloud deployments.
|
|
* [ ] Configure `crossorigin` function if using cross-origin resources.
|
|
* [ ] Test resource loading in your deployment environment.
|
|
* [ ] Review `content_css` configuration if using cross-origin stylesheets.
|
|
|
|
For complete details on the new crossorigin function API, see: xref:tinymce-and-cors.adoc#crossorigin[crossorigin configuration option].
|
|
|
|
==== Removed Empty Files
|
|
// #TINY-11287, #TINY-12084
|
|
|
|
Several empty files have been removed from the codebase to reduce clutter and improve maintenance:
|
|
|
|
* Empty CSS file from the Comments plugin
|
|
* Empty LESS file from the Mentions plugin
|
|
|
|
**Impact**: These changes have no functional impact but may affect custom build processes that explicitly reference these files.
|
|
|
|
**Migration checklist:**
|
|
|
|
* [ ] Check build processes for references to Comments plugin CSS
|
|
* [ ] Check build processes for references to Mentions plugin LESS
|
|
* [ ] Remove any imports of these empty files
|
|
* [ ] Test Comments and Mentions plugins after removal
|
|
|
|
=== Content Handling Updates
|
|
|
|
==== Improved DIV Element Handling
|
|
// #TINY-12171
|
|
|
|
The handling of `<div>` elements during cut operations has been improved to prevent issues with element structure and content preservation.
|
|
|
|
**Impact**: This change affects how div elements are handled during cut operations, particularly in complex document structures.
|
|
|
|
**Migration checklist:**
|
|
|
|
* [ ] Test cut/paste with nested div structures
|
|
* [ ] Review custom cleanup functions affecting divs
|
|
* [ ] Verify content structure after cut operations
|
|
|
|
=== Service and Configuration Changes
|
|
|
|
==== Discontinuation of Medical English (UK)
|
|
// #TINY-12255
|
|
|
|
[WARNING]
|
|
The "Medical English (UK)" dictionary has been removed due to licensing constraints. Customers using this feature must update their configurations accordingly.
|
|
|
|
**Impact**: Users relying on this dictionary will need to make alternative arrangements for medical-specific spell checking.
|
|
|
|
**Migration checklist:**
|
|
|
|
* [ ] Remove "Medical English (UK)" from spellchecker configurations
|
|
* [ ] Remove any custom dictionary integrations related to Medical English
|
|
* [ ] Test spellchecker functionality with remaining dictionaries
|
|
* [ ] Configure alternative medical dictionary if required
|
|
|
|
==== Decoupling of Service Versions from {productname} Editor
|
|
// #EPIC-247, #EPIC-265
|
|
|
|
Services previously bundled with the editor, such as Java Servlet services, are no longer included in {productname} {release-version} packages. Customers should migrate to xref:bundle-intro-setup.adoc[Containerized service deployments] or consider alternative hosting options.
|
|
|
|
**Impact**: This reduces the dependency between the editor and backend services, simplifying updates and maintenance.
|
|
|
|
**Migration steps:**
|
|
|
|
* Update the applications deployment architecture to use xref:bundle-intro-setup.adoc[Containerized services] where applicable
|
|
|
|
==== Transition from Java WAR Files to Containerized Services
|
|
// #EPIC-247
|
|
|
|
{productname} {release-version} 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
|
|
|
|
For more information on deploying the server-side components using Docker, see: xref:bundle-intro-setup.adoc[Containerized service deployments].
|
|
|
|
== Conclusion
|
|
|
|
Upgrading to {productname} {release-version} requires integrators to update their API calls, plugin configurations, and service integrations to accommodate the breaking changes introduced in this release. While some adjustments may involve significant code updates, these enhancements are intended to simplify development, and improve the overall editor experience.
|
|
|
|
For more guidance, refer to the:
|
|
|
|
* link:https://www.tiny.cloud/docs[{productname} Documentation],
|
|
* Utilize our in-house **Ask AI** widget for general support found in the bottom corner of every documentation page, or
|
|
* link:https://www.tiny.cloud/contact/[Contact {supportname}] for assistance.
|
|
|
|
For additional details on {productname} {release-version} changes, see xref:8.0-release-notes.adoc#overview[{productname} {release-version} release notes].
|