When adapting CKEditor 5 as described in Section 10.3, “CKEditor 5 Customization” or for contacting the CoreMedia support team, it may sometimes be important to understand the details of interaction between CoreMedia Studio and CKEditor 5. In this section, you will get a short glimpse on how to do that.

The (or one) key to success is the ckdebug hash-parameter you may add to the CoreMedia Studio URL, like http://localhost:3000/#ckdebug=verbose, where the parameter value denotes the verbosity of the output. Without a parameter value, it defaults to log level INFO.

Regarding data-processing of CoreMedia Rich Text 1.0 provided by Rich Text Plugin the most important keywords to look for in the browser console are HtmlDomConverter and CoreMediaRichText.

While HtmlDomConverter will tell step by step, which transformation steps have been applied either from CoreMedia Rich Text 1.0 to CKEditor 5 data view or vice versa, CoreMediaRichText summarizes in- and output, provides details on the sanitation process (responsible for ensuring valid CoreMedia Rich Text 1.0 even on corrupted data-processing) and details on the configured rule sets.

Rules Overview

Data-processing rules are provided as plain array of mapping rules, similar to firewall or mail-filter rules. If you want to validate, that your rule is active and processed in expected order (if order matters), you may find debugging output as sketched in Example 10.27, “CoreMediaRichText: Rules Overview”.

CoreMediaRichText: 16 rule configurations added.
toData Rules (16):
    toData-transform-xlink-attributes
    replace-i-by-em
    replace-b-by-strong
    replace-s-by-span.strike
    replace-del-by-span.strike
    replace-strike-by-span.strike
    replace-u-by-span.underline
    ...
toView Rules (12):
    toView-transform-xlink-attributes
    replace-em-by-i
    replace-span.strike-by-s
    replace-span.underline-by-u
    replace-span.code-by-code
    replace-p.p--div-by-div
    replace-p.p--heading-#-by-headings
...

Note, that especially for debugging purpose, it is recommended adding a descriptive ID to the rule. You will see a generic ID otherwise in output. Utility methods for mapping that ship with CoreMedia CKEditor 5 Plugins generate these IDs automatically.

Rules Execution

At first glance, if you see something missing in the editing view or later in the data stored on the server, you may want to compare the corresponding values. See the corresponding example outputs in Example 10.28, “CoreMediaRichText: From Data to Data View” and Example 10.29, “CoreMediaRichText: From Data View to Data”.

CoreMediaRichText: Transformed RichText to HTML within 2.1 ms:
{
  in: '<?xml version="1.0" encoding="utf-8"?>
    <div xmlns="http://www.coremedia.com/2003/richtext-1.0"
         xmlns:xlink="http://www.w3.org/1999/xlink">
      <p>Lorem</p>
    </div>'
  out: '<p>Lorem</p>'
}

CoreMediaRichText: Transformed HTML to RichText within 1.6 ms:
{
  in: '<p>Lorem</p>'
  out: '<?xml version="1.0" encoding="utf-8"?>
    <div xmlns="http://www.coremedia.com/2003/richtext-1.0">
      <p>Lorem</p>
    </div>'
}

For more details, have a look at output of HtmlDomConverter, with entries similar to those shown in Example 10.30, “To Data Processing: Processing Stages”. They will tell you, in what stage of processing and in which order rules are applied. In the given example you see, that the transformation of <h1> to the well-known representation in CoreMedia Rich Text 1.0 as <p class="p--heading-1"> happens in a stage called imported. This stage information may help you to analyze your data-processing if it provides unexpected results. For details on these stages, have a look at Section 10.2.10, “Rich Text Plugin” and the referenced documentation in CoreMedia CKEditor 5 Plugins workspace.

HtmlDomConverter:
  convert(#document-fragment) {
    input: '#document-fragment: type: 11, contents: <h1>Hello World!</h1>'
  }

...

convert(H1) {
  input: '<h1>: ...'
}

convert(H1); Stage: prepared {
  input: '<h1>: ...',
  prepared: '<h1>: ...'
}

convert(H1); Stage: imported {
  input: '<h1>: ...',
  imported: '<p>: ...'}

... children being processed ...

convert(H1); Stage: importedWithChildren {
  input: '<h1>: ...',
  importedWithChildren: '<p>: ...'
}

...

HtmlDomConverter: convert(H1); Stage: Done. {
  input: '#document-fragment: type: 11, contents: <h1>Hello World!</h1>',
  output: '#document-fragment: type: 11,
    contents:
      <p xmlns="http://www.coremedia.com/2003/richtext-1.0"
         class="p--heading-1">
        Hello World!
      </p>'}
...

For details regarding data-processing and transformation within the layers of CKEditor 5 you may want to have a look at Section 10.1.1, “Glance at CKEditor 5 Architecture”.

Sanitation

The Sanitation is responsible for handling any XML elements, attributes or structure that would not validate when send to the server. Thus, it is a kind of firewall, to ensure, that the data provided by the editor are stored on the server at best effort. For details see Section 10.2.10, “Rich Text Plugin” and especially Section “Note on Strictness”.

Typically, you will see debugging output similar as shown in Example 10.31, “Sanitation: Default Operation”. It signals standard operation with no applied modifications. If you have an element in data view, where a corresponding mapping is missing, you will instead get a warning (with preceding debug information) as shown in Example 10.32, “Sanitation: Warnings”. Such warnings typically signal, that you should adjust your data-processing. The example output tells you about a <mark> element left at parent element <p>, that is not supported by CoreMedia Rich Text 1.0. In the given case, sanitation will remove the <mark> element and replace it by its children within the given parent node.

To fix such issues, you should adapt your data processing configuration as sketched in Section “Configure Data-Processing”.

[DEBUG] CoreMediaRichText:
  Sanitation done:
    Visited Elements: 5;
    Removed: 0 severe of 0 total;
    Removed Invalid Attributes: 0,
    Maximum Element Depth: 1;
    Duration (ms): 0.10000002384185791

[DEBUG] CoreMediaRichText: Removing mark (type: 1, parent: p): invalidAtParent

[WARN] CoreMediaRichText:
  Sanitation done with issues (turn on debug logging for details):
    Visited Elements: 3;
    Removed: 1 severe of 1 total;
    Removed Invalid Attributes: 0,
    Maximum Element Depth: 2;
    Duration (ms): 0.5