From a878bf8cc8d9aaf675f2bdb9dbeccbf80ab656b4 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Mon, 14 Jul 2025 21:55:57 +1000 Subject: [PATCH] DOC-3147: Refine migration guide for TinyMCE 8.0: update breaking change descriptions, enhance license key system details, and clarify DOMPurify sanitization impacts. --- modules/ROOT/pages/migration-from-7x.adoc | 159 ++++++++++++++++------ 1 file changed, 114 insertions(+), 45 deletions(-) diff --git a/modules/ROOT/pages/migration-from-7x.adoc b/modules/ROOT/pages/migration-from-7x.adoc index 448a402d9..75c9bac4f 100644 --- a/modules/ROOT/pages/migration-from-7x.adoc +++ b/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] ---- ---- [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('

New content

'); editor.insertContent('

New content

'); ---- -*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].