Advertising sustains the DA. Ads are hidden for members. Join today

CKEditor 4 API overview

Last updated on
13 January 2023

Note that this only covers the CKEditor Drupal 9 module API, not the CKEditor JavaScript library API — for that, see http://docs.ckeditor.com/.

For high-level information on what this module does, see the Text Editor module documentation.

API features

Ordered by most to least frequently used APIs:

CKEditor skins
Drupal 9's CKEditor uses the Moono skin by default. This is fine for most sites, since it's a fairly neutral skin. Some sites want to have perfect integration though, and in that case you may want to install another skin — perhaps even one you create yourself.
To do that, implement hook_editor_js_settings_alter():
function hook_editor_js_settings_alter(array &$settings) {
  foreach (array_keys($settings['editor']['formats']) as $text_format_id) {
    if ($settings['editor']['formats'][$text_format_id]['editor'] === 'ckeditor') {
      $settings['editor']['formats'][$text_format_id]['editorSettings']['skin'] = 'SKIN_NAME,ABSOLUTE_URL_TO_SKIN';
    }
  }
}
CKEditor iframe CSS
The CSS that is loaded into a CKEditor iframe instance, for example at /node/add/article (i.e. a CKEditor instance that is not used for in-place editing) may need to be customized so that CKEditor iframe instances match the styling on the front-end (for those who prefer WYSIWYG) or to make it show the structure (for those who prefer purely assistive text editors).
Front-end theme CSS
Virtually every front-end theme has CSS to style paragraphs, blockquotes, image captions and so on. Therefore all front-end themes should tell CKEditor iframe instances to load the CSS for any content (text/markup) content creators can create. They can do that by specifying a ckeditor_stylesheets key in their *.info.yml file. The CSS assets listed there will also be loaded into the iframe. See the example in Bartik. Also see the How to make CKEditor match your front-end theme ("The WYSIWYG is a Lie") tutorial!
Module CSS
Modules that are loading CSS on the front end can use hook_ckeditor_css_alter() to also load this CSS in CKEditor iframe instances.
CKEditor Plugin plugins
Add more functionality to CKEditor!
\Drupal\ckeditor\CKEditorPluginInterface: Drupal plugins that correspond 1:1 to CKEditor plugins, to make Drupal aware of the available CKEditor plugins. Hence the — at first sight — confusing name: CKEditor Plugin plugins, but it actually makes sense!
  • There are four additional, optional interfaces you can implement
    1. \Drupal\ckeditor\CKEditorPluginButtonsInterface allows a CKEditor plugin to define which buttons it provides, so that users can configure a CKEditor toolbar instance via the the drag-and-drop-based UI.
      Example: \Drupal\ckeditor\Plugin\CKEditorPlugin\StylesCombo provides a CKEditor toolbar button (a dropdown even).
    2. \Drupal\ckeditor\CKEditorPluginContextualInterface allows a CKEditor plugin to enable itself automatically based on the context: if some other CKEditor plugin's button is enabled, if some filter is enabled, if some CKEditor plugin's setting has a certain value, or a combination of all of the above.
      Example: \Drupal\ckeditor\Plugin\CKEditorPlugin\DrupalImageCaption enables itself if the Image button is present and the alignment or caption filter is enabled.
    3. \Drupal\ckeditor\CKEditorPluginConfigurableInterface allows a CKEditor plugin to define a settings form, for configuring any settings this CKEditor plugin may have.
      Example: the \Drupal\ckeditor\Plugin\CKEditorPlugin\StylesCombo plugin allows you to configure styles that can be applied.
    4. \Drupal\ckeditor\CKEditorPluginCssInterfacesince 8.1.0 allows a CKEditor plugin to define additional CSS to be loaded in iframe instances of CKEditor.
      Example: the \Drupal\ckeditor\Plugin\CKEditorPlugin\DrupalImageCaption plugin loads additional CSS.
  • Plugin implementations must be annotated with the @CKEditorPlugin annotation so they can be discovered.
    • This includes the ckeditor plugin id; the id defined in the annotation must match the name of the plugin as defined in the plugin's javascript on the line that adds the plugin.
// The annotation in of the plugin in the php must match what is defined here.
CKEDITOR.plugins.add('pluginId', { ... });
Last but not least: when implementing a new text editor plugin, you probably also want to make sure the UX for configuring it is excellent. For that, see ckeditor.drupalimage.admin.js and ckeditor.stylescombo.admin.js for examples. Note this aspect (and only this aspect!) is subject to be changed in https://www.drupal.org/node/2567801.

Debugging

Drupal 9 includes a customized, optimized build of CKEditor. See core/assets/vendor/ckeditor/build-config.js. The documentation in that file also explains how to replace Drupal 9's included CKEditor build (which is optimized for production) with a build that is optimized for development (i.e. unminified).

See also

Tags

Help improve this page

Page status: No known problems

You can: