Migrating from TinyMCE 5 to TinyMCE 6

Previously, when loading a requested resource, the AddOnManager passed a success or failure callback to report the status of the request. In TinyMCE 6, AddOnManager reports this status by returning a Promise.

Previously, the change event was triggered by the first modification made to a TinyMCE editor instance. However, subsequent changes did not cause the event to fire until focus was switched away from the editor.

For example, typing a single character into the TinyMCE editor text-entry area triggered the change event. Subsequent typing, or selecting of the entered character and modifying it by setting it to bold or italic, did not trigger further change events. Making further modifications and then switching focus away from the editor did trigger this event, however.

As of TinyMCE 6, the change event is not fired unless and until

Previously, when a component in a TinyMCE dialog box changed — for example, when a next or previous button was clicked — the entire dialog box was re-rendered.

In TinyMCE 6.0, the initialData type in the dialog redial API uses object diffing for the passed spec. As a consequence, the API now only re-renders the portions of a dialog that have changed.

Previously, multiple TinyMCE APIs used disable or disabled in their function or property names.

In TinyMCE 6, these function names have been changed and configuration changes are required.

The fire() method in

has been renamed to dispatch().

fire has been aliased to dispatch, so existing integrations should still work as expected.

fire has also, however, been marked as deprecated. Using dispatch() in place of fire() is recommended.

In TinyMCE 6.0, plugins (and other addons) are no longer initialized with the new keyword.

As a consequence, the plugin initializer value passed to PluginManager.add must be a function. It cannot be a class. (The plugin initializer value is the second argument passed to PluginManager.add().)

This change makes it safe to use both older functions and newer arrow functions when instantiating add-ons.

Previously, using closeButton to disable the close button on a Notification required a timeout value to also be set.

In TinyMCE 6 this requirement was removed; closeButton now shows or hides the close button regardless of whether a timeout value is set or not set. An editor.notificationManager with both timeout: 5000 and closeButton: false set will still present a notification that automatically closes after displaying for 5 seconds.

Previously, when loading a requested resource, the PluginManager passed a success or failure callback to report the status of the request. In TinyMCE 6, PluginManager reports this status by returning a Promise.

Previously, when loading a requested resource, ScriptLoader passed a success or failure callback to report the status of the request. In TinyMCE 6, ScriptLoader reports this status by returning a Promise.

The SetContent event’s content property has been deprecated.

When the SetContent event fires, any data in content has already been added to the TinyMCE editor instance and cannot be altered, making content essentially moot as an SetContent property.

To alter such data before it is added to the TinyMCE editor, use the content property available in the BeforeSetContent event.

Previously, when loading a requested resource, StyleSheetLoader passed a success or failure callback to report the status of the request. In TinyMCE 6, StyleSheetLoader reports this status by returning a Promise.

Previously, when loading a requested resource, the ThemeManager passed a success or failure callback to report the status of the request. In TinyMCE 6, ThemeManager reports this status by returning a Promise.

Previously, the mceInsertTable command worked in two modes.

If invoked without arguments —

tinymce.activeEditor.execCommand('mceInsertTable');

— the command opened the Insert Table dialog box.

If invoked with arguments —

tinymce.activeEditor.execCommand('mceInsertTable', false, { rows: 2, columns: 2 });

— the command inserted a table, with the specified properties, directly into the document without opening the Insert Table dialog box.

In TinyMCE 6.0, the mceInsertTableDialog command must be used to invoke the Insert Table dialog box.

Previously, mceAddEditor and mceToggleEditor used the editorManager.settings values to set the id and UI and UX options for a new TinyMCE editor instance.

editorManager.settings is not used at all in TinyMCE 6 and has been removed.

Instead, the mceAddEditor and mceToggleEditor commands use id and options values from an object passed in when the command is run.

For example —

tinyMCE.execCommand('mceAddEdit', false, { id: 'ed-1', options: { readonly: false, toolbar: 'bold italic strikethrough' } })

— finds a textarea with id ed-1 and turns it into a working TinyMCE editor that displays the bold, italic, and strikethrough buttons in the editor toolbar.

Previously, element_format had no explicit default value. It’s implicit value, however, was xhtml.

In TinyMCE 6.0, element_format now has an explicit default value: html.

This new, and explicit default changes how entered material is serialised. In particular, self-closing elements, such as <hr>, <br>, and <img> no longer present in the xhtml standard fashion, as <hr />, <br />, and </img /> respectively.

Previously the images_upload_handler option passed success or failure callbacks to report the status of an image upload. In TinyMCE 6, images_upload_handler reports upload results by returning a Promise.

The link_default_protocol option sets the link protocol used by links added or edited using the link dialog.

It now defaults to 'https'. Previously it defaulted to 'http'.

Previously, the list of configured plugins could be retrieved by calling editor.getParam('plugins') and returned the configured plugins as a string.

As of TinyMCE 6, the list of configured plugins is retrieved by calling editor.options.get('plugins') and now returns the configured plugins as an array.

TinyMCE 6.0 allows plugin loading in any of three formats:

Previously, one other format was allowed: arrays of space-separated strings. This format is no longer accepted in TinyMCE 6.0.

All references to any of these plugins should be removed from plugin configurations.

See below for specific documentation of potential migration issues, if any, regarding these removed plugins.

Five plugins were removed as per the previous TinyMCE 5 announcement:

Four plugins were removed because their functionality is now a Core part of TinyMCE 6.0:

The functionality from these plugins is now enabled automatically, except for paste which as previously announced no longer supports cleaning Microsoft Word content.

Three plugins have been empty stub plugins since TinyMCE 5.0, and were removed in TinyMCE 6.0:

As noted in the TinyMCE 6.0 Release Notes, the imagetools plugin is no longer included as part of the Free editor.

Image Tools is now Enhanced Image Editing, a Premium plugin.

The imagetools_proxy option has been renamed to editimage_proxy. However, when setting up Tiny services the recommended configuration is now editimage_proxy_service_url and will be used in favour of editimage_proxy if both are set.

Users of the Free version of TinyMCE 5.x who rely on the removed imagetools plugin should not upgrade to TinyMCE 6.0 without a subscription plan that provides access to Enhanced Image Editing.

As noted in the TinyMCE 6.0 Release Notes, the media plugin no longer uses the SaxParser.

As a consequence the iframe, video, audio, and object elements are no longer marked as special, and cannot be marked as such. Put another way, the DOM parser does not preserve embedded content.

Instead these elements, and their contents, are validated against the TinyMCE schema.

This validation is generally done by the valid_elements, valid_children or extended_valid_elements config.

The schema must, therefore, be configured to allow usage of the media elements, and the media element attributes.

The getUsers API was a part of the mentions plugin and was used to retrieve a list of mentioned users in the current editor session.

This API has been deprecated in TinyMCE 6.0.

Refer to the TinyMCE 6.0 Release Notes for an alternative to the getUsers API.

As noted in the TinyMCE 6.0 Release Notes, the paste plugin’s functionality is no longer provided as a plugin. It is now a core part of TinyMCE 6.0.

In conjunction with this change, three changes have been made:

The tabfocus plugin has been removed. It is no longer part of TinyMCE 6.0. And it is not otherwise available.

The tabfocus_elements option, which relied on the tabfocus plugin, no longer functions.

As per standard web practice, the tabindex attribute should be used instead of the tabfocus plugin or any of the tabfocus plugin’s options.

The tab order of a page’s elements, including TinyMCE, is configured by setting the tabindex attribute on the relevant HTML elements. The browser then natively handles the tab order.

To configure tabindex for the TinyMCE editor, set the attribute on the target element for the editor. For example:

In iframe (classic editor) mode, TinyMCE copies the tabindex attribute from the target element to the editor’s iframe, to allow this to work correctly.

As noted in the TinyMCE 6.0 Release Notes, the toc plugin is no longer part of the Free editor.

Table of Contents has been updated and is now a Premium plugin.

Users of the Free version of TinyMCE 5.x who rely on the, now deprecated and removed, toc plugin, should not upgrade to TinyMCE 6.0 without a subscription plan that provides access to Premium plugins such as Table of Contents.

The new Premium tableofcontents plugin also changes the names of several elements.

Any configurations or logic that use the old element names must be updated to the new names after upgrading to TinyMCE 6.0 and installing the new tableofcontents plugin.

buttonType is a new property available for button components used in dialogs. It replaces the, now deprecated property, primary.

The primary property was boolean, allowing for only two states: true and false.

The new buttonType property can take any of three states: 'primary', 'secondary', and 'toolbar'.

Setting buttonType: 'primary' is the same as setting primary: true.

Setting buttonType: 'secondary' is the same as setting primary: false.

In TinyMCE 5.x, editors without a height value specified in the TinyMCE configuration defaulted to a height of 200px In TinyMCE 6.0, editors without a height value specified in the TinyMCE configuration default to 400px.

As was the case in TinyMCE 5.x, this new default only applies to editors in iframe mode, not inline mode.

The new default can be overridden by explicitly setting a height value in the TinyMCE configuration. So setting this to 200px will recreate the previous default presentation.

Also, setting the CSS height of the element replaced by TinyMCE to a value larger than 400px will increase the editor height. Setting the element’s CSS height to a value less than 400px will not reduce the height of the editor, however.

This default can be overridden as part of an initialization configuration. Setting min_height to > 400 will increase the height of the initial TinyMCE editor.

But setting a value below 100 makes it possible for manual, end-user re-sizing to reduce the TinyMCE editor to a horizontal sliver (or, potentially, make it disappear entirely). Setting min_height to < 100 is not recommended

The names of the following user-interface and user experience elements were changed.

The primary property was a boolean property available as a basic panel component of dialogs.

It has been deprecated and replaced by the new buttonType property.

TinyMCE previously used float to position tables to the left or right of the viewport (the working area available to the TinyMCE editor). This caused multiple layout and UX problems.

For example, consider a TinyMCE document that included a table that took up less than 100% of the viewport and a paragraph of text below that table. If both the table and the paragraph were selected and their alignment was changed to left or right, the paragraph of text moved up beside the table.

As another example, consider a TinyMCE document containing a table that is wider than the viewport. If you selected this table’s contents and set the alignment to right, the portion of the table that was outside the viewport disappeared to the left, and no scrollbar presented allowing you to bring that portion back into view.

As of TinyMCE 6.0, tables are positioned using margin rather than float. This prevents these layout and UX problems occurring.

However, when upgrading to TinyMCE 6.0, there are two things to be aware of:

First, TinyMCE 6.0 does not alter existing documents. Extant TinyMCE documents with tables that were aligned to either left or right will still have the float property assigned when opened and edited unless and until their alignment is altered.

If an extant TinyMCE document with an aligned table is opened using TinyMCE 6.0 and the alignment of the table is re-set, TinyMCE 6.0 will remove the float property and use the margin property to set the alignment.

Second, if the previous behavior is required, a custom format will need to be created. Specifically, the following format (the table-specific code from TinyMCE 5.x’s DefaultFormats.ts) must be added to the format configuration:

Alternatively, the Formatter API can be used to register a custom format using editor.formatter.register(<name>, <format>).

Previously, before HTML content was passed to TinyMCE 5.x, it was parsed using an in-house developed API, SaxParser.

The SaxParser API was developed in the then-absence of alternatives.

When this API’s validate setting was enabled — validate: true — SaxParser removed elements and attributes that did not fit the declared schema.

And, over its lifetime, SaxParser was extended. For example, as of TinyMCE 5.9, the SaxParser API marked attributes with certain names or IDs as unsafe, because some names or IDs can cause the host browser to overwrite existing properties or functions.

Since TinyMCE 6.0, this basic parser was removed and replaced with two significantly more thorough alternatives:

Before HTML (or XML) content is passed to TinyMCE 6, the DOMParser API parses the HTML (or XML) string into a DOM object. As part of this process, DOMParser attempts to correct malformed HTML.

For example, the following string:

When this string is passed in, the DOMParser API adds the missing closing anchor tag:

Next, the, now correctly formed, DOM object is passed to DOMPurify.

DOMPurify runs a security-focused ruleset over the DOM object to sanitize the HTML and protect TinyMCE, and applications using TinyMCE, against XSS attacks.