Plugin SDK

Custom pages

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:

1
import { connect, MainNavigationTabsCtx } from 'datocms-plugin-sdk';
2

3
connect({
4
  mainNavigationTabs(ctx: MainNavigationTabsCtx) {
5
    return [
6
      {
7
        label: 'Analytics',
8
        icon: 'analytics',
9
        pointsTo: {
10
          pageId: 'analytics',
11
        },
12
      },
13
    ];
14
  },
15
});

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:

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:

1
import { connect, ContentAreaSidebarItemsCtx } from 'datocms-plugin-sdk';
2

3
connect({
4
  contentAreaSidebarItems(ctx: ContentAreaSidebarItemsCtx) {
5
    return [
6
      {
7
        label: 'Welcome!',
8
        icon: 'igloo',
9
        placement: ['before', 'menuItems'],
10
        pointsTo: {
11
          pageId: 'welcome',
12
        },
13
      },
14
    ];
15
  },
16
});

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:

1
import { connect, SettingsAreaSidebarItemGroupsCtx } from 'datocms-plugin-sdk';
2

3
const labels: Record<string, string> = {
4
  "en": 'Settings',
5
  "it": 'Impostazioni',
6
  "es": 'Configuración',
7
};
8

9
connect({
10
  settingsAreaSidebarItemGroups(ctx: SettingsAreaSidebarItemGroupsCtx) {
11
    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:

1
import React from 'react';
2
import ReactDOM from 'react-dom';
3
import { connect, RenderPageCtx } from 'datocms-plugin-sdk';
4

5
function render(component: React.ReactNode) {
6
  ReactDOM.render(
7
    <React.StrictMode>{component}</React.StrictMode>,
8
    document.getElementById('root'),
9
  );
10
}
11

12
connect({
13
  renderPage(pageId, ctx: RenderPageCtx) {
14
    switch (pageId) {
15
      case 'welcome':
16
        return render(<WelcomePage ctx={ctx} />);
17
      case 'settings':
18
        return render(<SettingsPage ctx={ctx} />);
19
      case 'analytics':
20
        return render(<AnalyticsPage ctx={ctx} />);
21
    }
22
  },
23
});

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
function WelcomePage({ ctx }: PropTypes) {
9
  return (
10
    <Canvas ctx={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:

Properties and methods available in every hook

Every hook available in the Plugin SDK shares the same minumum set of properties and methods.

Authentication properties

Information about the current user using the CMS.


ctx.currentUser: User | SsoUser | Account | Organization

The current DatoCMS user. It can either be the owner or one of the collaborators (regular or SSO).

Custom pages

Adding a link to the custom page

Top-bar navigation items

Menu item in the Content navigation sidebar

Custom section in the Settings area

Step 2: Rendering the page

mainNavigationTabs(ctx)

Return value

Context object

renderPage(pageId: string, ctx)

Context object

settingsAreaSidebarItemGroups(ctx)

Return value

Context object

`mainNavigationTabs(ctx)`

`renderPage(pageId: string, ctx)`

`settingsAreaSidebarItemGroups(ctx)`