CKEditor API overview

Last updated on
9 January 2017

The CKEditor API is new in Drupal 8.

Note this is only covering the CKEditor Drupal 8 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 8'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';
    }
  }
}

Debugging

Drupal 8 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 8's included CKEditor build (which is optimized for production) with a build that is optimized for development (i.e. unminified).

See also

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.
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.
  • 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.

Tags