|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:
* 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:
**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}.
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.
* {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].