close

Filter

loading table of contents...

Studio Developer Manual / Version 2404

Table Of Contents

10.4 Debugging CKEditor 5

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
...

Example 10.27. CoreMediaRichText: Rules Overview


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>'
}

Example 10.28. CoreMediaRichText: From Data to Data View


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>'
}

Example 10.29. CoreMediaRichText: From Data View to Data


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>'}
...

Example 10.30. To Data Processing: Processing Stages


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

Example 10.31. Sanitation: Default Operation


[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

Example 10.32. Sanitation: Warnings


Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

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