Migration guide from v11.2.0 to v12.0.0

[Reinmar]

Migration guide for CKEditor 5 v12.0.0.

The following are the most important changes and ways to update your code. The list has been split into a section for developers integrating the editor into their systems and a section for plugin authors. However, depending on the CKEditor 5 Framework features that you used you may need to check both sections.

Integration developers

editor.getData() returns an empty string

The editor.getData() method returns an empty string if the editor is empty. If you preferred the old behaviour, then you can use it like this:

editor.getData( { trim: 'none' } ); // -> '<p>&nbsp;</p>'

Modifying editable element attributes

Prior to v12.0.0 the editable attributes could have been changed in various ways. For instance directly via:

editor.ui.view.editable.editableElement.setAttribute( 'spellcheck', 'false' ); // INCORRECT!

Since v12.0.0 the only correct and reliable way to manage editable elements attributes is via the editing view, so, through the engine:

editor.editing.view.change( writer => {
    writer.setAttribute( 'spellcheck', 'false', editor.editing.view.document.getRoot() );
} );

Accessing the editable element

Prior to v12.0.0 you could access the editable element via editor.ui.view.editable.editableElement. The assumption was, therefore, that there's only a single editable element in the entire editor.

Since v12.0.0 the editor UI assumes the existance of multiple editable roots. Therefore, the correct way to access the editable DOM element is via:

editor.ui.getEditableElement( 'editableName' ); // -> Element

However, since all official editors contain just one editable (which is called main like the engine's root), you can access it like this:

editor.ui.getEditableElement(); // -> Element

Main editor UI element

Prior to v12.0.0 you could access the editor's main UI element (its UI container) via editor.element.

Since v12.0.0 that property has been moved to:

editor.ui.element; // -> Element

Image upload adapters

The FileLoader#file property now returns a promise instead of a File object directly. See an example how to modify your upload adapter in: https://github.com/ckeditor/ckeditor5-image/pull/282/files.

Plugin developers

Conversion helpers

The conversion helpers which were available in the @ckeditor/ckeditor5-engine/src/conversion/upcast-converters and @ckeditor/ckeditor5-engine/src/conversion/downcast-converters modules and required importing are now available directly on the for() function.

For instance, prior to v12.0.0:

import { upcastElementToElement } from '@ckeditor/ckeditor5-engine/src/conversion/upcast-converters';

// ...

editor.conversion.for( 'upcast' ).add( upcastElementToElement( { view: 'p', model: 'paragraph' } ) );

Since v12.0.0:

editor.conversion.for( 'upcast' ).elementToElement( { view: 'p', model: 'paragraph' } );

You can still use editor.conversion.for( ... ).add() method to define totally custom converters, but the conversion helpers are now available only on the for() object.

Mark your widget as isObject in the schema

All model elements which are represented as widgets in the view should be marked with isObject (and isBlock or isInline) in the schema.

If you see that editor.getData() returns an empty string when your widget is the only content of the editor, then there's a high chance that you forgot to use isObject in its schema definition.

Other changes

• The editor#dataReady event was removed. The editor.data#ready event has been introduced and should be used instead.
• The editor#pluginsReady event was removed. Use Plugin#afterInit() method instead.
• The editor#uiReady event was removed. Use editor.ui#ready event instead.
• Other breaking changes in ckeditor5-engine.
• Breaking changes in ckeditor5-widget.
• Breaking changes in ckeditor5-ui.