Studio Developer Manual / Version 2310
Table Of ContentsThis 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";
// Alternative import location:
// import { Strictness } from
// "@coremedia/ckeditor5-coremedia-richtext";
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 valuesltrandrtlare supported. loose mode will remove thedirattribute 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
widthandheightfor<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.
