On this page
Text Editor API overview
Last updated on
9 January 2017
The Text Editor API is new in Drupal 8. It is inspired, and in some parts functionally identical to the Drupal 7 Wysiwyg module.
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:
- Text editor dialogs: the image and link dialogs
- The image (
\Drupal\editor\Form\EditorImageDialog
) and link (\Drupal\editor\Form\EditorLinkDialog
) dialogs can both be altered. Any new form elements under$form['attributes']
will be respected by the corresponding JavaScript in the text editor, so that either the image (<img>
) or link (<a>
) will get the attributes with the values corresponding to any form elements you add by altering. - Text editor config entities
\Drupal\editor\Entity\Editor
config entity: configure text editors, one text format can have one text editor- Every text editor out there has its own way of being set up, and therefore has a different kind of settings. No matter what they are, they end up being stored in the text editor config entity. See
\Drupal\editor\EditorInterface::getSettings()
. - Text editor settings can be altered using
hook_editor_js_settings_alter()
. - Text editor plugins
\Drupal\editor\Plugin\EditorPluginInterface
: text editor plugins, to provide additional text editors (assistive editors, WYSIWYG editors …) that are available to site builders to be used- Plugin implementations must be annotated with the
@Editor
annotation so they can be discovered. - Discovered plugins' annotation metadata can be altered using
hook_editor_info_alter()
. \Drupal\editor\Plugin\EditorBase
provides a default implementation so text editor plugins don't need to implement every method.
- Plugin implementations must be annotated with the
- The above allows Drupal to be aware of how to load and configure this text editor. The Text Editor module also has a JavaScript API that allows it to invoke the specific text editor plugin's JavaScript, to initialize the text editor. For that, implement
Drupal.editors
, seeDrupal.editors.ckeditor
for an example (incore/modules/ckeditor/js/ckeditor.js
). - 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
editor.admin.js
. Note this aspect (and only this aspect!) is subject to be changed in https://www.drupal.org/node/2567801. - Text editor XSS filtering
- To completely prevent a type of security vulnerability that was encountered several times in Drupal 7 and earlier versions when text editors were being used, the Text Editor module has an additional, special/narrow purpose layer to guarantee safety for content editors. A text editor plugin can specify (in its annotation) whether its safe against XSS filtering or not. For example, a Markdown editor doesn't parse and display the raw content, which means it's guaranteed to be safe. But CKEditor actually rendered the entered HTML also, and thus extra measures are necessary.
- 99% of the time, the default implementation,
\Drupal\editor\EditorXssFilter\Standard
will be sufficient. In very advanced cases, you may want to use a custom implementation, by implementing\Drupal\editor\EditorXssFilterInterface
. - To make Drupal use a custom text editor XSS filter, implement
hook_editor_xss_filter_alter()
.
See also
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