Headless Server Developer Manual / Version 2404
Table Of ContentsDelivering 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/.
