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 intended to target only what's inside the editor 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.
Similarly, any CSS provided by the administrative theme could also affect the content inside the editor. You may also want to include a CSS reset to remove any inherited styles from the editor (elements in the reset should also be prefixed with `.ck-content`).
ckeditor5_stylesheets[] = css/ckeditor5reset.css ckeditor5_stylesheets[] = css/ckeditor5.css
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.