To add one or more tabs to the top bar of the interface, you can use the mainNavigationTabs
hook:
import { connect , IntentCtx } from 'datocms-plugin-sdk' ;
connect ( {
mainNavigationTabs ( ctx : IntentCtx ) {
return [
{
label : 'Analytics' ,
icon : 'analytics' ,
pointsTo : {
pageId : 'analytics' ,
} ,
} ,
] ;
} ,
} ) ;
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:
{
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:
icon : {
type : 'svg' ,
viewBox : '0 0 448 512' ,
content :
'<path fill="currentColor" d="M448,230.17V480H0V230.17H141.13V355.09H306.87V230.17ZM306.87,32H141.13V156.91H306.87Z" class=""></path>' ,
}
Menu item in the Content navigation sidebar Similarly, we can use the contentAreaSidebarItems
hook to add menu items to the sidebar that is displayed when we are inside the "Content" area:
import { connect , IntentCtx } from 'datocms-plugin-sdk' ;
connect ( {
contentAreaSidebarItems ( ctx : IntentCtx ) {
return [
{
label : 'Welcome!' ,
icon : 'igloo' ,
placement : [ 'before' , 'menuItems' ] ,
pointsTo : {
pageId : 'welcome' ,
} ,
} ,
] ;
} ,
} ) ;
This code will add a menu item above the default menu items present in the sidebar.
Custom section in the Settings area It is also possible to add new sections in the sidebar present in the "Settings" area with the settingsAreaSidebarItemGroups
hook:
import { connect , IntentCtx } from 'datocms-plugin-sdk' ;
const labels : Record < string , string > = {
"en" : 'Settings' ,
"it" : 'Impostazioni' ,
"es" : 'Configuración' ,
} ;
connect ( {
settingsAreaSidebarItemGroups ( ctx : IntentCtx ) {
if ( ! ctx . currentRole . attributes . can_edit_schema ) {
return [ ] ;
}
return [
{
label : 'My plugin' ,
items : [
{
label : labels [ ctx . ui . locale ] ,
icon : 'cogs' ,
pointsTo : {
pageId : 'settings' ,
} ,
} ,
] ,
} ,
] ;
} ,
} ) ;
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:
import React from 'react' ;
import ReactDOM from 'react-dom' ;
import { connect , RenderPageCtx } from 'datocms-plugin-sdk' ;
function renderPage ( component : React . ReactNode ) {
ReactDOM . render (
< React.StrictMode > { component } </ React.StrictMode > ,
document . getElementById ( 'root' ) ,
) ;
}
connect ( {
renderPage ( pageId , ctx : RenderPageCtx ) {
switch ( pageId ) {
case 'welcome' :
return render ( < WelcomePage ctx = { ctx } /> ) ;
case 'settings' :
return render ( < SettingsPage ctx = { ctx } /> ) ;
case 'analytics' :
return render ( < AnalyticsPage ctx = { ctx } /> ) ;
}
} ,
} ) ;
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:
import { RenderPageCtx } from 'datocms-plugin-sdk' ;
import { Canvas } from 'datocms-react-ui' ;
type PropTypes = {
ctx : RenderPageCtx ,
} ;
function WelcomePage ( { ctx } : PropTypes ) {
return (
< Canvas ctx = { ctx } >
Hi there !
</ Canvas >
) ;
}
mainNavigationTabs
Use this function to declare new tabs you want to add in the top-bar of the
UI.
Return value The function must return an array of objects with the following structure:
Show structureProperties available in context The following information and methods are available:
ctx.currentRole The role for the current DatoCMS user.
ctx.currentUser The current DatoCMS user. It can either be the owner or one of the
collaborators (regular or SSO).
ctx.currentUserAccessToken The access token to perform API calls on behalf of the current user. Only
available if currentUserAccessToken additional permission is granted.
ctx.environment The ID of the current environment.
ctx.itemTypes All the models of the current DatoCMS project, indexed by ID.
ctx.plugin The current plugin.
ctx.site The current DatoCMS project.
ctx.ui UI preferences of the current user (right now, only the preferred locale is
available).
settingsAreaSidebarItemGroups
Use this function to declare new navigation sections in the Settings Area
sidebar.
Return value The function must return an array of objects with the following structure:
Show structureProperties available in context The following information and methods are available:
ctx.currentRole The role for the current DatoCMS user.
ctx.currentUser The current DatoCMS user. It can either be the owner or one of the
collaborators (regular or SSO).
ctx.currentUserAccessToken The access token to perform API calls on behalf of the current user. Only
available if currentUserAccessToken additional permission is granted.
ctx.environment The ID of the current environment.
ctx.itemTypes All the models of the current DatoCMS project, indexed by ID.
ctx.plugin The current plugin.
ctx.site The current DatoCMS project.
ctx.ui UI preferences of the current user (right now, only the preferred locale is
available).
contentAreaSidebarItems
Use this function to declare new navigation items in the Content Area
sidebar.
Return value The function must return an array of objects with the following structure:
Show structureProperties available in context The following information and methods are available:
ctx.currentRole The role for the current DatoCMS user.
ctx.currentUser The current DatoCMS user. It can either be the owner or one of the
collaborators (regular or SSO).
ctx.currentUserAccessToken The access token to perform API calls on behalf of the current user. Only
available if currentUserAccessToken additional permission is granted.
ctx.environment The ID of the current environment.
ctx.itemTypes All the models of the current DatoCMS project, indexed by ID.
ctx.plugin The current plugin.
ctx.site The current DatoCMS project.
ctx.ui UI preferences of the current user (right now, only the preferred locale is
available).
renderPage
This function will be called when the plugin needs to render a specific
page (see the mainNavigationTabs
, settingsAreaSidebarItemGroups
and
contentAreaSidebarItems
functions).
Properties available in context The following information and methods are available:
ctx.account The account that is the project owner.
ctx.currentRole The role for the current DatoCMS user.
ctx.currentUser The current DatoCMS user. It can either be the owner or one of the
collaborators (regular or SSO).
ctx.currentUserAccessToken The access token to perform API calls on behalf of the current user. Only
available if currentUserAccessToken additional permission is granted.
ctx.environment The ID of the current environment.
ctx.fields All the fields currently loaded for the current DatoCMS project, indexed by
ID. It will always contain the current model fields and all the fields of
the blocks it might contain via Modular Content/Structured Text fields. If
some fields you need are not present, use the loadItemTypeFields function
to load them.
ctx.fieldsets All the fieldsets currently loaded for the current DatoCMS project, indexed
by ID. It will always contain the current model fields and all the fields
of the blocks it might contain via Modular Content/Structured Text fields.
If some fields you need are not present, use the loadItemTypeFieldsets
function to load them.
ctx.itemTypes All the models of the current DatoCMS project, indexed by ID.
ctx.owner The account that is the project owner.
ctx.pageId The ID of the page that needs to be rendered.
ctx.plugin The current plugin.
ctx.site The current DatoCMS project.
ctx.ssoUsers 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.
ctx.theme An object containing the theme colors for the current DatoCMS project.
ctx.ui UI preferences of the current user (right now, only the preferred locale is
available).
ctx.users 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.
Methods available in context The following information and methods are available:
ctx.alert() Triggers an "error" toast displaying the selected message.
ctx.createNewItem() 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.
ctx.customToast() Triggers a custom toast displaying the selected message (and optionally a
CTA).
ctx.editItem() 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.
ctx.editUpload() Opens a dialog for editing a Media Area asset. It returns a promise
resolved with:
The updated asset, if the user persists some changes to the asset itself
null, if the user closes the dialog without persisting any change
An asset structure with an additional deleted property set to true, if
the user deletes the asset.
ctx.editUploadMetadata() 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.
ctx.loadFieldsUsingPlugin() Loads all the fields in the project that are currently using the plugin for
one of its manual field extensions.
ctx.loadItemTypeFields() Loads all the fields for a specific model (or block). Fields will be
returned and will also be available in the the fields property.
ctx.loadItemTypeFieldsets() Loads all the fieldsets for a specific model (or block). Fieldsets will be
returned and will also be available in the the fieldsets property.
ctx.loadSsoUsers() Loads all SSO users. Users will be returned and will also be available in
the the ssoUsers property.
ctx.loadUsers() Loads all regular users. Users will be returned and will also be available
in the the users property.
ctx.navigateTo() Moves the user to another URL internal to the backend.
ctx.notice() Triggers a "success" toast displaying the selected message.
ctx.openConfirm() Opens a UI-consistent confirmation dialog. Returns a promise resolved with
the value of the choice made by the user.
ctx.openModal() Opens a custom modal. Returns a promise resolved with what the modal itself
returns calling the resolve() function.
ctx.selectItem() 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.
ctx.selectUpload() 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.
ctx.updateFieldAppearance() 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.finalpermissions.canedit_schema
before calling this, as the user might not have the permission to perform
the operation.
ctx.updatePluginParameters() Updates the plugin parameters.
Always check ctx.currentRole.meta.finalpermissions.canedit_schema
before calling this, as the user might not have the permission to perform
the operation.