ckeditor5-3228346

CONTENTS OF THIS FILE

• Introduction
• Installation
• Development
• Drupal Plugins
• Drupal CKEditor plugins
• Toolbar Admin
• Configuration
• Maintainers

INTRODUCTION

Provides the CKEditor 5 rich text editor for use with Drupal.

• For a full description of the module, visit the project page: https://drupal.org/project/ckeditor5

• To submit bug reports and feature suggestions, or to track changes: https://drupal.org/project/issues/ckeditor5

INSTALLATION

• Install as you would normally install a contributed Drupal module. See https://www.drupal.org/docs/extending-drupal/installing-modules for more information.

DEVELOPMENT

There are two Drupal specific CKEditor 5 applications. There's an application for rendering the CKEditor toolbar configuration UI in js/admin. Application containing Drupal specific plugins is located in js/drupal.

Both of these applications can be built with the following commands:

• yarn packages:install
• yarn packages:build

Note: yarn packages:install does not update yarn.lock meaning that if you have made changes to packages.json, yarn install needs to be run manually for that package to update yarn.lock.

DRUPAL PLUGINS

Drupal plugins may use either yml or a php Annotation for their definitions. A php class does not need an Annotation if it is defined in yml.

The module yml file should be named {module_name}.ckeditor5.yml, it will be discovered if it ends in .ckeditor5.yml.

The minimally required metadata: the CKEditor 5 plugins to load, the label and the HTML elements it can generate — here's an example for a module providing a Marquee plugin, both in yml and Annotation form:

MODULE_NAME_marquee:
  ckeditor5:
    plugins: [PACKAGE.CLASS]
  drupal:
    label: Marquee
    elements:
      - <marquee>

and

 * @CKEditor5Plugin(
 *   id = "MODULE_NAME_marquee",
 *   ckeditor5 = @CKEditor5AspectsOfCKEditor5Plugin(
 *     plugins = { "PACKAGE.CLASS" },
 *   ),
 *   drupal = @DrupalAspectsOfCKEditor5Plugin(
 *     label = @Translation("Marquee"),
 *     elements = { "<marquee>" },
 *   )
 * )

The metadata relating strictly to the CKEditor 5 plugin's JS code is stored in the ckeditor5 key; all other metadata is stored in the drupal key.

If the plugin has a dependency on another module, adding the provider key will prevent the plugin from being loaded if that module is not installed.

If the plugin needs to provide dynamic values, these can be provided by a php class. To make this class discoverable, either:

add class to the yml definition:

MODULE_NAME_marquee:
  ckeditor5:
    …
  drupal:
    class: \Drupal\{module_name}\Plugin\CKEditor5Plugin\{class_name}

or add the Annotation to the php class so that it can be discovered.

@CKEditor5Plugin(
  id = "module_name.plugin_name"
  { ...additional definitions }
)

@see Annotation\CKEditor5Plugin.php

Definitions should either be in yml or the php annotation, they are discovered either way but will not be merged if there are some definitions in each.

The php class may also be used for overriding definitions or for validation, for example to ensure an editor setting is compatible with the definitions provided by a plugin.

DRUPAL CKEDITOR PLUGINS

The Drupal CKEditor plugins should be cloned to the same folder with rest of the CKEditor 5 repositories because in order to build these packages, they need be able to read files from the main CKEditor 5 repository.

• https://github.com/zrpnr/ckeditor5-drupal-media
• https://github.com/zrpnr/ckeditor5-drupal-image

Create your own plugin using ckeditor5-drupal-image or ckeditor5-drupal-media as an example. Note in the webpack.config.js you must at minimum have:

plugins: [
  new webpack.DllReferencePlugin({
    manifest: require('../ckeditor5/build/ckeditor5-dll.manifest.json'),
    scope: 'ckeditor5/src',
    name: 'CKEditor5.dll',
  })
]

where the manifest points to the file in your local ckeditor5 repo. This allows your plugin to reference the source files in the manifest.

In your plugin instead of importing from an npm package: import Plugin from '@ckeditor/ckeditor5-core/src/plugin';

you would need to refer to that export as it is found in the manifest: import { Plugin } from 'ckeditor5/src/core';

TOOLBAR ADMIN

The toolbar admin features keyboard support and aria-live button descriptions. Source:

• https://github.com/zrpnr/ckeditor5-drupal-admin

Contributed plugins may provide an icon for their toolbar items by adding a background-image using the css class: .ckeditor5-toolbar-button-{pluginToolbarItem}

Add a library with any styles needed for your toolbar buttons using the admin_library key, it will be automatically discovered.

The toolbar admin UI loads in #ckeditor5-toolbar-app and parses the available toolbar buttons listed in #ckeditor5-toolbar-buttons-available. The selected buttons are written to the value of #ckeditor5-toolbar-buttons-selected.

The UI app currently supports announcements on the following events:

• onFocusDisabled - User focuses an item in the "available" or "dividers" list
• onFocusActive - User focuses an item in the "active" list
• onFocusActiveFirst - User focuses on the first item in the "active" list
• onFocusActiveLast - User focuses on the last item in the "active" list

The announcements describe available keyboard commands for the focused button.

CONFIGURATION

• Select CKEditor 5 as the editor for an available text format See (/admin/config/content/formats)
• Add buttons to the toolbar UI to configure the text format.
• An explicit wrapping breakpoint may be added anywhere in the toolbar to force a new toolbar line, regardless of toolbar width. Adding one or more of these buttons will automatically enable CKEditor 5's shouldNotGroupWhenFull toolbar option.
• A "Divider" may be added anywhere to create a vertical line between buttons.
• Drag any unwanted buttons back to the "Available" section to remove them.

MAINTAINERS

Current maintainers:

• Peter Weber (https://www.drupal.org/u/zrpnr)