close

Filter

loading table of contents...

Headless Server Developer Manual / Version 2301

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!

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

    Example:
    detailText{
      text: (view: "plainFirstParagraph")
    }
  

Names of the currently predefined views are:

default

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.

simplified

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

plainFirstParagraph

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:

name

The transformer’s view name.

elements

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

classes

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.

contexts

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.

initialContext

Defines the root context.

handlerSets

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

    resources/richtext/myView.yml
  

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
    contexts:
      - &root !RootContext
        name: root
        handlers:
          - - !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 https://yaml.org/.

Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

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