On this page
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, implementhook_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
\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).\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.\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.\Drupal\ckeditor\CKEditorPluginCssInterface
since 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.
- There are four additional, optional interfaces you can implement
- 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
andckeditor.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
Help improve this page
Page status: No known problems
You can:
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion