JSON RTE Plugin for Contentstack App SDK

This document outlines how to build JSON Rich Text Editor (RTE) plugins using the Contentstack App SDK. These plugins extend the editor’s functionality by enabling custom formatting, embeds, and interactions within the JSON RTE.

Prerequisites

• Basic understanding of JSON RTE
• JSON structure and terminology associated with it

Structure of JSON RTE

{
  "type": "doc",
  "children": [
    {
      "type": "p",
      "children": [
        {
          "text": "Paragraph"
        }
      ]
    },
    {
      "type": "h1",
      "children": [
        {
          "text": "Heading One"
        }
      ]
    }
  ]
}

Node Types

In the JSON RTE, the JSON structure represents as a Node, which consists of two types:

• Block Node: Contains a children array with nested nodes.
• Leaf Node: Contains only a text property and optional formatting marks like bold, italic, etc.

The root of the document is a special Block Node of type doc. All editor content is nested within this root node.

Marks

Marks define text formatting in leaf nodes. Common marks include bold, italic, and underline.

Example:

{
  "text": "I am Bold",
  "bold": true
}

In the above example, bold is the mark applied to the string "I am Bold".

Render Type

A Block node can be rendered in three ways:

• Block: Rendered as a standalone block element (e.g., paragraph, heading).
• Inline: Rendered within other text flows (e.g., links).
• Void: Represents self-contained, non-editable elements (e.g., images, embeds).

Path

A Path is an array of indexes that locates a node’s exact position within the document tree.

In the JSON RTE, a path is represented as: Number[]

Examples:

• The doc node has a path of [0].
• The first paragraph inside the doc node has a path of [0, 0].

Point

A Point represents a specific location within a leaf node’s text.

It consists of:

• path: Identifies the node’s position in the document tree.
• offset: Indicates the character index within the node’s text string.

Structure:

{
  path: Path,
  offset: Number
}

Range

A Range defines a selection within a JSON document using two points:

• anchor: The starting point of the selection.
• focus: The ending point of the selection.

Structure:

{
  anchor: Point,
  focus: Point
}

Location

A Location identifies a specific position within the JSON RTE document. It can be one of the following:

• Path: Specifies a node’s position in the document tree.
• Point: Specifies a character offset within a leaf node.
• Range: Specifies a selection spanning from an anchor to a focus point.

Use a Location object as input when targeting or modifying content in the editor.

Inclusion in your project

To build a JSON RTE plugin:

1. Install the SDK

   Add the @contentstack/app-sdk package to your React project:

   npm install @contentstack/app-sdk

2. Clone the Boilerplate

   Use the JSON RTE plugin boilerplate from GitHub as a starting point. It includes the required project structure and configuration.

Classes

RTEPlugin(plugin_id, callback)

The RTEPlugin method allows you to create a JSON RTE plugin instance.

Kind: Instance property of the JSON RTE plugin

Returns: Plugin Object

configCallback: (rte: IRteParam) => IConfig

The IConfig object is a user-defined object that contains metadata that controls how the plugin behaves and appears in the editor.

The following table contains the possible properties of IConfig:

RTE Instance (rte)

The rte object provides access to essential functions and properties for interacting with the JSON RTE.

The following is a list of properties and methods of the JSON RTE instance.

Properties:

rte.ref

The rte.ref property returns the HTML reference of the JSON RTE.

rte.fieldConfig

The rte.fieldConfig() property provides metadata about the JSON RTE field, as defined in the content type builder page.

rte.getConfig: () => Object

The rte.getConfig() method retrieves the configuration object defined during plugin creation or selection.

Use this method to access custom plugin parameters, such as API keys or UI settings specified in:

• The plugin’s initialization logic.
• Field-level configuration in the builder.

RTE Methods

Access RTE methods using the rte.methodName() syntax. These methods allow you to retrieve paths, modify nodes, apply text formatting, and manage content within the editor.

RTE Selection Methods (rte.selection)

The rte.selection object provides methods and hooks to manage and query the current selection within the editor.

Node Options:

Functions that transform or modify content accept an options parameter. This parameter includes settings that control where and how the transformation is applied using the NodeOptions interface.

Available Options:

• at: Specifies the location in the editor where the transformation should occur. It defaults to the user's current selection.
• match: A custom function that filters which nodes should be affected, based on their content and path.

interface NodeOptions {
  at?: Location;
  match?: (node: Node, path: Location) => boolean;
}

Events function:

The Events functions are built-in methods available on the RTE instance and can be invoked using the syntax: rte.{event_name}().

Plugin

Plugin instances expose methods to handle editor events and organize related plugins into dropdowns.

Editor Events

Plugin.on: (event_type, callback) => void

Dropdown plugin

The Plugin.addPlugins method groups related plugins into a single dropdown menu within the RTE toolbar.

Plugin.addPlugins: (...Plugin) => void

Example:

const ChooseAsset = RTE("choose-asset", () => {
  /** Choose Asset Code */
});
const UploadAsset = RTE("upload-asset", () => {
  /** Upload Asset Code */
});
const Asset = RTE("asset-picker", () => {
  /** Asset Picker Code */
});
Asset.addPlugins(ChooseAsset, UploadAsset);

This groups the ChooseAsset and UploadAsset plugins under a dropdown button represented by Asset.