Browse Source

DOC-3147: Refine migration guide for TinyMCE 8.0: update breaking change descriptions, enhance license key system details, and clarify DOMPurify sanitization impacts.

pull/3781/head
Karl Kemister-Sheppard 3 weeks ago
parent
commit
a878bf8cc8
  1. 159
      modules/ROOT/pages/migration-from-7x.adoc

159
modules/ROOT/pages/migration-from-7x.adoc

@ -19,33 +19,37 @@ 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]
|xref:license-key-system-update[License Key System]
|Self-hosted deployments now require a new license key format and license key manager. Old keys are **not compatible**.
|High
|xref:dompurify-update-breaking-change[DOMPurify Update and Stricter Sanitization]
|Sanitization is now stricter; content previously allowed may be stripped or altered. See migration guide for details.
|xref:dompurify-update-breaking-change[DOMPurify Update]
|Sanitization is now stricter; content previously allowed may be stripped or altered.
|High
|xref:editor-selection-setcontent-deprecated[editor.selection.setContent] Deprecated
|xref:editor-selection-setcontent-deprecated[editor.selection.setContent]
|Method deprecated. Use `editor.insertContent` instead.
|Medium
|xref:fire-method-deprecation[fire()] Method Deprecation
|xref:fire-method-deprecation[fire()]
|Method deprecated. Use `dispatch()` for event handling.
|Medium
|xref:pagebreak-split-block-default[pagebreak_split_block Default Value]
|xref:pagebreak-split-block-default[pagebreak_split_block]
|The default value changed from `false` to `true`, affecting how page breaks interact with block elements.
|Low
|xref:editor-documentbaseurl-removal[editor.documentBaseUrl] Removal
|xref:editor-documentbaseurl-removal[editor.documentBaseUrl]
|Undocumented property removed. Use `editor.editorManager.documentBaseURI` instead.
|Low
|xref:skipfocus-consolidation[skipFocus and skip_focus] Consolidation
|xref:skipfocus-consolidation[skipFocus and skip_focus]
|Options consolidated to `skipFocus` in `ToggleToolbarDrawer`.
|Low
|xref:split-button-css-breaking-change[Split buttons]
|Split button CSS classes and structure have changed.
|Low
|===
====
@ -58,7 +62,9 @@ Any items marked **"High"** level require immediate attention during migration.
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:
{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
@ -68,17 +74,22 @@ This section applies to self-hosted installations only. For cloud deployments, l
* Commercial License Key Manager setup and requirements
* Troubleshooting and FAQ
==== Key Migration Considerations
**Impact**: The new license key system introduces breaking changes that require updates to your configuration and code.
* *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.
**Key Migration Considerations**:
==== Migration Steps
* *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.
. *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.
**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]
@ -98,11 +109,12 @@ tinymce.init({
==== 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:
When migrating to {productname} {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:
. *CDN/Static Hosting:*
** Ensure the supplied `licensekeymanager` folder is in your {productname} plugins directory:
+
[tree]
----
your-site/
@ -114,9 +126,10 @@ your-site/
│ └── ... other plugins
----
. *NPM/Module Bundler:*
** Install TinyMCE and ensure the license key manager is imported:
+
*NPM/Module Bundler:*
Install {productname} and ensure the license key manager is imported:
[source, javascript]
----
// Import TinyMCE
@ -131,9 +144,10 @@ tinymce.init({
});
----
. *React/Next.js:*
** When using the `@tinymce/tinymce-react` package:
+
*React/Next.js:*
When using the `@tinymce/tinymce-react` package:
[source, javascript]
----
import { Editor } from '@tinymce/tinymce-react';
@ -150,24 +164,25 @@ export default function MyEditor() {
}
----
. *PHP/Laravel:*
** Ensure the license key manager is included when publishing {productname} assets:
+
*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:...'
});
tinymce.init({
selector: '#editor',
license_key: 'T8LK:...'
});
</script>
----
[IMPORTANT]
====
* The license key manager is automatically included when using Tiny Cloud.
* The license key manager is automatically included when using {companyname} 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.
@ -196,14 +211,20 @@ This change improves security and aligns with DOMPurify's recommended defaults.
==== Key Changes
* **DOMPurify upgraded to 3.2.6** — The custom patch is now included upstream; maintaining a forked patch is no longer required.
* **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 Guidance
*Impact*: This change improves security by preventing potential XSS attacks through comments and attributes that were previously allowed. However, it may also result in content being stripped or altered unexpectedly.
**Migration Steps:**
* Review workflows and test content that previously relied on relaxed sanitization.
* If custom comment handling is required, consider using DOMPurify hooks as recommended by the maintainers.
* If custom comment handling is required, note that DOMPurify hooks cannot be used directly unless you fork TinyMCE or disable TinyMCE's built-in sanitization and implement your own with DOMPurify.
* {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.
.Example: Content Differences
|===
@ -227,6 +248,46 @@ This change improves security and aligns with DOMPurify's recommended defaults.
For information on disabling DOMPurify sanitization (not recommended), see xref:security.adoc#xss_sanitization-option[xss_sanitization option].
====
== Core Changes
[[split-button-css-breaking-change]]
=== Split button CSS structure updates
// #TINY-8665
{productname} {release-version} updates the internal structure of split buttons. Split buttons now render as two separate components with updated CSS classes:
* `.tox-split-button__main` — Main action button
* `.tox-split-button__chevron` — Dropdown chevron button
**Impact**: This change improves the flexibility of split button styling and allows for more granular control over each component.
**Migration steps:**
Update all CSS selectors and styles that previously targeted the unified `.tox-split-button` class to target the new `.tox-split-button__main` and `.tox-split-button__chevron` classes.
[source,css]
----
/* Before TinyMCE 8.0 */
.tox-split-button {
/* Previous styling approach */
}
/* TinyMCE 8.0+ */
.tox-split-button__main {
/* Main button styling */
}
.tox-split-button__chevron {
/* Chevron button styling */
}
----
**Migration checklist:**
* [ ] Search your CSS for `.tox-split-button` and update to use `.tox-split-button__main` and `.tox-split-button__chevron`.
* [ ] Test all split button styles in your application to ensure they render correctly.
* [ ] Update any custom plugins that use split buttons to reflect the new structure.
== Core API Changes
[discrete]
@ -243,6 +304,12 @@ IMPORTANT: The following sections detail important changes that require updates
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]
----
@ -253,8 +320,6 @@ editor.selection.setContent('<p>New content</p>');
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`
@ -282,7 +347,9 @@ console.log('documentBaseURI', editor.documentBaseURI.getURI());
TIP: Use `tinymce.activeEditor.documentBaseURI.getURI()` for all base URL operations.
.Required Changes
**Impact**: This change improves URL handling consistency by removing an undocumented API that was not aligned with the documented `documentBaseURI` property.
**Migration steps:**
To update all references of `documentBaseUrl` to the new API, replace any usage of `editor.documentBaseUrl` (or similar) with `tinymce.activeEditor.documentBaseURI.getURI()`. The property `documentBaseUrl` has been removed, and the correct way to access the document base URL is now through the `documentBaseURI` property, which is a URI object. You can then call `.getURI()` on it to get the string value of the URL.
@ -316,6 +383,10 @@ For more information see: link:https://www.tiny.cloud/docs/tinymce/latest/apis/t
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.
**Impact**: This change simplifies focus management, reducing the risk of confusion and unexpected behavior.
**Migration steps:**
[source, javascript]
----
// Old approach (Deprecated) in TinyMCE 8
@ -325,8 +396,6 @@ editor.execCommand('ToggleToolbarDrawer', { skip_focus: false }, { skipFocus: tr
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
@ -403,7 +472,7 @@ The Image and Accessibility Checker plugins now follow the latest W3C standards
**Migration checklist:**
* [ ] Identify images previously using `role="presentation"` for decorative purposes in your content
* [ ] Replace those with empty alt attributes (`alt=""`)
* [ ] Replace those with empty alt attributes `alt=""`
* [ ] Update image plugin configuration if customized
* [ ] Test accessibility checker with updated content
@ -554,8 +623,8 @@ Upgrading to {productname} {release-version} requires integrators to update thei
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/docs[{productname} Documentation].
* {productname}’s new **Ask AI** widget is ready to assist you, just click the icon in the bottom-right corner of any documentation page.
* 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].
Loading…
Cancel
Save