Backdrop 1.27.0 includes an all-new module and library for rich text editing, CKEditor 5. This is a major upgrade from CKEditor 4 and contains a completely different set of APIs.

Upgrade Process for Existing Sites and Site Owners

Upgrading from CKEditor 4 to 5 is not required (though it is encouraged). Backdrop 1.x (including 1.27.0) still includes the CKEditor 4 project. Any sites that used CKEditor 4 may continue to do so. For more information about upgrading to CKEditor 5, see the CKEditor 5 upgrade process blog post.

Changes for Themes that Provide CKEditor-specific CSS

The CKEditor 4 module provided a way for themes to provide CSS to be used within the CKEditor 4 iframe. This was done through the theme's .info file with a line such as this:

ckeditor_stylesheets[] = css/ckeditor.css

This same method can be used to provided CKEditor 5 styles by using a similarly named key:

ckeditor5_stylesheets[] = css/ckeditor5.css

CKEditor 4 used an iframe to isolate the contents of the editor from the rest of the page. Thus, CSS selectors could be generic as they would only affect the iframe contents, such as this:

h3 {
  font-size: 2em;
}

But in CKEditor 5, the editor contents are not within an iframe; it is a div within the parent page. Selectors need to add an additional parent class to target the editor contents specifically:

.ck-content h3 {
  font-size: 2em;
}

Every selector within a CKEditor 5 stylesheet should be prefixed with this .ck-content class.

Changes for Modules that Provide CKEditor Plugins

Any plugins written for CKEditor 4 are not compatible with CKEditor 5. If you had a contrib or custom module that integrated with CKEditor 4, it is recommended to take one of the following approaches:

  • Create a new branch of the project (i.e. 1.x-1.x is for CKEditor 4, and 1.x-2.x is for CKEditor 5)
  • Or create an entirely separate project (i.e. "ckeditor_codestyle" for CKEditor 4, and "ckeditor5_codestyle" for CKEditor 5)

To make clear which module your project works with, specify the module in your project's .info file:

For CKEditor 4

dependencies[] = ckeditor

For CKEditor 5:

dependencies[] = ckeditor5

Unfortunately, the plugin JS itself will need to be entirely rewritten for CKEditor 5. The Backdrop core built-in plugins within core/modules/ckeditor5/js/plugins can provide a template for creating a new CKEditor plugin. The CKEditor 5 API documentation is also a good starting point.

Introduced in branch: 
1.x
Introduced in version: 
1.27.0
Impacts: 
Module developers