Brightspot - Marked Text

Marked Text is a JSON representation of a Brightspot rich text editor (RTE) field containing all the metadata for rich-text objects. Its structure is flattened in such a way that is conducive to the GraphQL ecosystem.

This utility provides a flexible framework for iterating over a Marked Text object and transforming it in any way required, without limitations. Most commonly in the form of HTML or React components.

Installing the API

Install with npm:

npm i  @brightspot/marked-text

Install with yarn:

yarn add @brightspot/marked-text

The exported markedTextTraversal function will transform the Marked Text representation of a Brightspot RTE field into the content required for your application.

Importing the function into your application:

import { markedTextTraversal } from '@brightspot/marked-text'

Transforming Marked Text

The markedTextTraversal function is passed the following two arguments.

1. data: Marked Text JSON object (see example below).
2. visitor: Object containing two properties: visitText with a function value; visitMark with a function value.

Below is a simple usage that converts Marked Text into an HTML representation with all of the expected parent-child nesting.

const result = markedTextTraversal(data, {
  visitText: (text) => {
    return text
  },
  visitMark: (mark, children) => {
    let markup = `<${mark.data.name}>`
    children.forEach((child) => (markup += child))
    markup += `</${mark.data.name}>`
    return markup
  },
})

Your visitText function is passed a single string argument. In this simple example nothing is needed beyond returning its value right back, but if a business case required it it could be transformed here.

The visitMark function is doing the bulk of the work, creating our HTML markup in this example. This function receives two arguments, a mark object and an array.

The mark object will always contain the properties descendants, end, start and data. The data property is also an object containing the property __typename. In the example below, it is of type RteHtmlElement which also contains the properties name and attributes but these extra properties vary depending on the type of rich text element returned.

{
  "descendants": 2,
  "end": 23,
  "start": 0,
  "data": {
    "__typename": "RteHtmlElement",
    "name": "p",
    "attributes": []
  }
}

The children array is the array of children within the mark that has been processed with the visitor object. As such, the type of elements in the array vary depending on the user's implementation.

Example Input-Output

Below is taken directly from the Brightspot GraphQL Explorer output, in our example above, data of Marked Text object lies within the property richText:

{
  "data": {
    "Article": {
      "headline": "Hello, world",
      "body": {
        "__typename": "RichTextBody",
        "richText": {
          "text": "Hello, rich text world!",
          "marks": [
            {
              "descendants": 2,
              "end": 23,
              "start": 0,
              "data": {
                "__typename": "RteHtmlElement",
                "name": "p",
                "attributes": []
              }
            },
            {
              "descendants": 1,
              "end": 16,
              "start": 7,
              "data": {
                "__typename": "RteHtmlElement",
                "name": "b",
                "attributes": []
              }
            },
            {
              "descendants": 0,
              "end": 16,
              "start": 12,
              "data": {
                "__typename": "RteHtmlElement",
                "name": "u",
                "attributes": []
              }
            }
          ]
        }
      }
    }
  }
}

Produces the following HTML:

<p>Hello, <b>rich <u>text</u></b> world!</p>