Editor Instances

---

---

⚠⚠ ⚠⚠ ⚠⚠

This wiki served in the early days of CKEditor 5 development and can be severely outdated.

Refer to the official CKEditor 5 documentation for up-to-date information.

---

---

One core concept of CKEditor 5 is that every editor created in a page is an "editor instance", being it an instance of the Editor class. Such instances provide the API entry point to manage existing editors in the page.

Creating an Editor Instance

To create an editor instance, simply call CKEDITOR.create( element, [config] ). For example:

// Create an editor that replaces <textarea id="contents"></textarea>
CKEDITOR.create( '#contents' ).then( function( editor ) {
    ...
} );

Note that create() returns a Promise because it is an asynchronous operation. Once it is done, the callback is fired, passing the editor as its parameter, enabling interacting with the created instance through JavaScript.

The CKEDITOR.instances collection contains all editor instances available in the page. To destroy an editor instance, simply call editor.destroy(). This will restore the source element and update its content with the destroyed editor data (by default but optionally).

Editor Instance Creation Workflow

The following operations are executed during the editor instance creation:

1. A reference to the original element is saved inside editor.element.
2. Configurations are saved inside editor.config.
3. The language file is loaded, if necessary, and the language resources are set inside editor.lang.
4. Plugins loaded and initialized.
5. Once the plugins are loaded, the following happens in parallel:
   • The UI library is initialized. Skin CSS files loaded. It should be possible to have CSS coming from website files though, avoiding the extra download.
   • The "Creator" is called.
   • Data is processed and loaded.

The "Creator"

The creator is responsible for bootstrapping the editor instance, especially in terms of UI. It is provided by plugins by calling editor.addCreator( name, creatorClass ).

The creator to be used in an editor instance is defined by:

1. The config.creator configuration, if defined.
2. Any of the registered creators (no order or priority defined).

Therefore, the best way to define which creator to use is by simply loading one creator plugin only.

Most commonly, the creator will hide the source element and replace it with the UI structure needed by the editor to run, bootstrapping the editor features inside it by setting the editor "root editable".

Editor Instance Content

Each editor instance will contain the following:

• One source element: editor.element.
• Instance configurations: editor.config.
• Localization and language dictionary: editor.lang.
• UI Library: editor.ui.
• Plugins: editor.plugins.
• Data: editor.setData() and editor.getData().
• Editables: editor.editables (Collection), editor.editables.root (Main Editable), editor.editables.current.

Editables

"Editables" are elements where WYSIWYG editing can be enabled. These elements are not necessarily editable by default, but editing can be activated on them through the API.

Editor features are generally (but not mandatorily) implemented in a way that editable boundaries are not broken, having only their contents touched by editing operations.

Root and Inner Editables

Each editor can have one "root editable" and several "inner editables", which are children of the root one in the DOM hierarchy.

When the user moves focus through different editables, the editor.editables.current property gets updated accordingly and editor features adapt to the current editable configurations.

Read-only vs Editable

An editable can be in read-only mode, so no editing is enabled in it. Inner-editables of such read-only editable can instead have editing enabled with a call like the following:

editable.isReadOnly = false;  // or "true" to disable, ofc

Even the root editable can be read-only and have inner editables with editing enabled. This could be enabled automatically on editor creation by using contenteditable="true/false" in the root and inner editables which would be automatically be listed as editables into the editor instance.

Additional Editable Features

Other than enabling the editing infrastructure in the editor, the following features are available in editables:

• Editable specific configurations. For example, the ENTER key may behave differently or different ACF rules should apply.
• Have a parent editable (except root), which configuration and features are inherited from. The root editable inherits from the editor instance itself.
• Have its own setData() and getData() methods, processed through dedicated data processors.