Skip to content

Richtext

Jump to bottom
mweikard edited this page Nov 5, 2018 · 4 revisions

Richtext

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 Richtext Transformers per Processing Definition. Each transformer handles a specific transformation aspect required by the client, e.g.

  • Generate a text only teaser from the first paragraph of a richtext property.
  • Generate a full HTML reresentation of a detail text including embedded images and internal links.

Richtext transformer are fully configurable via YAML configuration files. Each configuration defines the following elements:

  • name: The transformer's view name.
  • elements: List of richtext elements. Is included at the start of the YAML definition. Individual elements are accessed by reference from following handlers.
  • classes: List of known Richtext 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 to group and reuse handlers in different contexts.

Output Format

The output type of a JSON Richtext attribute is defined by the GraphQL Field's type:

  • String: A string representation of the Markup. The Schema Generator generates this return type by default.
  • RichtextTree: A custom scalar GraphQL Type that defines a tree based representation of the Markup. It can be generated by customizing a field's return type, i.e.: 
    - !CustomField
  name: detailText
  sourceName: "detailText"
  targetType: RichtextTree
  dataFetcher: Richtext
    As the field's type is scalar the output is based on the serialization of the specific tree representation and cannot be accessed by GraphQL Query means.

Richtext Views

There are different options for accessing a specific Richtext view:

  1. Return a Richtext wrapper object from a field's source expression with the desired view: 
    - !CustomField
  name: teaserText
  sourceName: "new Richtext(teaserText, 'teaser')"
  2. Request a specific view from the query by using a Richtext field's optional argument view. This also overrides a view defined in the schema: 
    ...
detailText(view: "detail")
...
  3. If non of the former option applies the default view from the Processing Definition configuration file is used: 
    ...
defaultRichtextFormat: detail
...

Contexts

A context defines how to transform a specific element node of a Richtext document. For this task it has a number of registered event handlers, which apply to its subnodes.

Richtext processing always starts with a Root Context. Contexts are stacked, i.e. when encountering the start of a paragraph a new context for handling the elements within that paragraph is push on top of current context and removed when the paragraphs end.

Root Context

Type Descriptor: !RootContext

Properties:

  • name: The context's name.
  • handlers: A list of event handler lists.
  • defaultHandler: An optional default event handler which is executed if none of the other handlers applies.

Example:

- &root !RootContext
  name: root
  handlers:
    - *headline_handlers
    - *block_handlers
    - *blockquote_handlers

Context

Type Descriptor: !RootContext

Properties:

  • name: The context's name.
  • handlers: A list of event handlers.
  • defaultHandler: An optional default event handler which is executed if none of the other handlers applies.

Example:

- !Context
  name: headline
  defaultHandler:
    !Handler
    outputHandler: !ElementWriter {writeCharacters: true}
  handlers:
    - *text_handlers

Event Handler

An Event Handler applies to a specific Start Element event within the XML event stream (with the exception of default handlers).

Type Descriptor: !Handler

Properties:

  • eventMatcher: Defines the matching condition, which is the start event for a specific element node.
  • outputHandler: Defines the output generated for the matching element node.
  • contextHandler: Defines a context action for the matching node, i.e. push another context onto the context stack.

Example:

handlers:
  - - !Handler
      eventMatcher:   !Matcher {qname: *p}
      contextHandler: !Push {contextName: plaintext}
      outputHandler:  !ElementWriter {writeCharacters: true}

This examples writes all the character nodes of a paragraph to the output and installs a new context plaintext for the paragraph's element subnodes.

Event Matcher

An Event Matcher defines the condition for triggering an Event Handler.

Type Descriptor: !Matcher

Properties:

  • qName: The qualified name of the start element event.
  • classes: Optional style classes. Matches if the event's attribute class contains any of the styles.

Example:

- !Handler
  eventMatcher: !Matcher {qname: *p, classes: *headline_styles}

Context Handler

Context Handlers define a modification on the context stack.

Push Context

Type Descriptor: !Push

Properties:

  • contextName: The name of the context to install.

Replace and Push Context

Type Descriptor: !ReplacePush

Properties:

  • contextName: The name of the context to install on top of the stack.
  • replacementName: The name of the context to replace the current context with.

Output Handler

Output Handlers define the generated output for an element node.

Element Writer

The default Output Handler for element nodes.

Type Descriptor: !ElementWriter

Properties:

  • writeElement: Boolean flag indicating if the start and stop element should be written to the output. Defaults to false.
  • writeCharacters: Boolean flag indicating if the character nodes of an element should be written. Defaults to false.
  • elementTransformer: Optional transfomation rules for the element.
  • attributeTransformers: Optional transformation rules for the element's attributes.

Empty Element Writer

Writer for empty elements, e.g. br.

Type Descriptor: !EmptyElementWriter

Image Writer

Generates embedded image tags. Uses the default link builder.
The output format is fixed to

<img data-src="[LINK-URI]" alt="[IMG-ALT-TEXT]"/>

Type Descriptor: !ImgWriter

Properties:

  • attributeTransformers: Optional transformation rules for the element's attributes.

Link Writer

Generates link tags. Uses the default link builder.
The output format is fixed to

<a data-href="[LINK-URI]">...</a>

for internal links and

<a href="[LINK-URI]">...</a>

for external links.

Type Descriptor: !LinkWriter

Element Transformer

An Element Transformer allows to generate an alternate element name based on the element styles. It is used e.g. for generating HTML headlines from the Richtext headlines, which are internally stored as paragraphs with custom style classes.

Element From Class

Type Descriptor: !ElementFromClass

Properties:

  • mapping: A mapping from style name to element qualified name.

Example:

elementTransformer:
  !ElementFromClass
  mapping:
    *headline_1_style: h1
    *headline_2_style: h2
    *headline_3_style: h3
    *headline_4_style: h4
    *headline_5_style: h5
    *headline_6_style: h6

Attribute Transformer

An Attribute Transformer allows to add/remove/modify attributes of an element node.
Currently there is only one transformer for filtering style classes.

Pass Styles

Type Descriptor: !PassStyles

Properties:

  • styles: List of allowed styles for the class attribute.
Clone this wiki locally