JSON Rich Text Editor

The JSON Rich Text Editor (RTE) field is a block-style rich text editor that enables users to add different types of content. It stores content in structured JSON blocks that can contain text, images, videos, etc.

Note: The JSON Rich Text Editor field is available only in the new Contentstack interface.

When you add a JSON RTE field in a content type, it displays a text area with editing and formatting options on the entry page. This field allows you to edit and format content entered in the field without using HTML tags.

Note: The JSON RTE field does not provide an HTML code view option, freeing content managers from the hassles of handling HTML source code.

With JSON RTE, you can efficiently structure your content using the formatting options such as bold, italics, subscript, superscript, headings, paragraphs, ordered or unordered lists, tables, links, and images.

JSON_RTE_Operations_GIF.gif

Customized JSON Rich Text Editor

Apart from choosing between the Basic and Advanced editors, developers can also choose the Custom editor, while adding the JSON RTE field to content types.

The Custom editor allows you to choose from the various formatting options, and control what will be available in the JSON RTE toolbar for content managers.

Note: Only the stack owner, admins, and users assigned “Developer” roles have the right to customize the RTE field.

To customize the JSON RTE field, log in to your Contentstack account, and perform the following steps:

  1. In the Content Type Builder page, add the JSON Rich Text Editor (RTE) field to it.
  2. In the Edit Properties section of the JSON RTE field, click on Advanced.
  3. Under the Editor Type, select Custom, and choose the formatting options you want to include in the JSON RTE field. To select all the formatting options, check the Select All box.
  4. After adding and configuring the fields, click on either Save or Save and Close button to save your content type.

Custom_JSON_RTE_GIF.gif

Now, when the content managers edit or create an entry of this content type, they will see the JSON RTE with the formatting/inserting options that you selected in the above step.

Additional Resource: You can read more about Field Visibility Rules in our documentation where we have covered it extensively.

Embed Entries or Assets within JSON Rich Text Editor

Contentstack allows you to embed entries and assets within the JSON Rich Text Editor field. Embedded entries and assets are automatically updated within the Rich Text Editor field whenever the source entry or asset is updated.

The JSON RTE field lets you embed entries inline within the flow of text, as a separate content block, or as a dynamic hyperlink.

Here are some real-world scenarios where we use embedded entries:

  • Embed entry inline: To pass in some value from a linked entry that might be dynamic, such as a working title or a link that opens a modal popup
  • Embed entry as block: To add descriptive image carousels, survey forms, or product listings
  • Embed entry as hyperlink: To add a hyperlink in the RTE that changes dynamically whenever any updates are made

In the case of assets, they can be embedded in the JSON Rich Text Editor in two ways, either as a displayable component or as a downloadable file.

Here are some real-world scenarios where we use embedded assets:

  • Displayable embedded images: Such assets are dynamically updated in the frontend whenever you make any changes to the source item in the asset manager
  • Downloadable Images or Files: Such items are usually PDFs or other reference file formats that come with a handy download link

Note: The option to embed entries and assets within rich text content is available only for Advanced and Custom Rich Text Editor fields. The Basic type of Rich Text Editor does not have this option.

Embed Entries in the JSON RTE

In the Advanced and Custom editor type, you need to enable the Embed Objects option and select the content type from which you wish to embed entries within your JSON Rich Text Editor.

To use the embed feature to add entries in your JSON Rich Text Editor, log in to your Contentstack account and perform the following steps:

  1. Go to the content type where you have enabled the Embed feature.
  2. In the JSON RTE field, click on the Embed Entry icon.
  3. In the modal that opens up, select the content type from the drop-down from where you want to add the entry.
  4. From the list of entries that appears, select the entry that you want to embed within the JSON RTE.
  5. Under Select embed type, you can select one of the following options:
    1. Embed as a block: On selecting this option, the embedded entry will appear as a block. You will be able to enter text above or below this block.
    2. Embed as part of text: On selecting this option, the embedded entry will appear as part of the inline text. You will be able to enter your text before or after the embedded entry

    Jrte_Embed_Entry.jpg
  6. Click the ✓ Embed Selected Entry button to add the entry within the RTE.

Note: You can only embed a maximum of 100 entries at any given time.

Embed Assets in the JSON RTE

Assets by default are embedded when added within the JSON RTE field.

Note: For “Custom” type editor, you need to select the Asset option to embed assets.

To use the embed feature to add assets in your Rich Text Editor, log in to your Contentstack account and perform the following steps:

  1. Go to the content type where you have the Asset option in your JSON RTE field.
  2. In the RTE field, click on the Asset icon and either select Choose from assets or Upload new assets.
  3. In the modal that opens up, you can search for a specific asset or select from the displayed list as shown below:
    Jrte_Embed_Asset.jpg
  4. Click the ✓ Embed Selected Asset button to add the asset within the RTE.

Limitations of Embedded Entries and Assets

  • A maximum of 100 entries can be embedded in a JSON RTE field.
  • By default, a maximum of 15 content types can be selected for a JSON RTE as a reference.
  • Assets are by default embedded within a JSON RTE field.
  • Any references within the embedded entry will not be resolved.

JSON RTE for Content Managers

  • The JSON RTE does not have the HTML code view functionality, thus freeing content managers of the tedious task of handling HTML source code to style their rich text content. They can instead concentrate on styling their rich text through the advanced formatting options available in the editor.
  • All other formatting options are available through the menu options at the top of the field.
  • Each element, such as paragraphs, images, lists, etc., is treated as a separate block, so editors can simply drag and drop them within the body text instead of cutting and pasting content.
  • The output data for JSON RTE is in JSON format by default but, when configured, can also provide output in HTML.

Schema of JSON RTE

In the JSON RTE, each paragraph is a block; each block is an array; each array has multiple spans of text objects, storing different nodes of text. It returns clean data, making it easier to process in the backend.

The JSON RTE is composed of Blocks that contain text within them. The schema and example for a block within the RTE is as follows:

Schema:

{
    uid: { type: String, required: true },
    type: { type: String, required: true },
    attrs: { type: Object },
    children: { type: Array[id(Block), Text] }
}

Example:

{
    "type": "h1",
    "uid": "3ddd280397cf44bcb8f",
    "attrs": {},
    "children": [
      {
        "text": "Hello World!",
        "bold": true
      },
      {
        "uid": "blta5aa9ca151e65333"
      },
      {
        "text": "Welcome",
        "bold": true
      }
    ]
}

Properties of Blocks within a JSON RTE:

  • uid: Each block can be uniquely identified by a UID.
  • type: Lets the editor know how a block can be rendered.
  • attrs: Contains all the attributes and metadata the current block requires. It also includes all the formatting options and other properties like href for links.

    Note: When you update an existing JSON RTE, you need to pass the dirty attribute for each content block. Set the attribute to true.

  • children: Contains an array of IDs of other components present inside the block, e.g., embedded items, and the text present inside the block.

Additional Resource: You can read more about the schema of the JSON RTE in our documentation where we have covered it extensively.

HTML RTE vs JSON RTE

JSON RTE stores content in plain text format, which can be understood and processed by all programming languages. Whereas the HTML RTE is limited and constrained to HTML markup.

JSON-formatted content helps developers render content to any front-end framework with immense flexibility and interoperability.

HTML code in source code viewer:

<p>This RTE is amazing.</p>

JSON RTE response code:

{
  "entry":{
    "title":"Entry 1",
    "json_rte":{
      "type":"doc",
      "attrs":{
        
      },
      "uid":"a52aa19f3af54a61a32f1724831dc084",
      "children":[
        {
          "type":"p",
          "attrs":{
            
          },
          "uid":"c0a9f4affcef4409b3d23857d35f863b",
          "children":[
            {
              "text":"This RTE is "
            },
            {
              "text":"amazing",
              "bold":true
            },
            {
              "text":"."
            }
          ]
        }
      ],
      "_version":2
    },
    "tags":[
      "json_rte"
    ],
    "locale":"en-us",
    "uid":"bltc4d873bf4fd6f624",
    "created_by":"blt7b815b05d2fe5dd8",
    "updated_by":"blt7b815b05d2fe5dd8",
    "created_at":"2021-07-15T09:51:40.418Z",
    "updated_at":"2021-07-15T09:52:54.900Z",
    "ACL":{
      
    },
    "_version":2,
    "_in_progress":false
  }
}

With the JSON-based editor, the developers can handle the HTML component, and content managers can undividedly focus on styling and generating high-quality content.

Hence, you will notice one significant difference between HTML and JSON RTE, the absence of the HTML source code viewer.

Difference_between_HTML_and_JSON_RTE.jpg

Migrate Content from HTML RTE to JSON RTE

There are certainly a ton of benefits of moving your content to the new JSON RTE. Contentstack allows you to migrate your rich text content from your existing HTML-based RTE fields to the new JSON RTE fields for all entries of a content type in just a few minutes. To get started with our CLI, you first need to install it and authenticate yourself in the CLI session.

Additional Resource: Refer to our migration guide to perform the steps, understand the different flags you can use, and migrate the content safely without any data loss.

Serialization

Serializing JSON RTE means to convert the JSON response to HTML response. Given below is an example that shows how to convert value of json_rte to html_rte:

import Component from 'my-project'
import { jsonToHtml } from "@contentstack/json-rte-serializer"
function App() {
    const htmlValue = jsonToHtml({ JSON Value})
    return 
}

Deserialization

Deserializing JSON RTE means to convert the HTML response to JSON response. Given below is an example that shows how to convert value of html_rte to json_rte:

import Component from 'my-project'
import { htmlToJson } from "@contentstack/json-rte-serializer"
function App() {
    const htmlDomBody = new DOMParser().parseFromString("<p>This is Html Value</p>", 'text/html').body
    const jsonValue = htmlToJson(htmlDomBody)
    return 
}

Note: For detailed information please refer to our JSON RTE Serializer Readme file.

Benefits of JSON RTE for Developers

  • It offers users the flexibility to parse the data the way they want.
  • Data in JSON format can be used any way you want, on any frontend of your choice: HTML for web browsers, render natively for mobile apps, audio versions for voice assistants, and so on.
  • JSON RTE is more suitable for evolving projects requiring moving to a new presentation layer or redesigning the app.
  • JSON-formatted content is maintained as plain text files. These plain text formats can be read and understood by any frontend framework to which your CMS renders rich text content. E.g., both mobile and web-based clients can recognize JSON-formatted content with ease.
  • JSON RTE offers extensions that can harvest JSON data to efficiently modify the RTE content as per your needs.
  • With an interoperable JSON data format, developers are not confined to a specific method of data presentation.
  • Developers can seamlessly add advanced features such as embedded content, experience extensions, etc., to the rich text editor and create interactive content.
  • It maintains rich text within several individual JSON blocks. This separation of content structure within the editor makes it easier for developers to pick and choose what should be displayed on the front end.

API Reference for JSON RTE

To add or update a JSON RTE within your stack via API request, refer to the following API requests in our CMA API documentation:

You can retrieve detailed information for the JSON RTE field through GraphQL as well. Please refer to the Get JSON RTE Fields while Retrieving Entries query in GraphQL API documentation.

Keyboard shortcuts for JSON RTE

Windows

Mac

Bold

CTRL + B

⌘ + B

Italic

CTRL + I

⌘ + I

Underline

CTRL + U

⌘ + U

Strikethrough

CTRL + -

⌘ + -

Inline code

CTRL + SHIFT + K

⌘ + ⇧ + K

Superscript

CTRL + SHIFT + ^

⌘ + ⇧ + ^

Subscript

CTRL + SHIFT + ~

⌘ + ⇧ + ~

Normal (Paragraph)

CTRL + Alt + 0

⌘ + Option + 0

Heading 1

CTRL + Alt + 1

⌘ + Option + 1

Heading 2

CTRL + Alt + 2

⌘ + Option + 2

Heading 3

CTRL + Alt + 3

⌘ + Option + 3

Heading 4

CTRL + Alt + 4

⌘ + Option + 4

Heading 5

CTRL + Alt + 5

⌘ + Option + 5

Heading 6

CTRL + Alt + 6

⌘ + Option + 6

Block Quotes

CTRL + Alt + 7

⌘ + Option + 7

Code Block

CTRL + Alt + 8

⌘ + Option + 8

Left

CTRL + Alt + L

⌘ + ^ + L

Center

CTRL + Alt + E

⌘ + ^ + E

Right

CTRL + Alt + R

⌘ + ^ + R

Justify

CTRL + Alt + J

⌘ + ^ + J

Ordered List

CTRL + SHIFT + 7

⌘ + ⇧ + 7

Unordered List

CTRL + SHIFT + 8

⌘ + ⇧ + 8

Insert Table

CTRL + ALT + SHIFT + T

⌘ + Option + ⇧ + T

Insert Row Above

CTRL + SHIFT + ↑

⌃ + Option + ↑

Insert Row Below

CTRL + SHIFT + ↓

⌃ + Option + ↓

Insert Column Left

CTRL + SHIFT + ←

⌃ + Option + ←

Insert Column Right

CTRL + SHIFT + →

⌃ + Option + →

Divider

CTRL + H

⌘ + H

Properties

CTRL + SHIFT + P

⌘ + ⇧ + P

Undo

CTRL + z

⌘ + z

Redo

CTRL + SHIFT + z

⌘ + ⇧ + Z

Limitations for JSON RTE

  • The JSON Rich Text Editor field is available only in the new Contentstack interface.
  • A maximum of 100 entries can be embedded within the JSON RTE.
  • A maximum of 15 content types can be selected as reference for a single JSON RTE.
  • The maximum number of instances allowed for JSON RTEs marked as "Multiple" is 100.
  • During migration, both the HTML-based and JSON RTEs should be at the same level of field depth to migrate content successfully.
  • If the JSON RTE is marked as "Multiple" and HTML RTE is of "Single" type, then you won't be able to migrate content.
  • During migration, the HTML RTE and JSON RTE should allow embedded entries from the same set of referenced content types. If the referenced content types differ, you cannot migrate content between the RTEs.

Tutorial Video

Let's learn how to work with the JSON Rich Text Editor.

FAQs

  1. Can I migrate content from existing HTML-based RTE to the new JSON RTE?
    Yes, you can migrate content from existing HTML-based RTE to the new JSON RTE using CLI. Please refer to our migration guide for more details.
  2. Can I migrate content from HTML-based RTE to JSON RTE in bulk?
    Yes, Contentstack allows you to migrate your rich text content from your existing HTML-based RTE fields to the new JSON RTE fields for all entries of a content type in just a few minutes. Please refer to our migration guide for more details.
  3. How can I add class HTML tags in the new JSON RTE?
    You can use the Properties option in More options to add tags in the JSON RTE.
    Jrte_Class_Properties.jpg
  4. Can I get a HTML response for my JSON RTE?
    Yes, you can add the include_html parameter while fetching an entry to get a HTML response. Please refer to the following API requests in our CMA API documentation:

Was this article helpful?

Thanks for your feedbackSmile-icon

On This Page

^