CKEditor 4 API overview

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', { ... });

• Discovered plugins' annotation metadata can be altered using hook_ckeditor_plugin_info_alter().
• \Drupal\ckeditor\CKEditorPluginBase provides a default implementation so CKEditor plugins don't need to implement every method. Which means it must optimize for the most common case: it is only useful for plugins that provide buttons.

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

• CKEditor module: deeply integrated text editor
• Text Editor module: associating assistive editors with text formats
• Filter module: text formats that filter user input
• Text Editor API
• Drupal 8: best authoring experience for structured content?
• CKEditor in Drupal 8: site builders & developers Q&A's
• Tutorial: Creation of extended functionality for the basic CKEditor in Drupal 8
• Tutorial: How to make CKEditor match your front-end theme ("The WYSIWYG is a Lie")
• About developing CKEditor Widget plugins: Introduction to Widgets
• List of CKEditor-related contrib modules for Drupal 8