Migrating from TinyMCE 4-x to TinyMCE 5-0-

The new TinyMCE 5.0 editor comes with significant changes to the previous versions. Most configuration changes in TinyMCE 5.0 only affect complex use cases like adding custom components. Setting up a basic TinyMCE 5.0 instance should be the same as TinyMCE 4.x.

Tiny has worked on creating a more configurable and modern editor while retaining the familiarity of the user interface from the older versions.

This chapter describes the migration process and workarounds for customers using TinyMCE version 4.x. It includes tasks that must be performed before the migration can begin, and different workaround procedures for deprecated, deleted, and updated features.

Editor-Core

Cloud Delivery

To serve TinyMCE 5 from the cloud, include this in your html page:

<script src="https://cloud.tinymce.com/5/tinymce.min.js?apiKey=your_API_key"></script>

To serve the latest nightlies and testing builds refer to the cloud deployment guide

<script src="https://cloud.tinymce.com/5-dev/tinymce.min.js?apiKey=your_API_key"></script>

Initialization

The initialization process of TinyMCE 5.0 is the same as TinyMCE 4.x. The bootstrap process and initialization events all remain the same. It still retains a familiar JSON structure. Some init configuration in the TinyMCE version 5.0 has been updated to simplify the configuration options, specifically the configuration items for UI components. Please see the Quick start section for more information on setup.

These changes may impact integrations depending upon the level of customization. Refer to the table below for a general guide for understanding the impact on a specific integration scenario:

Note: For support related issues such as problems while migrating and a workaround, please contact support. Alternatively, track developer preview issues on GitHub, here.

Methods

• All TinyMCE 4.x methods for creating UI components have been removed. New methods have been added for TinyMCE 5.0. For more information, see the docs.
• No core editor methods were removed (tinymce, editor, selection, on(), etc. remain the same).

Settings

In TinyMCE 5.0, some configurations have been removed because they are no longer necessary or an improved solution has been introduced.

Added settings

Removed settings

• file_browser_callback - Previously, the file_browser_callback option was used to add a file or image browser to TinyMCE. This feature was deprecated in version 4.1.0 and replaced by file_picker_callback. file_browser_callback option has been removed from TinyMCE 5.0 owing to the configuration changes in the dialog component.

• insert_button_items - Previously, the insert_button_items option was used to specify what to display in the insert toolbar button’s menu in a space-separated list of menu items control identifiers or | for a menu separator. This toolbar button has been removed from TinyMCE 5.0 owing to the changes in the menus and removal of the context property. For a workaround, configure a custom toolbar button using the following configurations in the tinymce.init:

tinymce.init({
  ...
  toolbar: 'insert',
  setup: function (editor) {
    editor.ui.registry.addMenuButton('insert', {
      icon: 'plus',
      tooltip: 'Insert',
      fetch: (callback) => callback('image link | inserttable')
    });
  }
});

Changed settings

file_browser_callback → file_picker_callback

When migrating from using file_browser_callback to file_picker_callback, there is no longer any need to manually find and update the element or fire events. Instead a callback function is now provided that will update the component with the value passed. In addition to that, it’s possible to update other fields by passing a second argument that will update other fields in the dialog. For more information about the file_picker_callback, see the docs.

Below is a basic example showcasing how to migrate from using file_browser_callback to file_picker_callback, assuming that browseFiles is a function that opens an external file picker.

TinyMCE 4.x

tinymce.init({
  ...
  file_browser_callback_types: 'file image media',
  file_browser_callback: function (fieldId, value, type, win) {
    browseFiles(value, type, function (fileUrl) {
      win.document.getElementById(fieldId).value = fileUrl;
    });
  }
});

TinyMCE 5.0

tinymce.init({
  ...
  file_picker_types: 'file image media',
  file_picker_callback: function (callback, value, meta) {
    browseFiles(value, meta.filetype, function (fileUrl) {
      callback(fileUrl);
    });
  }
});

Themes

In TinyMCE 5.0, some themes have been removed and are now combined in a new single responsive theme called Silver. In TinyMCE 5.0 Silver is enabled by default, if a theme is not specified. The Silver theme contains a set of configurable UI components that could be used to replace the current customizations (modern, inline, and inlite theme).

Removed themes

Inlite

The Inlite theme is no longer supported in TinyMCE 5.0. The features that the Inlite theme used to provide are now available as a plugin. The inlite plugin has been renamed quickbars. The following is an example of the current quickbars configuration:

{
  theme: 'silver',
  inline: true,
  toolbar: false,
  menubar: false,
  plugins: [ 'quickbars' ]
}

This will provide a similar but improved distraction-free experience in TinyMCE 5.0.

Modern

The Modern theme is no longer supported in TinyMCE 5.0. The modern theme’s UI library tinymce.ui.* has also been deleted. This change may impact integrations depending upon the level of customization.

Note: For support related issues such as problems while migrating and a workaround, please contact support. Alternatively, track developer preview issues on GitHub, here.

Events

Removed events

Mobile support

In TinyMCE 4.x, mobile support was introduced bundled with a new theme and configuration settings. TinyMCE 5.0 makes this process seamless where mobile support comes out of the box without any additional configurations. The mobile theme will be automatically loaded if a user views the editor on a mobile phone. TinyMCE 5.0 mobile will be an exciting space to watch.

Components

Method Namespacing changes

The methods for registering components have moved to a different part of the editor API. They are now in the UI Registry part of the editor API.

Changed methods

New methods

The following new methods have been added for creating and using new components:

Custom toolbar buttons

The methods for adding Custom toolbar buttons have changed significantly between TinyMCE 4.x and TinyMCE 5.0. The methods have been moved from editor.* to editor.ui.registry.* Toolbar button types have changed from - basic, split, listbox, and menu, to - basic, toggle, split, and menu. Explicit methods have been added for creating each type of toolbar button.

Changed methods

Some of the methods from TinyMCE 4.x for creating custom toolbar buttons have been moved and re-implemented to use the TinyMCE 5.0 style of configuration. For more information on how these methods have changed, see docs.

New methods

New methods have been added for creating other common types of toolbar buttons. For example, to create a toggle button In TinyMCE 5.0 editor.ui.registry.addToggleButton() is used. Each of these methods takes configurations specific to their type, to simplify implementation.

For more information on how these methods have changed, see docs.

Removed toolbar button types

Listbox is no longer a supported toolbar button type in TinyMCE 5.0. Though listbox has been removed, any functionality provided by custom listbox toolbar buttons can be retained by switching to a different kind of toolbar button using the new methods. The recommended toolbar button type to switch to is the Split button.

Toolbar configuration differences between TinyMCE 4.x and TinyMCE 5.0:

onclick → onAction

onclick is now onAction. The callback function given to onAction should take a buttonApi argument that’s passed to the onAction callback is an object that contains some helper functions. Each type of toolbar button has a different set of API functions. See docs for more information.

Example:

TinyMCE 4.x:

editor.addButton('mybutton', {
  text: "My Button",
  onclick: () => alert("My Button clicked!")
});

TinyMCE 5.0:

editor.ui.registry.addButton('myButton', {
  text: 'My Button',
  onAction: (buttonApi) => alert('My Button clicked!')
});

cmd → onAction

cmd: string has been removed as a configuration options, and commands should be executed in onAction instead. Example:

TinyMCE 4.x:

editor.addButton('mybutton', {
  text: "My Button",
  cmd: 'mceSave'
});

TinyMCE 5.0:

editor.ui.registry.addButton('myButton', {
  text: 'My Button',
  onAction: (_) => editor.execCommand('mceSave')
});

onpostrender → onSetup

onpostrender has been removed and replaced with onSetup for menu and toolbar components. There are 3 major changes:

• While onpostrender only ran once, when the editor was created, onSetup runs every time a component is rendered, e.g. for a menu item, every time its menu becomes visible.
• onSetup now has an API containing some helper functions. Each type of toolbar button has a different API.
• onSetup can be configured to return a function, which will be automatically be called on the teardown of the component, e.g., when a menu item’s menu is closed.
  • If some functionality only runs when the editor is first initialized, it should be passed to editor.on('init', callback) as the callback function.

Caution: If onSetup listens to any events using editor.on(eventName, callback) it should return a editor.off(eventName, callback) callback to unbind the event on tear down. This is particularly important if onSetup listens to any events using editor.on(eventName, callback). Unless the event was 'init', onSetup should return (buttonApi) => ed.off(eventName, callback). The tear down callback function will automatically be called by the editor when necessary.

Example:

TinyMCE 4.x:

editor.addButton('currentdate', {
  icon: 'insertdatetime',
  tooltip: "Insert Current Date",
  onclick: insertDate,
  onpostrender: function monitorNodeChange() {
    var btn = this;
    editor.on('NodeChange', function(e) {
      btn.disabled(e.element.nodeName.toLowerCase() == 'time');
    });
  }
});

TinyMCE 5.0:

In this example, the button’s API contains isDisabled: () => boolean and setDisabled: (state: boolean) => void.

editor.ui.registry.addButton('customDateButton', {
  icon: 'insert-time',
  tooltip: 'Insert Current Date',
  disabled: true,
  onAction: (_) => editor.insertContent(toTimeHtml(new Date())),
  onSetup: (buttonApi) => {
    const editorEventCallback = (eventApi) => buttonApi.setDisabled(eventApi.element.nodeName.toLowerCase() === 'time');
    editor.on('NodeChange', editorEventCallback);
    return (buttonApi) => editor.off('NodeChange', editorEventCallback);
  }
});

Note: The callback function given to onSetup should take a buttonApi argument which is an object that contains some helper functions.

Custom menu items

The following configurations options have changed in the Custom Menu items in TinyMCE 5.0:

• addMenuItem has a new configuration.
• A new method addNestedMenuItem has been added to the options. The addNestedMenuItem is an explicit method for creating menu items that have a submenu with more menu items.
• A new method addToggleMenuItem has been added to the options. The addToggleMenuItem is an explicit method for creating toggle menu items similar to the new special toolbar button methods.
• The concept of context has been removed from menu item configurations.

New methods:

Changed methods:

The following are examples of Custom Menu Item configurations in TinyMCE 4.x and TinyMCE 5.0:

TinyMCE 4.x

editor.addMenuItem('example', {
 text: 'My menu item',
 context: 'tools',
 onclick: () => editor.insertContent('Hello world!!');
});

TinyMCE 5.0

editor.ui.registry.addMenuItem('example', {
 text: 'My menu item',
 onAction: () => editor.insertContent('Hello world!!');
});

For more information on how these methods have changed, see docs.

Custom dialogs

Dialogs are still opened via the editor.windowManager.open(config) api, however a number of configuration options have changed.

Removed settings:

New settings:

Changed settings:

Note: onchange, a callback that was previously used to detect changes on each component, has been removed. The changes are now tracked by a single callback function with the change data. Refer to the Interactive example using redial(config): void for more information.

TinyMCE 4.x

const config = {
  title: 'Insert Link',
  body: [
    {
      name: 'text',
      type: 'textbox',
      size: 40,
      label: 'Text to display',
      onchange () {
        data.text = this.value();
      }
    }
  ]
};

TinyMCE 5.0

const config = {
  title: 'Insert Link',
  body: {
    type: 'panel',
    items: [
      {
        name: 'text',
        type: 'input',
        label: 'Text to display'
      }
    ]
  },
  onChange (api, changeData) {
    if (changeData.name === 'text') {
      // Do something with the text to display changes
    }
  }
};

For more information about the new dialog configuration, see the Dialog and Dialog components docs.

Custom context toolbars

The Context Toolbar accepts toolbar buttons that were previously added to the editor using the editor’s addButton, addToggleButton, addSplitButton or addMenuButton functions. The method for creating custom context toolbars in TinyMCE 5.0 has also been changed from editor.addContextToolbar() to editor.ui.registry.addContextToolbar().

For more information on Context Toolbars, see docs.

Custom context menus

The Context menu is no longer a plugin, it is part of the core and always enabled. Where TinyMCE 4.x only supported adding registered menu items, the new context menu also allows plugins to register “sections” of the context menu. These sections are dynamic and may show or hide depending on the cursor position when the context menu is opened. For example, the default context menu config is now 'link image editimage table spelling' which are all plugin section references, not menu items. See docs

New methods:

For more information on Context Menus, see the docs.

Custom context forms

ContextForm consists of an input field and a series of related buttons. Context forms can be shown wherever a context toolbar can be displayed. Also, when a context form is registered containing a launch configuration, a special context toolbar button with name `form:${name}` is registered which will launch that particular context form. ContextForms are a generalization of the Insert Link form that existed in the original inlite theme from TinyMCE 4.

Plugins

Each release of TinyMCE adds new features and functionality. Occasionally some features and functionalities are removed because a better option is added. Here are the details about the features and functionalities that were removed in TinyMCE 5.0.

Removed features

Plugins with dialogs no longer have height or width settings for their dialogs. The dialog component now uses CSS3 and a predefined small, medium, and large template to specify the dimensions.

The following plugins from TinyMCE 4.x do not require height or width options to be specified in TinyMCE 5.0:

• Code
• Codesample
• Preview
• Template

Changed plugin settings

Please read the docs for more information on the Tiny 4.x configuration options.

Changed features

These features have either changed or have been deleted in TinyMCE 5.0.

Table

Changes between TinyMCE 4.x and TinyMCE 5.0:

• The text field for Styles have been removed from the advanced table of the dialogs. This simplifies the dialogs for users and gives the editor a stricter control over the table styles which ensures that the styles are correct.
• Improved methods for how styles are set and retrieved from tables, rows, and cells to make these operations more reliable.
• Using CSS for styling, and therefore could remove a few legacy data attributes that were set on tables, rows, and cells which are no longer the good practice. This makes the output HTML cleaner and more modern.
• When opening a properties dialog with a single table, row, or cell selected, the dialog will autofill with the relevant existing values. If multiple rows or cells are selected to open the relevant properties dialog, TinyMCE 4.x left all the dialog fields blank. TinyMCE 5.0 automatically fills values for all the selected rows or cells which have the same values. The fields which have no existing value or have different values are left empty.
• Border input field in the table properties dialog is now called Border width for better clarity.

Other removed component configuration settings

Some UI configurations in TinyMCE 5.0 have changed due to an updated UI engine. All inline style configurations have been removed in TinyMCE 5.0 in favor of modern CSS. This affects all TinyMCE 4.x UI component configurations. The table below shows UI configurations that have been removed. They are generally related to inline CSS settings.

Please see the TinyMCE 4.x docs for more information on the above settings.