Structured Text is a consciously simple format, with a very small number of possible nodes — only the ones that are really helpful to capture the semantics of a standard piece of content, and with zero possibility to introduce styling and break the decoupling of content from presentation.
This is generally a very good thing, as it makes working on the frontend extremely simple and predictable: unlike HTML or Markdown, you don't have to be defensive and worry about some complex nesting of tags that you'd never think it could be possible, or unwanted styles coming from the editors.
There are, however, situations where it is critical to be able to add a small, controlled set of styles to your content, to represent nuances of different semantics within a piece of content.
Adding custom styles to nodes
Let's take this article as an example:
The third paragraph is conceptually similar to the others, but it's obviously more important, and we want the reader to pay more attention to what it says.
In these cases, we can use plugins to specify alternative styles for paragraph and heading nodes using the customBlockStylesForStructuredTextField hook:
The code above will add a custom "emphasized" style for paragraph nodes to every Structured Text field in the project. The appliedStyle property lets you customize how the style will be rendered inside of DatoCMS, when the user selects it:
You can also use the first argument of the hook (field) to only allow custom styles in some specific Structured Text fields. If that's the case, you'll probably want to add some settings to the plugin to let the final user decide which they are:
if (!fieldsInWhichAllowCustomStyles.includes[field.attributes.api_key)) {
5
// No custom styles!
6
return [];
7
}
8
9
return [
10
{
11
id:'emphasized',
12
node:'paragraph',
13
// ...
14
},
15
];
16
}
The final Structured Text value will have the custom style applied in the style property:
1
{
2
"type":"root",
3
"children":[
4
{
5
"type":"paragraph",
6
"style":"emphasized",
7
"children":[
8
{
9
"type":"span",
10
"value":"Hello!"
11
}
12
]
13
}
14
]
15
}
Adding custom marks
The default Structured Text editor already supports a number of different marks (strong, code, underline, highlight, etc.), but you might want to annotate parts of the text using custom marks.
An example would be adding a "spoiler" mark, to signal a portion of text that we don't want to show the visitor unless they explicitly accept a spoiler alert.
The customMarksForStructuredTextField hook lets you do exactly that:
The code above will add a custom "spoiler" mark to every Structured Text field in the project. The appliedStyle property lets you customize how the style will be rendered inside of DatoCMS, when the user selects it:
The final result on the Structured Text value will be the following:
1
{
2
"type":"root",
3
"children":[
4
{
5
"type":"paragraph",
6
"children":[
7
{
8
"type":"span",
9
"value":"In the "
10
},
11
{
12
"type":"span",
13
"marks":["spoiler"],
14
"value":"final killing scene"
15
},
16
{
17
"type":"span",
18
"value":", the director really outdid himself."
19
}
20
]
21
}
22
]
23
}
You're in charge of the frontend!
All of our Structured Text management libraries (React, Vue, etc.) allow you to specify custom rendering rules. When working with custom styles and marks, it's up to your frontend to decide how to render them!
'Lorem Ipsum is simply dummy text of the printing and typesetting industry',
5
choices: [
6
{
7
label:'Positive',
8
value:'positive',
9
intent:'positive',
10
},
11
{
12
label:'Negative',
13
value:'negative',
14
intent:'negative',
15
},
16
],
17
cancel:{
18
label:'Cancel',
19
value:false,
20
},
21
});
22
23
if (result) {
24
ctx.notice(`Success! ${result}`);
25
}else{
26
ctx.alert('Cancelled!');
27
}
These properties provide access to "entity repos", that is, the collection of
resources of a particular type that have been loaded by the CMS up to this
moment. The entity repos are objects, indexed by the ID of the entity itself.
All the models of the current DatoCMS project, indexed by ID.
All the fields currently loaded for the current DatoCMS project, indexed by
ID. If some fields you need are not present, use the loadItemTypeFields
function to load them.
All the fieldsets currently loaded for the current DatoCMS project, indexed
by ID. If some fields you need are not present, use the
loadItemTypeFieldsets function to load them.
All the regular users currently loaded for the current DatoCMS project,
indexed by ID. It will always contain the current user. If some users you
need are not present, use the loadUsers function to load them.
All the SSO users currently loaded for the current DatoCMS project, indexed
by ID. It will always contain the current user. If some users you need are
not present, use the loadSsoUsers function to load them.
These methods let you open the standard DatoCMS dialogs needed to interact
with records.
Opens a dialog for creating a new record. It returns a promise resolved
with the newly created record or null if the user closes the dialog
without creating anything.
const itemTypeId =prompt('Please insert a model ID:');
2
3
const item =await ctx.createNewItem(itemTypeId);
4
5
if (item) {
6
ctx.notice(`Success! ${item.id}`);
7
}else{
8
ctx.alert('Closed!');
9
}
Opens a dialog for selecting one (or multiple) record(s) from a list of
existing records of type itemTypeId. It returns a promise resolved with
the selected record(s), or null if the user closes the dialog without
choosing any record.
Opens a dialog for editing an existing record. It returns a promise
resolved with the edited record, or null if the user closes the dialog
without persisting any change.
These methods can be used to update both plugin parameters and manual field
extensions configuration.
Updates the plugin parameters.
Always check ctx.currentRole.meta.final_permissions.can_edit_schema
before calling this, as the user might not have the permission to perform
the operation.
Performs changes in the appearance of a field. You can install/remove a
manual field extension, or tweak their parameters. If multiple changes are
passed, they will be applied sequencially.
Always check ctx.currentRole.meta.final_permissions.can_edit_schema
before calling this, as the user might not have the permission to perform
the operation.
ctx.notice(`Successfully edited field ${field.attributes.api_key}`);
36
}
These methods let you open the standard DatoCMS dialogs needed to interact
with Media Area assets.
Opens a dialog for selecting one (or multiple) existing asset(s). It
returns a promise resolved with the selected asset(s), or null if the
user closes the dialog without selecting any upload.
const uploadId =prompt('Please insert an asset ID:');
2
3
const item =await ctx.editUpload(uploadId);
4
5
if (item) {
6
ctx.notice(`Success! ${item.id}`);
7
}else{
8
ctx.alert('Closed!');
9
}
Opens a dialog for editing a "single asset" field structure. It returns a
promise resolved with the updated structure, or null if the user closes
the dialog without persisting any change.
'Lorem Ipsum is simply dummy text of the printing and typesetting industry',
5
choices: [
6
{
7
label:'Positive',
8
value:'positive',
9
intent:'positive',
10
},
11
{
12
label:'Negative',
13
value:'negative',
14
intent:'negative',
15
},
16
],
17
cancel:{
18
label:'Cancel',
19
value:false,
20
},
21
});
22
23
if (result) {
24
ctx.notice(`Success! ${result}`);
25
}else{
26
ctx.alert('Cancelled!');
27
}
These properties provide access to "entity repos", that is, the collection of
resources of a particular type that have been loaded by the CMS up to this
moment. The entity repos are objects, indexed by the ID of the entity itself.
All the models of the current DatoCMS project, indexed by ID.
All the fields currently loaded for the current DatoCMS project, indexed by
ID. If some fields you need are not present, use the loadItemTypeFields
function to load them.
All the fieldsets currently loaded for the current DatoCMS project, indexed
by ID. If some fields you need are not present, use the
loadItemTypeFieldsets function to load them.
All the regular users currently loaded for the current DatoCMS project,
indexed by ID. It will always contain the current user. If some users you
need are not present, use the loadUsers function to load them.
All the SSO users currently loaded for the current DatoCMS project, indexed
by ID. It will always contain the current user. If some users you need are
not present, use the loadSsoUsers function to load them.
These methods let you open the standard DatoCMS dialogs needed to interact
with records.
Opens a dialog for creating a new record. It returns a promise resolved
with the newly created record or null if the user closes the dialog
without creating anything.
const itemTypeId =prompt('Please insert a model ID:');
2
3
const item =await ctx.createNewItem(itemTypeId);
4
5
if (item) {
6
ctx.notice(`Success! ${item.id}`);
7
}else{
8
ctx.alert('Closed!');
9
}
Opens a dialog for selecting one (or multiple) record(s) from a list of
existing records of type itemTypeId. It returns a promise resolved with
the selected record(s), or null if the user closes the dialog without
choosing any record.
Opens a dialog for editing an existing record. It returns a promise
resolved with the edited record, or null if the user closes the dialog
without persisting any change.
These methods can be used to update both plugin parameters and manual field
extensions configuration.
Updates the plugin parameters.
Always check ctx.currentRole.meta.final_permissions.can_edit_schema
before calling this, as the user might not have the permission to perform
the operation.
Performs changes in the appearance of a field. You can install/remove a
manual field extension, or tweak their parameters. If multiple changes are
passed, they will be applied sequencially.
Always check ctx.currentRole.meta.final_permissions.can_edit_schema
before calling this, as the user might not have the permission to perform
the operation.
ctx.notice(`Successfully edited field ${field.attributes.api_key}`);
36
}
These methods let you open the standard DatoCMS dialogs needed to interact
with Media Area assets.
Opens a dialog for selecting one (or multiple) existing asset(s). It
returns a promise resolved with the selected asset(s), or null if the
user closes the dialog without selecting any upload.
const uploadId =prompt('Please insert an asset ID:');
2
3
const item =await ctx.editUpload(uploadId);
4
5
if (item) {
6
ctx.notice(`Success! ${item.id}`);
7
}else{
8
ctx.alert('Closed!');
9
}
Opens a dialog for editing a "single asset" field structure. It returns a
promise resolved with the updated structure, or null if the user closes
the dialog without persisting any change.
