Change record status: 
Project: 
Introduced in branch: 
8.x
Description: 

We built the CKEditor module on top of the "pluggable text/WYSIWYG editors" foundation that was laid at #1878344: Add CKEditor JS library to core (see http://drupal.org/node/1911614 for the corresponding changelog).

This is a work in progress! We're still working on tighter integration. See Drupal core issues tagged with "CKEditor in core".

CKEditor: UI changes

CKEditor drag-and-drop configuration UI

CKEditor drag-and-drop configuration UI

CKEditor in use

CKEditor in use

Note that because CKEditor is built on top of the foundational Text Editor module, its configuration is automatically stored in the config system.

API

There's two parts: the API that allows you to provide CSS for CKEditor's iframe mode, and the API that allows Drupal modules to provide additional CKEditor plug-ins.

Provide CSS for CKEditor's iframe mode

CKEditor can run in two modes: iframe mode and "inline mode". iframe mode is used when CKEditor is applied to forms, e.g. the node/%/edit form. inline mode is used when doing in-place editing. Here is a screenshot showing both at the same time:

CKEditor through Editor.module both on regular form and for true WYSIWYG.png

When using the inline mode, CKEditor is effectively modifying the HTML to which your Drupal site's theme/CSS already applies. In other words: even while editing, everything looks exactly like it will look for the end user.
The same cannot be said of the iframe mode. Precisely because it runs in an iframe, your Drupal site's theme/CSS does not apply to it (plus, on pages like node/%/edit, the active Drupal theme is the admin/back-end theme, not the front-end theme, so even if that were not the case, you'd be out of luck). That's why it's customary to provide a CSS file for CKEditor's iframe mode to make it resemble your front-end theme as closely as possible.

In Drupal 8, themes can define style sheets specifically for CKEditor's iframe mode, which CKEditor will then automatically use. To use this, specify the following in a theme's .info file:

ckeditor_stylesheets:
  - css/ckeditor-iframe.css

There's also a corresponding alter hook, so that modules can provide CKEditor iframe mode style sheets as well:

  • hook_ckeditor_css_alter()

Provide additional CKEditor plugins

To define a CKEditor plugin in a module, create a class in {module}/src/Plugin/CKEditorPlugin/{PluginName}.php and implement \Drupal\ckeditor\CKEditorPluginInterface. This is the most basic plugin interface, and if you just implement this, it's impossible to get CKEditor to load your plugin.

The class must also declare a plugin annotation in its docblock comment. Here is an example from the drupalImage CKEditorPlugin.

/**
 * Defines the "drupalimage" plugin.
 *
 * @CKEditorPlugin(
 *   id = "drupalimage",
 *   label = @Translation("Image"),
 *   module = "ckeditor"
 * )
 */

Depending on the CKEditor plugin, you may want to implement either \Drupal\ckeditor\CKEditorPluginButtonsInterface (if the plugin has buttons; implementing this will make the buttons available in the drag-and-drop configuration UI; if the button is enabled, the plugin will be loaded automatically) or \Drupal\ckeditor\CKEditorPluginContextualInterface (if the CKEditor plugin doesn't have buttons, and it should be loaded based on the presence of another button or based on some setting).

Finally, if you want your CKEditor plugin to have settings (i.e. a form, much like the "Styles dropdown" settings form in the above screenshot) as well, you must also implement CKEditorPluginConfigurableInterface.

The most common case is to have a CKEditor plugin without settings and with just a button, so the base plugin CKEditorPluginBase that is provided implements CKEditorPluginInterface and CKEditorPluginButtonsInterface.

Detailed documentation can be found directly on these interfaces.

Finally, it is possible to alter CKEditor plugins via hook_ckeditor_plugin_info_alter().

AttachmentSize
ckeditor.png30.14 KB
ckeditor-configuration.png65.28 KB
Impacts: 
Site builders, administrators, editors
Module developers
Themers
Updates Done (doc team, etc.)
Online documentation: 
Not done
Theming guide: 
Not done
Module developer documentation: 
Not done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other: 
Other updates done