View on GitHub

CoreMedia CKEditor 5 Plugins

CoreMedia's CKEditor 5 Plugins provides plugins for CKEditor 5 with focus on integration into CoreMedia CMS.

Download this project as a .zip file Download this project as a tar.gz file

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 npm.coremedia.io.

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-babel-config`	Internal: Shared Babel configuration.
`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-jest-test-helpers`	Support for JEST tests
`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

import CoreMediaStudioEssentials from
    "@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:

Invoke setData() for data from server.
Remember editor.model.document.version directly after set.
Wait for invocation of Autosave.
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.

CoreMedia CKEditor 5 Plugins

Quick Start

Requirements

Build and Start

Packages

Installation

Minimal

Studio Integration Remarks

Autosave Feature

See Also