guideEditor bundle

# Overview

An “editor bundle” is the source code of a pre-configured and ready-to-use CKEditor 5 editor, which is minified and merged into a single file. Such a properly prepared editor is required to use the document storage as well as import and export features.

A correctly built editor must be uploaded to CKEditor Cloud Services because it is used to convert operations that are in the collaboration session to data (HTML, Markdown, text etc. depending on your editor configuration). Without the uploaded editor CKEditor Cloud Services will not be able to convert the document to a form that looks the same as the collaborating user sees.

The same editor bundle should also be used by the collaborating users on your website.

Whenever you change something in your editor bundle or its configuration, you should re-upload it to CKEditor Cloud Services. It prevents the use of different versions of the editor bundle on your website and on the CKEditor Cloud Services server.

Otherwise, if the changes you make to the editor or its configuration affect the appearance or formatting of the document, the document data will look different than on your website. Even worse, some issues with converting the user operations on the CKEditor Cloud Services server may appear in such scenario.

# Building the editor bundle

You can build your editor just like it is done in the official CKEditor 5 documentation.

However, for your editor to be used by CKEditor Cloud Services, it must fulfill certain requirements, as explained below.

# Requirements

The following conditions must be met for an editor bundle to be supported by CKEditor Cloud Services.

Adding a plugin by passing the config.plugins option to the static create() method is not possible because your editor config is sent to CKEditor Cloud Services in a JSON format with your editor bundle. Objects or functions that can be Plugins cannot be sent in this format.

As such, the only way to add plugins to the editor is to use the static builtinPlugins property.

Using the CKEditorCS name is compulsory because CKEditor Cloud Services can only use your editor under the CKEditorCS class name.

# Uploading the editor bundle

If you have already built your editor, you must upload it to the server together with the editor configuration. The editor upload process requires the use of the POST /editors method described in the Editors REST API section.

Two required parameters are passed to the body of this method:

  • bundle – The code of your minified editor in a form of a string.

Before you upload your editor to the CKEditor Cloud Services server, make sure it was built in accordance with the requirements mentioned above.

  • config – This is the editor configuration that you will also use on your website. See the Editor configuration section below for more details.

  • testData – This is the real document content generated by the editor you upload to the CKEditor Cloud Services server. It helps to detect if any of your custom plugins modify the document content incorrectly or an invalid configuration has been passed.

It is highly recommended to test the uploaded editor using real document content.
When you pass testData during the editor upload, it is more certain that the editor will save the data correctly.
Make sure that the content you test has been created using all the custom plugins you have implemented and that it contains as many HTML elements as possible, especially if your custom plugins modify the document content.

See the Retrieve the test data example section below for more details.

# Editor configuration

CKEditor 5 configuration sent to the CKEditor Cloud Services server should be identical to the editor configuration used on your website. The editor configuration must be prepared in the JSON format, with the settings for config.cloudServices and the required bundleVersion property inside.

{
  "cloudServices": {
    "bundleVersion": "unique_editor_bundle_version"
  }
}

Note that bundleVersion is a property that acts as a unique build identifier.

It is assumed that whenever you change something in your bundle or its configuration, you should re-upload it to CKEditor Cloud Services with a new bundleVersion.

The bundleVersion property is required in the configuration used on your website and in the configuration uploaded to CKEditor Cloud Services.

# Retrieve the test data example

  1. Temporarily store the reference to the editor:
const config = { ... }; // The editor configuration.

CKEditorCS
    .create( document.querySelector( '#editor' ), config )
    .then( editor => {
        // Temporarily store the reference to the editor.
        // It allows you to get the data when you finish the document writing process.
        window.editor = editor;
    } )
  1. Write the document content using all custom plugins you have implemented in the editor.

  2. Open the browser console and use the command below to retrieve the testData:

window.editor.getData( { trim: 'none' } )

Refer to the Getting and saving data documentation of CKEditor 5 for more examples.

# Editor upload request body example

The following is an example for the body of the editor upload request:

{
  "bundle": "content string of the editor bundle",
  "config": {
    "cloudServices": {
      "bundleVersion": "unique_editor_bundle_version"
    }
  }
}

Remember that the editor bundle that you uploaded is only available within the environment to which it was assigned. If you use the same editor for different environments, you must upload it separately for each of them.

# Example

Check an example of creating an editor bundle in Node.js.