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:

import { connect, MainNavigationTabsCtx } from 'datocms-plugin-sdk';
connect({
  mainNavigationTabs(ctx: MainNavigationTabsCtx) {
    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:

{
  // ...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:

import { connect, ContentAreaSidebarItemsCtx } from 'datocms-plugin-sdk';
connect({
  contentAreaSidebarItems(ctx: ContentAreaSidebarItemsCtx) {
    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, SettingsAreaSidebarItemGroupsCtx } from 'datocms-plugin-sdk';
const labels: Record<string, string> = {
  "en": 'Settings',
  "it": 'Impostazioni',
  "es": 'Configuración',
};
connect({
  settingsAreaSidebarItemGroups(ctx: SettingsAreaSidebarItemGroupsCtx) {
    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 render(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>
  );
}

Function Reference