DatoCMS.StructuredText (datocms_graphql_client v0.15.2)
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
render(node, dast, options)
to_html(dast, options \\ %{})
Specs
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"
}
]
}
]
}
}
}
into this:
<p>Hi There</p>
By default, the types are transformed as follows:
type | result |
---|---|
root | the rendered children |
paragraph | <p>...</p> |
span | the node value |
heading | <hn>...</hn> where n is the level |
link | <a ...>...</a> |
block | requires custom renderer (see below) |
inlineItem | requires custom renderer (see below) |
itemLink | requires custom renderer (see below) |
Note that text styling is transformed as follows:
mark | tag |
---|---|
code | code |
emphasis | em |
highlight | mark |
strikethrough | del |
strong | strong |
underline | u |
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:
node
- the node to be rendered,dast
- the original value supplied toDatoCMS.StructuredText.to_html/2
,options
- the options supplied toDatoCMS.StructuredText.to_html/2
.
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
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
.