CoreMedia CKEditor 5 Plugins

CoreMedia's CKEditor 5 Plugins provides plugins for CKEditor 5 with focus on integration into CoreMedia CMS. Since 2022 (CMS v2210.1) CKEditor 5 replaces the previous integration of CKEditor 4.

Quick Start

Requirements

• Install the required Node.js version according to engines in package.json (also: .nvmrc).

  If you have nvm installed, nvm use and/or nvm install will switch to the required Node.js version.

  NVM for Windows

  nvm use is only available for the original Linux distribution of NVM. Alternatives, such as CoreyButler.NVMforWindows (winget ID) are not aware of it. A possible alternative is nvm use $(Get-Content .nvmrc) or use Windows Subsystem Linux (WSL).

• Install the required pnpm version according to the engines entry in package.json.

Build and Start

$ pnpm install
$ pnpm -r build
$ pnpm start

Note, that pnpm install requires access to repository.coremedia.com/nexus/repository/coremedia-npm.

Since Version 44 a license key is necessary to use the CkEditor. Create a file named .env in the root of this workspace and add a line

CKEDITOR_LICENSE_KEY=<your-license-key>

The last command will start a lightweight HTTP server and by default opens http://127.0.0.1:8080/sample/ (may vary, if port 8080 is in use) in your default browser. It will provide a demo of the features providing by the plugins contained in this workspace. As alternative, open app/sample/index.html directly in your preferred browser.

Packages

Most packages are published with scope @coremedia/ as for example @coremedia/ckeditor5-coremedia-link. Others, only meant for internal workspace usage, are not published and have scope @coremedia-internal/.

Name	Description
ckeditor5-bbcode	BBCode: Data-Processor
ckeditor5-common	Common Utilities, independent from CKEditor
ckeditor5-core-common	Assistive Utilities for @ckeditor/ckeditor5-core
ckeditor5-coremedia-blocklist	Highlights words in the editor content and allows to adjust list of words.
ckeditor5-coremedia-content	Content Related Commands
ckeditor5-coremedia-content-clipboard	Clipboard Support for CoreMedia Contents
ckeditor5-coremedia-differencing	Support server-side differencing in CoreMedia Studio
ckeditor5-coremedia-example-data	Internal: Eases setup of Mock Data for testing purpose
ckeditor5-coremedia-images	Support for CMS BLOB References like images
ckeditor5-coremedia-link	Support for Content Link, Link Target Specification
ckeditor5-coremedia-richtext	CoreMedia RichText 1.0 DTD: Data-Processor
ckeditor5-coremedia-richtext-support	CoreMedia RichText 1.0 DTD: Registers known elements/attributes
ckeditor5-coremedia-studio-essentials	CoreMedia Studio: Aggregator Plugin for essential plugins
ckeditor5-coremedia-studio-integration	CoreMedia Studio: Communication facade for Studio integration
ckeditor5-coremedia-studio-integration-mock	CoreMedia Studio: Mock Communication facade for testing
ckeditor5-data-facade	Data I/O facade to prevent accidental data change propagation
ckeditor5-dataprocessor-support	Deprecated: Utilities for providing custom CKEditor 5 DataProcessors
ckeditor5-dom-converter	Base architecture for data-processing
ckeditor5-dom-support	Utilities for handling DOM objects
ckeditor5-font-mapper	Replaces characters in given font to alternative representation on paste
ckeditor5-link-common	Assistive Utilities for @ckeditor/ckeditor5-link
ckeditor5-logging	Logging Facade

The subtle difference between ckeditor5-coremedia-richtext and ckeditor5-coremedia-richtext-support is, that the latter one just adds support for attributes from CoreMedia RichText for which no editing actions are configured (yet). Simply speaking, ckeditor5-coremedia-richtext ensures, that data can be read and stored on server, while ckeditor5-coremedia-richtext-support ensures, that all valid CoreMedia RichText attributes are registered as valid within CKEditor. For details see the corresponding documentation.

Installation

Minimal

For minimal CoreMedia RichText 1.0 support, the only module to install is ckeditor5-coremedia-studio-essentials:

pnpm install @coremedia/ckeditor5-coremedia-studio-essentials

importCoreMediaStudioEssentialsfrom"@coremedia/ckeditor5-coremedia-studio-essentials/CoreMediaStudioEssentials";ClassicEditor.create(document.querySelector('#editor'),{plugins: [CoreMediaStudioEssentials,/* ... */],}).then((editor)=>{/* ... */});

These essential plugins ensure, that you can edit any CoreMedia RichText 1.0 and that any information loaded from server are not lost. This approach mainly relies on CKEditor's General HTML Support feature, telling CKEditor not to remove any not (yet) known elements or attributes from data.

For full editorial experience, you should of course install corresponding plugins, like CKEditor's text-formatting plugins or editing support for link targets (mapped to xlink:role/xlink:show in CoreMedia RichText).

Studio Integration Remarks

Autosave Feature

Alternative: For versions later than 16.0.0 we ship a so-called data facade plugin. This plugin takes care of a better behavior for data coming from external data storages, preventing "no change" data to be written back to server (without editorial interactions applied).

Still, if not relying on this recommended plugin, the following information may be valuable to you.

It is recommended, using CKEditor's Autosave plugin for saving data into CoreMedia CMS. Note though, that the Autosave plugin is automatically triggered when initialized with data received from CoreMedia CMS:

Create CKEditor → Set Data From Server → Autosave Data To Server

As CKEditor applies/has to apply some normalization to the received data (such as removing ignorable whitespace), the data set and directly afterward received on Autosave via getData() may differ (while being semantically equal).

Unhandled, and directly forwarded to server, this would trigger the so-called auto-checkout feature in CoreMedia Studio: The editor opening the affected document will own the document and will be marked as being the current editor of that document.

Thus, it is strongly recommended validating editor.model.document.version and preventing storing data on server, if these versions do not differ from previously setData() call. A typical approach is:

1. Invoke setData() for data from server.
2. Remember editor.model.document.version directly after set.
3. Wait for invocation of Autosave.
4. If editor.model.document.version is the same as remembered on set prevent forwarding the data to CoreMedia CMS.

For convenience, you may consider using the ckeditor5-data-facade that implements the described behavior.

See Also

• GitHub Pages: These pages on GitHub Pages.
• Walk-Through Examples: Some step-by-step guides for customizing CKEditor 5.
• Development: Hints for developing within this workspace
• License: Apache 2.0 License Text
• Versioning: Versioning Policy