close

Filter

loading table of contents...

Studio Developer Manual / Version 2301

Table Of Contents

10.1.2.7 Rich Text Plugin

This plugin provides a data processor for CKEditor 5, so that you can load CoreMedia Rich Text 1.0 into CKEditor 5. Understanding this plugin and its configuration is crucial for integrating most of the plugins provided by CKEditor 5 as well as, when you want to provide support for additional attributes and elements as they are known by HTML5, for example.

The data-processor also defines some reserved classes, which are applied as class attribute values, which are important to understand, when designing the delivery of contents on your web page. These classes include, for example, p--heading-1, to denote a paragraph as to be rendered as <h1> or more sophisticated classes such as tr--header, td--header to be rendered as <thead> and <th> respectively.

The plugin is bundled in the npm package @coremedia/​ckeditor5-coremedia-richtext. For more details regarding this plugin and its configuration consult CoreMedia CKEditor 5 Plugin: Rich Text.

The plugin is part of the Studio Essentials Plugin plugin.

Note on Strictness

Apart from the element and attribute mappings, the Rich Text plugin also ships with a sanitation layer. This layer is responsible to store data on server at best effort. Best effort means, that the resulting data after data processing must represent valid CoreMedia Rich Text 1.0. Sanitation ensures that, for example, any invalid elements are removed at last processing stage, so that all other data are kept.

Unknown Element Example: You added the Highlight introducing the <mark> element to CKEditor 5. As initially no mapping exists for that element, the purpose of sanitation is to remove the element prior storing it on server, so that at least the data including the text wrapped by the <mark> element are stored on server.

The sanitation itself provides a configuration regarding the level of sanitation as can be seen in Example 10.1, “Strictness Configuration”. Four different values are possible, where LOOSE is the default and the others are STRICT, LEGACY and NONE.

// Strictness also exported in CoreMediaStudioEssentials for lean
// dependency management.
import CoreMediaStudioEssentials, { Strictness } from
  "@coremedia/ckeditor5-coremedia-studio-essentials/CoreMediaStudioEssentials";

// Alternative import location:
// import { Strictness } from
//   "@coremedia/ckeditor5-coremedia-richtext/Strictness";

ClassicEditor.create(domElement, {
  plugins: [
    // Typical dependency used to also integrate Rich Text Plugin.
    CoreMediaStudioEssentials,
    // ...
  ],
  "coremedia:richtext": {
    // The default strictness level.
    strictness: Strictness.LOOSE,
  },
});

Example 10.1. Strictness Configuration


Available Strictness levels:

Loose (Default)

By default, the Rich Text plugin ships with a strictness level loose, which is recommended for best robustness and enough for the given purpose. This will validate the data after data processing short before sending it to server. In contrast to simple validation, it tries to repair a possibly invalid state. This includes removing unknown elements or attributes as well as adding possibly missing required attributes.

Such invalid states should not occur in production, but may be a result in development processes, like when you enabled a plugin for a new HTML element, but did not adapt the data processing yet. The sanitation ensures, that the data, despite this new element, can still be stored on server.

Legacy

This level is similar to the CKEditor 4 behavior. It also validates the element structure and known and required attribute names, but it skips validating attribute values. The result may not represent valid CoreMedia Rich Text 1.0 and should be used with care. It just exists for best compatibility towards CKEditor 4.

One example attribute, which is handled different to loose mode is dir: Only values ltr and rtl are supported. loose mode will remove the dir attribute on any different value. legacy mode instead will keep it.

Strict

This is the highest sanitation level. It does not only check for valid DTD, but regarding attribute values, also checks, what attribute values are meant to be. Thus, attributes like width and height for <img> elements may, according to DTD, contain strings. In strict mode, they are enforced to be numeric.

None

This disables any sanitation. It is like taking away a safety net. In general, this is not recommended, as it requires perfectly shaped data processing rules, which never result in possibly invalid CoreMedia Rich Text 1.0. It may help setting this level while debugging (see Section 10.1.4, “Debugging CKEditor 5”) and if you experience any performance issues during sanitation process.

Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

Please use Mozilla Firefox, Google Chrome, or Microsoft Edge.