loading table of contents...

Headless Server Developer Manual / Version 2310

Table Of Contents

5.1 Rich Text Output

Delivering CoreMedia RichText properties requires a transformation of the internally stored markup format into a format that can be serialized to JSON output and that matches the requirements of the client. This process is handled by a configurable set of Rich Text Transformers per RichTextTransformerRegistry. Each transformer handles a specific transformation aspect required by the client, for example:

  • Generate a text only teaser from the first paragraph of a richtext property.

  • Generate a full HTML representation of a detail text including embedded images and internal links.

Transformers are applied to the raw content of a GraphQL field on either of these types:

  • String: A string representation of the complete Markup.

  • RichTextTree: A custom scalar GraphQLType that defines a tree based representation of the markup.

  • [CMLocalized!]: A list of all embedded content objects within the markup.

The output format may be specified by the transformation name in a GraphQL query with a view clause, where the name of the view is equivalent to the transformation name.

Please note, that the term 'view' is not connected in any way to the views of the CAE used for rendering the same content for different display purposes!

    richtext-field-name {
      graphQL-field-name(view: "transformation-name")

      text: (view: "plainFirstParagraph")

Names of the currently predefined views are:


Delivers the complete content of the requested field, consisting of all embedded markup, links and images, for instance. This view is the default, if no view is specified.


Delivers the complete content of the requested field, where special embedded markup like links and images is replaced by a plain version.


Delivers the first paragraph of the requested field without any embedded markup.

Please also note that, for technical reasons, the delivered content in all views is always nested in a <div> tag

Rich text transformers are fully configurable via YAML configuration files. Each configuration defines the following elements:


The transformer’s view name.


List of rich text elements. Is included at the start of the YAML definition. Individual elements are accessed by reference from following handlers.


List of known rich text CSS class names. Is included at the start of the YAML definition. Individual names are accessed by reference from following handlers.


List of processing contexts. Each context defines a list of handlers, which are responsible for:

  • Processing opening and closing elements.

  • Processing text nodes.

  • Transforming elements and attributes.


Defines the root context.


An optional mapping of named handler lists. Allows grouping and reusing handlers in different contexts.

Writing a new transformer is easily accomplished. First, create a YAML text file and place it in the Blueprint in the folder resources/richtext. The name of the file should match the name of the view used later in your GraphQL queries, for example a transformer named 'myView':


As a starting point, add this basic content to your transformer file:

    #!import file=includes/elements.yml
    #!import file=includes/classes.yml
    #!import file=includes/attributes.yml

    name: myView
      - &root !RootContext
        name: root
          - - !Handler
              eventMatcher:   !Matcher {qname: }
              outputHandler:  !ElementWriter {writeCharacters: true}
    initialContext: *root

Note that the file name (without the suffix) matches the ‘name’ property. As mentioned above, any transformer consists of the top level YAML properties ‘name’, ‘elements’, ‘classes’, ‘contexts’, ‘handlerSets’ and ‘initalContext’, which are all included in this basic example file.

When writing a configuration in YAML style, the indention is most important. For a reference about YAML you may refer to

Search Results

Table Of Contents

Your Internet Explorer is no longer supported.

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