CKEditor API

The CKEditor API is new in Drupal 8.

Note that this only applies to the CKEditor module API in Drupal 8, not the CKEditor JavaScript library API – for that, see http://docs.ckeditor.com/.

For more detailed information about what this module does, see the Text Editor module documentation.

API Features

Organized by least commonly used APIs:

CKEditor Skins

CKEditor in Drupal 8 uses the Moono skin by default. This is fine for most sites, as it’s a fairly neutral skin. However, some sites want perfect integration, and in that case you can install a different skin — even one you create yourself.
To do this, 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

CSS loaded into the CKEditor iframe instance (e.g., on /node/add/article) might need adjustment to either match front-end styles (for WYSIWYG lovers) or expose structure (for semantic purists).
    – Front-end Theme CSS
Most front-end themes style elements like paragraphs, blockquotes, image captions, etc. All front-end themes should load CSS for any content that authors might create. This is done using the ckeditor_stylesheets key in your *.info.yml file. Those stylesheets will be loaded in the iframe. See Bartik example. Also check out WYSIWYG Is a Lie!
    – Module CSS
Modules loading CSS in the front-end can use hook_ckeditor_css_alter() to also load it in the CKEditor iframe.

CKEditor Plugins

Add more functionality to CKEditor!

\Drupal\ckeditor\CKEditorPluginInterface: Drupal plugins that map 1:1 with CKEditor plugins, letting Drupal know about available CKEditor plugins.

• There are four optional, additional interfaces you can implement:

1. CKEditorPluginButtonsInterface – defines toolbar buttons the plugin provides, for drag-and-drop UI configuration.
   Example: StylesCombo.
2. CKEditorPluginContextualInterface – enables the plugin conditionally, based on other enabled buttons or filters.
   Example: DrupalImageCaption enables itself if the Image button and certain filters are enabled.
3. CKEditorPluginConfigurableInterface – defines a settings form for plugin options.
   Example: StylesCombo allows custom style configuration.
4. CKEditorPluginCssInterface – defines additional CSS to load in CKEditor iframes.
   Example: DrupalImageCaption plugin loads extra CSS.

• Plugins must be annotated with @CKEditorPlugin so they can be discovered.

This includes the CKEditor plugin ID. The ID in the annotation must match the plugin name defined in JavaScript:

// The annotation in PHP must match what's defined here.
CKEDITOR.plugins.add('pluginId', { ... });

• Plugin metadata can be altered using hook_ckeditor_plugin_info_alter().
• \Drupal\ckeditor\CKEditorPluginBase provides default method implementations for common use cases (especially those with buttons).

Lastly, if you implement a new text editor plugin, you’ll likely want excellent UX for configuration. For examples, see ckeditor.drupalimage.admin.js and ckeditor.stylescombo.admin.js. This (and only this!) aspect may change in https://www.drupal.org/node/2567801.

Debugging

Drupal 8 ships with a custom optimized CKEditor build. See core/assets/vendor/ckeditor/build-config.js. The file’s comments explain how to replace the built-in (production-optimized) CKEditor build with a development one (i.e., unminified).

See Also

• CKEditor module: deeply integrated text editor
• Editor module: linking WYSIWYGs to text formats
• Filter module: text formats to sanitize user input
• Text Editor API
• Drupal 8: structured content authoring?
• CKEditor in Drupal 8: dev Q&A
• Tutorial: Create extended functionality for CKEditor in D8
• Tutorial: Make CKEditor match your front-end theme ("WYSIWYG is a lie")
• CKEditor Widget plugin development guide
• List of CKEditor-related contrib modules