Skip to content

Latest commit

 

History

History
698 lines (513 loc) · 43.6 KB

migration-from-4x.md

File metadata and controls

698 lines (513 loc) · 43.6 KB
layout title title_nav description keywords
default
Migrating from TinyMCE 4 to TinyMCE 5.
Migrating from TinyMCE 4
Guidance for migrating from TinyMCE 4 to TinyMCE 5.
migration considerations premigration pre-migration

Most configuration changes in TinyMCE 5 only affect complex use cases, such as customized user interface components. The process for setting up a basic TinyMCE 5 instance is the same as TinyMCE 4.

This chapter describes the migration process and workarounds for customers using TinyMCE 4. It describes the settings that require updating prior to migration; and workaround procedures for deprecated, deleted, and updated features.

Note: For support related to migration, please contact Tiny support. Open Source users: Please report issues on the TinyMCE GitHub Repository.

Contents

Editor-Core

To migrate the core TinyMCE editor to TinyMCE 5, review the following sections:

Cloud Delivery

To use TinyMCE 5 from the {{site.cloudname}}, include this script in your HTML page. Replace 'no-api-key' with your API key.

<script src="{{ site.cdnurl }}" referrerpolicy="origin"></script>

For information on using the latest development and testing builds, see: Cloud deployment guide - Specify editor & plugin versions.

Editor: Changes to API Methods

All TinyMCE 4 API methods for creating UI components have been removed. New methods have been added for TinyMCE 5. For information on creating and customizing UI components, see: User interface components.

Editor: Changes to Settings

TinyMCE 5 includes the following changes to editor-core settings:

New Editor settings

Setting Description
custom_colors custom_colors is true by default. Setting custom_colors: false removes the custom color picker in the color swatch.

Changed Editor settings

Setting TinyMCE 4 TinyMCE 5
height Set the height of the editable area of the editor.
Supported number values.		 Sets the overall height of the editor, including the menubar, toolbars, and statusbar.
Supports numbers and strings. Assumes strings are a valid CSS value for height.
width Supported number values. Supports numbers and strings. Assumes strings are a valid CSS value for width.
resize true by default. true by default if the autoresize plugin is not enabled.
false by default if the autoresize plugin is enabled.

Removed Editor settings

  • The file_browser_callback option has been removed for TinyMCE 5. The file_browser_callback option was used to add a file or image browser to TinyMCE. This option was deprecated in version 4.1.0 and replaced by file_picker_callback.

  • insert_button_items - the insert_button_items option was used to specify the toolbar items to display in the insert toolbar button menu. This toolbar button has been removed from TinyMCE 5. 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')
    });
  }
});
Migrating from file_browser_callback to file_picker_callback

file_picker_callback provides a callback function, removing the requirement for an additional function to manually find and update the element or fire events. file_picker_callback can also update other fields by passing a second argument to update other fields in the dialog. For information on using file_picker_callback, see: Image & file upload options - file_picker_callback.

The following example shows the difference between the removed file_browser_callback setting and file_picker_callback, assuming that browseFiles is a function that opens an external file picker.

TinyMCE 4 - file_browser_callback
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 - file_picker_callback
tinymce.init({
  ...
  file_picker_types: 'file image media',
  file_picker_callback: function (callback, value, meta) {
    browseFiles(value, meta.filetype, function (fileUrl) {
      callback(fileUrl);
    });
  }
});

Browser support: backward compatibility or quirks mode

TinyMCE 5 does not support browsers running in Quirks or backward compatibility modes.

Deprecated Editor settings

New platform detection functions were to the Env API for {{site.productname}} 5.1, allowing for some older detection properties to be deprecated.

Deprecated Property Alternative Property / Reason for Deprecation Type Original Description
opera Use browser.isOpera() instead. Boolean Constant that is true if the browser is Opera.
webKit Use browser.isSafari() or browser.isChrome() instead. Boolean Constant that is true if the browser is WebKit (Safari/Chrome).
ie Use browser.version.major and browser.isIE() or browser.isEdge() instead. Number Constant that is greater than zero if the browser is IE.
gecko Use browser.isFirefox() instead. Boolean Constant that is true if the browser is Gecko.
mac Use os.isOSX() or os.isiOS() instead. Boolean Constant that is true if the operating system is Mac OS.
iOS Use os.isiOS() instead. Boolean Constant that is true if the operating system is iOS.
android Use os.isAndroid() instead. Boolean Constant that is true if the operating system is android.
desktop Use deviceType.isDesktop() instead. Boolean Constant that is true if the browser is running on a desktop device
contentEditable All supported browsers now support content editable elements. Boolean Constant that is true if the browser supports editing.
caretAfter All supported browsers now support placing carets after inline blocks. Boolean Returns true/false if the browser can or can't place the caret after a inline block like an image.
range All supported browsers now support native DOM ranges. Boolean Constant that is true if the browser supports native DOM Ranges. IE 9+.
ceFalse All supported browsers now support contentEditable=false regions. Boolean Constant that is true if the browser supports contentEditable=false regions.

Themes

Most themes provided with TinyMCE 4 have been removed from TinyMCE 5 and are now combined in a new responsive theme called Silver. The Silver theme is enabled by default and contains a set of configurable UI components that can be used to replace the functionality of the TinyMCE 4 themes: Modern, Inline, and Inlite.

Removed Theme Replaced by
Modern Silver
Modern inline Silver Inline
Inlite(Distraction-free Editor) Silver (distraction-free configuration)
Mobile Silver (responsive to small screen touch devices)

Inlite theme removed

The Inlite theme has been removed from TinyMCE 5.

The Inlite theme features are provided by the Quick Toolbar (quickbars) plugin for TinyMCE 5. The Inlite quicklink functionality is now provided by Context Forms.

The following is an example of a TinyMCE 5 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.

Modern theme removed

The Modern theme has been removed from TinyMCE 5. The Modern theme's UI library tinymce.ui.* has also been removed. This change may impact integrations depending upon the level of customization.

Themes: Removed events

Removed event Description
BeforeRenderUi Fired before the UI was rendered.

Mobile theme

The {{site.productname}} 4 Mobile theme was deprecated in {{site.productname}} 5.1. The mobile-optimized editor is loaded on mobile devices. For information on the new mobile experience, see: {{site.productname}} mobile.

User Interface components

This section covers migrating UI components to TinyMCE 5

Removed UI configuration settings

All inline style configurations have been removed in TinyMCE 5 in favor of modern CSS. This affects all TinyMCE 4 UI component configurations. Skins should be used for custom styling in TinyMCE 5.

Removed style settings:

  • flex
  • border
  • layout - Use the TinyMCE 5 UI component settings to compose a custom layout.
  • spacing
  • padding
  • align
  • pack
  • no-wrap

Changed UI API method namespace

The API methods for registering UI components have moved. They are now part of tinymce.editor.ui.registry.

Changed methods

The following methods have changed for TinyMCE 5:

Old method New method Component
editor.addButton(identifier, configuration) editor.ui.registry.addButton(identifier, configuration) Toolbar Buttons
editor.addContextToolbar: (name, spec) editor.ui.registry.addContextToolbar Context toolbar
editor.addMenuItem: (name, spec) editor.ui.registry.addMenuItem Menu item
editor.addSidebar: (name, spec) editor.ui.registry.addSidebar: (name, spec) Sidebar

New methods

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

New method Description
editor.ui.registry.addAutocompleter: (name, spec) Autocompleter
editor.ui.registry.addContextForm: (name, spec) Context form
editor.ui.registry.addContextMenu: (name, spec) Context menu
editor.ui.registry.addMenuButton: (name, spec) Menu Button
editor.ui.registry.addNestedMenuItem: (name, spec) Nested menu item
editor.ui.registry.addSplitButton: (name, spec) Split Button
editor.ui.registry.addToggleButton: (name, spec) Toggle Button
editor.ui.registry.addToggleMenuItem: (name, spec) Toggle menu item
editor.ui.registry.addIcon: (name, svgData) Registers an SVG as an icon
editor.ui.registry.getAll: () Returns an array of everything in the UI registry

Custom toolbar buttons

The API methods for adding Custom toolbar buttons have changed for TinyMCE 5. The methods have been moved from editor.* to editor.ui.registry.*. The toolbar button type listbox has been removed and a toogle button type has been added. The button types available in TinyMCE 5 are:

Listbox toolbar buttons are not supported in TinyMCE 5. The recommended replacement toolbar button type is the Split button.

Changed toolbar button API methods

The following methods for creating custom toolbar buttons have been moved for TinyMCE 5. For information on how to use the new methods, see: Toolbar buttons.

Old method New method
editor.addButton() editor.ui.registry.addButton()
editor.addMenuItem() editor.ui.registry.addMenuItem()

New toolbar button API methods

New methods have been added for creating common types of toolbar buttons.

New method Description
editor.ui.registry.addToggleButton() Adds a custom toolbar toggle button.
editor.ui.registry.addSplitButton() Adds a custom toolbar split button.
editor.ui.registry.addMenuButton() Adds a custom toolbar menu button.

For information on how to use these methods, see: Types of toolbar buttons.

Changed Toolbar API methods

Old method New method Description
onclick onAction onclick is now onAction. onAction now has an API to provide helper functions to the user. For an example migration, see: Migrating onclick to onAction.
cmd onAction cmd has been removed as a configuration option. Commands should be executed through onAction now. For an example migration, see: Migrating cmd to onAction.
onpostrender onSetup onpostrender has been replaced with onSetup. For an example migration, see: Migrating onpostrender to onSetup.
Migrating onclick to onAction

onclick is now onAction. The callback function given to onAction takes a buttonApi argument which is an object that contains helper functions.

For example:

TinyMCE 4 - onclick
editor.addButton('mybutton', {
  text: "My Button",
  onclick: () => alert("My Button clicked!")
});
TinyMCE 5 - onAction
editor.ui.registry.addButton('myButton', {
  text: 'My Button',
  onAction: (buttonApi) => alert('My Button clicked!')
});

Each type of toolbar button has a different set of API functions. For information using toolbar buttons, see: Types of toolbar buttons.

Migrating cmd to onAction

cmd: string has been removed. Commands should be executed using onAction instead.

For example:

TinyMCE 4 - cmd
editor.addButton('mybutton', {
  text: "My Button",
  cmd: 'mceSave'
});
TinyMCE 5 - onAction
editor.ui.registry.addButton('myButton', {
  text: 'My Button',
  onAction: (_) => editor.execCommand('mceSave')
});
Migrating onpostrender to onSetup

onpostrender has been replaced with onSetup for menu and toolbar components.

There are 3 major changes:

  • onpostrender was only processed when the editor was created, onSetup runs every time a component is rendered. For example: onSetup for a menu item is processed every time the menu rendered.
  • onSetup has an API containing 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, such as when a menu item's menu is closed.
    • If a function should only be executed when the editor is first initialized, use the editor.on('init', callback) 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. Unless the event was 'init', onSetup returns (buttonApi) => ed.off(eventName, callback).

For example:

TinyMCE 4 - onpostrender
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 - onSetup

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 takes a buttonApi argument which is an object that contains helper functions.

Custom context toolbars

The Context Toolbar accepts toolbar buttons to the editor using the addButton, addToggleButton, addSplitButton, or addMenuButton functions.

The API method for creating custom context toolbars in TinyMCE 5 has changed from editor.addContextToolbar() to editor.ui.registry.addContextToolbar().

For information on Context Toolbars, see: Context toolbar.

Custom menu items

The following configuration options have changed in the custom menu items for TinyMCE 5:

  • addMenuItem has a new configuration.
  • A new method, addNestedMenuItem has been added to the options. The addNestedMenuItem is a method for creating menu items that have a sub-menu with one or more menu items.
  • A new method, addToggleMenuItem has been added to the options. The addToggleMenuItem is a method for creating toggle menu items similar to the toggle toolbar button.
  • The concept of context has been removed from menu item configurations. The menu setting provides this functionality for TinyMCE 5.

To add a custom item to a menu, use the menu setting. All items in a menu need to be declared in order to appear.

For example:

tinymce.init({
  selector: '#editor',
  plugins: 'help',
  menu: {
    help: { title: 'Help', items: 'help | myCustomMenuItem' }
  },
  menubar: 'file edit help',
  setup: (editor) => {
    editor.ui.registry.addMenuItem('myCustomMenuItem', {
      text: 'My Custom Menu Item',
      onAction: () => alert('Menu item clicked')
    });
  }
});

More information

New menu item methods

New method Description
editor.ui.registry.addNestedMenuItem() Adds a menu item that opens a sub-menu.
editor.ui.registry.addToggleMenuItem() Adds a custom toggle menu item.

Changed menu item methods

Old method New method Description
editor.addMenuItem: (name, spec) editor.ui.registry.addMenuItem() Adds a custom basic menu item.

The following examples show custom menu item configurations in TinyMCE 4 and TinyMCE 5:

TinyMCE 4 - example custom menu item

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

TinyMCE 5 - example custom menu item

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

For information on how to use these methods, see: Custom menu items.

Custom dialogs

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

Removed dialog settings:
Removed setting Description
height The dialog component now uses CSS3 and a predefined small, medium, and large template to specify the dimensions.
width The dialog component now uses CSS3 and a predefined small, medium, and large template to specify the dimensions.
bodyType bodyType has been merged into the body setting.
onpostrender onpostrender has been removed for the dialog configuration. The dialog configuration now includes an initialData setting for providing the initial state and an API to fetch or update the data. Refer to this section for more information on how to configure initialData.
url URL dialogs now have their own API. For more information, see Custom URL dialogs.
New dialog settings:
New setting Description
initialData An object containing the initial value for the dialog components.
onCancel A callback that is called when the dialog is cancelled without submitting any changes.
onTabChange A callback that is called when switching tabs in a TabPanel.
Changed dialog settings:
Old setting New setting Description
onchange onChange onChange now takes a callback function which is passed an API helper function and data.

Note: The onchange callback function provided within individual components has been removed. A single onChange callback function provides the same functionality for all components in TinyMCE 5.

TinyMCE 4 - onchange

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

TinyMCE 5 - onChange

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 information about the new dialog configuration, see the Dialog and Dialog components documentation.

Changes to the Custom dialog API

A redesign of the dialog API resulted in the following changes:

Removed Custom dialog APIs
API Type Description
tinymce.WindowManager.getParams() Method Returned the params of the last window open call. This was used in iframe based dialog to get params passed from the tinymce plugin.
tinymce.WindowManager.getWindows() Method Returned the currently opened window objects.
tinymce.WindowManager.setParams() Method Set the params of the last opened window.
tinymce.WindowManager.windows Property Returned an array of opened dialogs.
Changed Custom dialog API Methods
Method Description Change
tinymce.WindowManager.alert() Creates an alert dialog. A window object is no-longer returned.
tinymce.WindowManager.confirm() Creates a "confirm" dialog. A window object is no-longer returned.
tinymce.WindowManager.close() Closes the top most window. Only closes dialogs created with open().

For information on the new Dialog API, see: UI components - Dialog instance API.

Custom URL dialogs

The URL dialogs have moved from the editor.windowManager.open() API to the editor.windowManager.openUrl() API. This provides clear separation of the two different types of dialogs in TinyMCE.

Removed URL dialog settings:
Old setting New setting Description
file url The file setting has been removed in TinyMCE 5 and replaced with url.
New URL dialog settings:
New setting Description
onCancel A callback that is called when the dialog is cancelled without submitting any changes.
onMessage A callback that is called when the dialog receives a message via the browser window.postMessage API.

TinyMCE 4 - windowManager.open()

editor.windowManager.open({
  title: 'URL Dialog Demo',
  url: 'http://mysite.com/external-page.html'
});

TinyMCE 5 - windowManager.openUrl()

editor.windowManager.openUrl({
  title: 'URL Dialog Demo',
  url: 'http://mysite.com/external-page.html'
});

For information about the new URL dialog configuration, see: URL dialog.

Plugins

The following section covers the changed and removed plugin features for TinyMCE 5.

Removed plugin settings

The height and width settings have been removed from plugin 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 do not require height or width options in TinyMCE 5:

Changed plugin settings

TinyMCE 4 TinyMCE 5
autoresize_min_height min_height
autoresize_max_height max_height
textcolor_cols color_cols
textcolor_map color_map

Changed plugins

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

Plugin name Description
ContextMenu New API. See the docs.
ColorPicker Moved to the core. See the docs.
TextColor The textcolor plugin was removed and this setting is has been replaced by text_color in TinyMCE 5.

Custom context menus

The Context menus are part of the core and enabled by default in TinyMCE 5. TinyMCE 5 supports adding registered menu items and allows plugins to register "sections" of the context menu. These sections show or hide depending on the cursor position when the context menu is opened.

For information on using context menus and the default context menu configuration, see: UI components - Context menu.

New context menu methods:
New method Description
editor.ui.registry.addContextMenu() Adds a custom context menu.

For information on Context Menus, see UI components - Context menu.

Spellchecker plugin

spellchecker_callback has been updated to remove a legacy format for the success callback, which accepted a mapping object of misspelled words to suggestions. For example:

spellchecker_callback: function(method, text, success, failure) {
    var words = text.match(this.getWordCharPattern());
    if (method == "spellcheck") {
      var suggestions = {};
      for (var i = 0; i < words.length; i++) {
        suggestions[words[i]] = ["First", "Second"];
      }
      success(suggestions);
    }
  }

The success callback now requires the mapping object to be wrapped in an object with the words key, such as:

spellchecker_callback: function(method, text, success, failure) {
    var words = text.match(this.getWordCharPattern());
    if (method == "spellcheck") {
      var suggestions = {};
      for (var i = 0; i < words.length; i++) {
        suggestions[words[i]] = ["First", "Second"];
      }
      success({ words: suggestions });
    }
  }

For information on the spellchecker_callback setting, see: Spell Checker plugin - spellchecker_callback

Table plugin

Changes between TinyMCE 4 and TinyMCE 5:

  • The text field for Styles have been removed from the advanced tab 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 valid.

  • When opening a properties dialog with a single table, row, or cell selected, the dialog will autofill with the relevant existing values. When multiple rows or cells are selected:

    • If the selected rows or cells have the same values, TinyMCE 5 automatically fills the dialog values.
    • If the fields have no existing value or have different values, the dialog fields are left empty.

  • The Border input field in the table properties dialog is now called Border width.