DatoCMS.StructuredText (datocms_graphql_client v0.17.0)

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 \\ %{})

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

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

options

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"
            }
          ]
        }
      ]
    }
  }
}

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

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:

Renderers can either return a String or a List of Strings. In the latter case, the Strings are joined together in the return value of to_html/2.

required-renderers

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.