DatoCMS.StructuredText (datocms_graphql_client v0.15.1)

Utilities for rendering DatoCMS StructuredText data.

Link to this section Summary

Functions

Transforms the data from a Structured Text field in a DatoCMS GraphQL response into HTML.

Link to this section Functions

Link to this function

render(node, dast, options)

Link to this function

to_html(dast, options \\ %{})

Specs

to_html(map(), map() | nil) :: String.t()

Transforms the data from a Structured Text field in a DatoCMS GraphQL response into HTML.

Options

  • :renderers - Custom HTML renderers (see below),
  • :data - Any data that you want to be passed in to your custom renderers.

The rendering system is recursive, calling back into render/3 as it iterates over child nodes.

The default rendering turns this:

%{
  value: %{
    schema: "dast",
    document: %{
      type: "root",
      children: [
        %{
          type: "paragraph",
          children: [
            {
              type: "span",
              value: "Hi There"
            }
          ]
        }
      ]
    }
  }
}
DatoCMS.StructuredText.to_html(structured_text)

into this:

<p>Hi There</p>

By default, the types are transformed as follows:

typeresult
rootthe rendered children
paragraph<p>...</p>
spanthe node value
heading<hn>...</hn> where n is the level
link<a ...>...</a>
blockrequires custom renderer (see below)
inlineItemrequires custom renderer (see below)
itemLinkrequires custom renderer (see below)

Note that text styling is transformed as follows:

marktag
codecode
emphasisem
highlightmark
strikethroughdel
strongstrong
underlineu

Optional Custom Renderers

All of the standard render methods can be overriden.

This is achieved by passing custom renderers in the second options parameter:

import DatoCMS.StructuredText, only: [to_html: 2, render: 3]

def custom_paragraph(node, dast, options) do
  ["<section>"] ++
    Enum.map(node.children, &(render(&1, dast, options))) ++
    ["</section>"]
end

options = %{
  renderers: %{
    render_paragraph: &custom_paragraph/3 # <-- Pass the custom renderer
  }
}

result = to_html(structured_text, options)

In this example, all paragraphs will be renderered using the custom function provided.

The custom renderers that can be used in this way are the following:

  • render_blockquote/3,
  • render_bulleted_list/3,
  • render_code/3,
  • render_emphasis/3,
  • render_heading/3,
  • render_highlight/3,
  • render_link/3,
  • render_numbered_list/3,
  • render_paragraph/3,
  • render_span/3.
  • render_strikethrough/3,
  • render_strong/3,
  • render_underline/3.

Custom renderers receive 3 parameters:

Required Renderers

If your structured text includes blocks, inline items or item links, you'll need to supply a custom renderer as it doesn't make sense to have a default renerer isn these cases.

  • render_block/3 for blocks,
  • render_inline_record/3 for inline items,
  • render_link_to_record/4 for item links.

Note: all custom renderers must accept 3 parameters, except render_link_to_record which receives both the node that is linked and the item that is linked to, plus the dast and options.