Through plugins it is possible to enrich the functionalities of DatoCMS by adding new pages and sections to the standard interface. These pages are almost full-screen, 100% customisable, and the end-user can reach them through links/menu items that can be added to the different DatoCMS navigation menus.
For example, the Custom Page plugin lets you embed any external URL inside DatoCMS, while the Content Calendar plugin uses a custom page to explore your records inside a calendar:
A page is nothing more than an iframe, inside of which the plugin developer can render what they prefer, while also having the possibility to:
access a series of information related to the project in which the plugin is installed or the logged-in user;
make calls to DatoCMS to produce various effects and interacting with the main application (ie. navigate to other pages, trigger notifications, opening modals, etc.);
Adding a link to the custom page
The SDK provides a number of hooks for adding links to custom pages within the navigation menus of DatoCMS.
Top-bar navigation items
To add one or more tabs to the top bar of the interface, you can use the mainNavigationTabs hook:
The pageId property is crucial here, as it specifies which custom page you want to display when you click the tab. If you wish, you can also customize the insertion point of the menu item via the placement property:
{
// ...other properties
placement: ['before','content'],
}
In this case, we are asking to show the tab before the default "Content" tab.
As for the icon, you can either use one of the Awesome 5 Pro solid icons by their name, or explicitly pass a custom SVG:
if (!ctx.currentRole.attributes.can_edit_schema) {
12
return [];
13
}
14
15
return [
16
{
17
label:'My plugin',
18
items: [
19
{
20
label: labels[ctx.ui.locale],
21
icon:'cogs',
22
pointsTo:{
23
pageId:'settings',
24
},
25
},
26
],
27
},
28
];
29
},
30
});
In this example, it can be seen that it is possible to show (or not) menu items depending on the logged-in user's permissions, or to show labels translated into the user's preferred interface language.
Step 2: Rendering the page
Once you enter the page through one of the links, you can render the content of the custom pages by implementing the renderPage hook:
The strategy to adopt here is is to implement a switch that, depending on the pageId, will render a different, specialized React component.
The hook, in its second ctx argument, provides a series of information and methods for interacting with the main application. It is a good idea to pass it to the page component, in the form of a React prop.
Here's an example page component. It is important to wrap the content inside the Canvas component to give our app the look and feel of the DatoCMS web app:
1
import{ RenderPageCtx }from'datocms-plugin-sdk';
2
import{ Canvas }from'datocms-react-ui';
3
4
type PropTypes ={
5
ctx: RenderPageCtx,
6
};
7
8
functionWelcomePage({ctx}: PropTypes){
9
return (
10
<Canvasctx={ctx}>
11
Hi there!
12
</Canvas>
13
);
14
}
mainNavigationTabs(ctx)
Use this function to declare new tabs you want to add in the top-bar of the
UI.
Return value
The function must return: MainNavigationTab[].
Context object
The following properties and methods are available in the ctx argument:
Every hook available in the Plugin SDK shares the same minumum set of properties and
methods.
Information about the current user using the CMS.
The current DatoCMS user. It can either be the owner or one of the
collaborators (regular or SSO).
'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.
const uploadId =prompt('Please insert an asset ID:');
2
3
const result =await ctx.editUploadMetadata({
4
upload_id: uploadId,
5
alt:null,
6
title:null,
7
custom_data:{},
8
focal_point:null,
9
});
10
11
if (result) {
12
ctx.notice(`Success! ${JSON.stringify(result)}`);
13
}else{
14
ctx.alert('Closed!');
15
}
renderPage(pageId: string, ctx)
This function will be called when the plugin needs to render a specific
page (see the mainNavigationTabs, settingsAreaSidebarItemGroups and
contentAreaSidebarItems functions).
Context object
The following properties and methods are available in the ctx argument:
This hook exposes additional information and operations specific to the context in
which it operates.
'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.
