Sorry, no results found for "".

In this page

Rendering the panel

Implementing a custom Sidebar

Rendering the sidebar

Asset Sidebars and Sidebar Panels

Hooks

itemFormSidebars()

renderItemFormSidebar()

itemFormSidebarPanels()

renderItemFormSidebarPanel()

uploadSidebars()

renderUploadSidebar()

uploadSidebarPanels()

renderUploadSidebarPanel()

Plugin SDK > Sidebars and sidebar panels

Sidebars and sidebar panels

Through plugins it is possible to customize the standard sidebars that DatoCMS offers when editing a record or an asset in the Media Area.

Sidebars vs Sidebar Panels

The SDK offers two ways to customize the sidebar interface. You can either add new collapsible panels to the default sidebar:

Or offer complete alternative sidebars, as in the example below:

Depending on the size of the content you need to display, you can choose one or the other. Or even offer both. You can take a look at a real-world example of both sidebars and sidebar panels in the Web Previews plugin.

Inside sidebars and sidebar panels, the plugin developer can render what they prefer, while also having the possibility to:

access a series of information relating to the record that's being edited, the project in which the plugin is installed or the logged-in user;
make calls to DatoCMS to produce various effects and interact with the main application (changing form values, navigating to other pages, triggering notifications, opening modals, etc.);

Implementing a Sidebar Panel

Let's say we want to create a sidebar panel that will show a link pointing to the website page related to the record we're editing.

The first step is to implement the itemFormSidebarPanels hook, to declare our intent to add the panel to the sidebar:

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

3
connect({
4
  itemFormSidebarPanels(model: ItemType, ctx: ItemFormSidebarPanelsCtx) {
5
    return [
6
      {
7
        id: 'goToWebsite',
8
        label: 'Go to website',
9
        startOpen: true,
10
      },
11
    ];
12
  },
13
});

The code above will add a panel to every record in our project... but maybe not every record in DatoCMS has a specific page in the final website, right?

It might be better to add some settings to our plugin to let the final user declare the set of models that have permalinks, and the relative URL structure enforced on the frontend:

1
itemFormSidebarPanels(model: ItemType, ctx: ItemFormSidebarPanelsCtx) {
2
  const { permalinksByModel } = ctx.plugin.attributes.parameters;
3

4
  // Assuming we're saving user preferences in this format:
5
  // {
6
  //   'blog_post': '/blog/:slug',
7
  //   'author': '/author/:slug',
8
  //   ...
9
  // }
10
  }
11

12
  if (!permalinksByModel[model.attributes.api_key]) {
13
    // Don't add the panel!
14
    return [];
15
  }
16

17
  // Add the panel!
18
}

Rendering the panel

The final step is to actually render the panel itself by implementing the renderItemFormSidebarPanel hook.

Inside of this hook we initialize React and render a custom component called GoToWebsiteItemFormSidebarPanel, passing down as a prop the second ctx argument, which provides a series of information and methods for interacting with the main application:

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

5
connect({
6
  renderItemFormSidebarPanel(
7
    sidebarPanelId,
8
    ctx: RenderItemFormSidebarPanelCtx,
9
  ) {
10
    ReactDOM.render(
11
      <React.StrictMode>
12
        <GoToWebsiteItemFormSidebarPanel ctx={ctx} />
13
      </React.StrictMode>,
14
      document.getElementById('root'),
15
    );
16
  },
17
});

A plugin might render different panels, so we can use the sidebarPanelId argument to know which one we are requested to render, and write a specific React component for each of them.

1
import { Canvas } from 'datocms-react-ui';
2

3
type PropTypes = {
4
  ctx: RenderItemFormSidebarPanelCtx;
5
};
6

7
function GoToWebsiteItemFormSidebarPanel({ ctx }: PropTypes) {
8
  return (
9
    <Canvas ctx={ctx}>
10
      Hello from the sidebar!
11
    </Canvas>
12
  );
13
}

Always use the canvas!

It is important to wrap the content inside the Canvas component, so that the iframe will continuously auto-adjust its size based on the content we're rendering, and to give our app the look and feel of the DatoCMS web app.

All we need to do now is to actually render the link to the website, reading from ctx.formValues the slug value and generating the final frontend URL:

1
import { ButtonLink } from 'datocms-react-ui';
2

3
function GoToWebsiteItemFormSidebarPanel({ ctx }: PropTypes) {
4
  if (ctx.itemStatus === 'new') {
5
    // we're in a record that still has not been persisted
6
    return <div>Please save the record first!</div>;
7
  }
8

9
  const { permalinksByModel } = ctx.plugin.attributes.parameters;
10
  const permalinkStructure = permalinksByModel[ctx.itemType.attributes.api_key];
11
  const url = permalinkStructure.replace(':slug', ctx.formValues.slug);
12

13
  return (
14
    <Canvas ctx={ctx}>
15
      <ButtonLink href={url} fullWidth>
16
        View it on the website!
17
      </ButtonLink>
18
    </Canvas>
19
  );
20
}

Implementing a custom Sidebar

Suppose that instead of presenting a link to a webpage, we want to embed the actual web page alongside the record. To do that we need more space than what a sidebar panel can offer, so creating a completely separate sidebar is more appropriate.

Managing sidebars is very similar to what we just did with sidebar panels. The main difference is in the way you define them. To declare our intent to add the sidebar, implement the itemFormSidebars hook:

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

3
connect({
4
  itemFormSidebars(model: ItemType, ctx: ItemFormSidebarsCtx) {
5
    return [
6
      {
7
        id: "sideBySidePreview",
8
        label: "Side-by-side preview",
9
        preferredWidth: 900,
10
      },
11
    ];
12
  },
13
});

With the preferredWidth, you can control the ideal width for the sidebar when it opens. Users will then be able to resize it if they want. There is one constraint though: the sidebar width cannot exceed 60% of the screen, taking up too much screen real estate. If the preferredWidth is bigger than this value, it will be capped.

Rendering the sidebar

Now, to render the sidebar itself, we can implement the renderItemFormSidebar hook.

Just like we did with the sidebar panel, we initialize React and render a custom component, passing down as a prop the second ctx argument, which provides a series of information and methods for interacting with the main application:

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

5
connect({
6
  renderItemFormSidebar(
7
    sidebarId,
8
    ctx: RenderItemFormSidebarCtx,
9
  ) {
10
    ReactDOM.render(
11
      <React.StrictMode>
12
        <SideBySidePreviewSidebar ctx={ctx} />
13
      </React.StrictMode>,
14
      document.getElementById('root'),
15
    );
16
  },
17
});

A plugin might render different sidebars, so we can use the sidebarId argument to know which one we are requested to render, and write a specific React component for each of them.

In our <SideBySidePreviewSidebar> component, we can simply render an iframe pointing to the webpage, copying most of the logic from our previous sidebar panel:

1
import { Canvas } from 'datocms-react-ui';
2

3
type PropTypes = {
4
  ctx: RenderItemFormSidebarCtx;
5
};
6

7
function SideBySidePreviewSidebar({ ctx }: PropTypes) {
8
  const { permalinksByModel } = ctx.plugin.attributes.parameters;
9
  const permalinkStructure = permalinksByModel[ctx.itemType.attributes.api_key];
10
  const url = permalinkStructure.replace(':slug', ctx.formValues.slug);
11

12
  return (
13
    <Canvas ctx={ctx}>
14
      <iframe src={url} />
15
    </Canvas>
16
  );
17
}

Asset Sidebars and Sidebar Panels

Requires Plugin SDK v2+

The asset sidebars and sidebar panels in the following examples requires v2.x.x or higher of the DatoCMS Plugins SDK. If you're still on v1, please upgrade before proceeding.

In addition to being able to customize the sidebars of a record, it is also possible to do the same in the detail view of an asset in the Media Area:

The implementation is absolutely similar to the one just seen. The only thing that changes is the hooks to be used:

For sidebars: uploadSidebars and renderUploadSidebar
For sidebar panels: uploadSidebarPanels and renderUploadSidebarPanel

Here's an example:

1
import {
2
  connect,
3
  UploadSidebarPanelsCtx,
4
  RenderUploadSidebarPanelCtx,
5
  UploadSidebarsCtx,
6
  RenderUploadSidebarCtx
7
} from 'datocms-plugin-sdk';
8

9
connect({
10
  uploadSidebars(ctx: UploadSidebarsCtx) {
11
    return [
12
      {
13
        id: "customSidebar",
14
        label: "My Custom Sidebar",
15
        preferredWidth: 900,
16
      },
17
    ];
18
  },
19
  renderUploadSidebar(sidebarId: string, ctx: RenderUploadSidebarCtx) {
20
    render(<CustomSidebar ctx={ctx} />);
21
  },
22

23
  uploadSidebarPanels(ctx: UploadSidebarPanelsCtx) {
24
    return [
25
      {
26
        id: 'customSidebarPanel',
27
        label: 'Custom Sidebar Panel',
28
        startOpen: true,
29
      },
30
    ];
31
  },
32
  renderUploadSidebarPanel(sidebarPanelId: string, ctx: RenderUploadSidebarPanelCtx) {
33
    render(<CustomSidebarPanel ctx={ctx} />);
34
  },
35
});

`itemFormSidebars(itemType: ItemType, ctx)`

Use this function to declare new sidebar to be shown when the user edits records of a particular model.

Return value

The function must return: ItemFormSidebar[].

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).

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

Plugin SDK > Sidebars and sidebar panels

Sidebars vs Sidebar Panels

Implementing a Sidebar Panel

Rendering the panel

Implementing a custom Sidebar

Rendering the sidebar

Asset Sidebars and Sidebar Panels

itemFormSidebars(itemType: ItemType, ctx)

Return value

Context object

renderItemFormSidebar(sidebarId: string, ctx)

Context object

itemFormSidebarPanels(itemType: ItemType, ctx)

Return value

Context object

renderItemFormSidebarPanel(sidebarPaneId: string, ctx)

Context object

uploadSidebars(ctx)

Return value

Context object

renderUploadSidebar(sidebarId: string, ctx)

Context object

uploadSidebarPanels(ctx)

Return value

Context object

renderUploadSidebarPanel(sidebarPaneId: string, ctx)

Context object

`itemFormSidebars(itemType: ItemType, ctx)`

`renderItemFormSidebar(sidebarId: string, ctx)`

`itemFormSidebarPanels(itemType: ItemType, ctx)`

`renderItemFormSidebarPanel(sidebarPaneId: string, ctx)`

`uploadSidebars(ctx)`

`renderUploadSidebar(sidebarId: string, ctx)`

`uploadSidebarPanels(ctx)`

`renderUploadSidebarPanel(sidebarPaneId: string, ctx)`