Plugin SDK > Outlets

Outlets

Through plugins, it's possible to customize various areas of the DatoCMS interface. We call these customizable areas "outlets".

Outlets are essentially iframes where plugin developers can render custom content, providing enhanced functionality and user experiences within the DatoCMS ecosystem.

Outlets offer the ability to:

Access information related to records, projects, or logged-in users
Make calls to DatoCMS to produce various effects and interact with the main application (e.g., changing values, navigating, triggering notifications, opening modals)
Customize the user interface to fit specific workflow needs

If you prefer, a form outlet can also be completely hidden from the interface (setting his height to zero), and work under the cover to tweak the default behaviour of DatoCMS.

Types of Outlets

DatoCMS allows you to configure outlets in various areas of the interface.

Record Form Outlets

Record form outlets allow you to add custom areas above the record editing form:

Implementing a Record Form Outlet

The first step is to implement the itemFormOutlets hook, to declare our intent to add the outlet to the form:

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

3
connect({
4
  itemFormOutlets(model, ctx: ItemFormOutletsCtx) {
5
    return [
6
      {
7
        id: 'myOutlet',
8
        initialHeight: 100,
9
      },
10
    ];
11
  },
12
});

The initialHeight property sets the initial height of the frame, while the plugin itself is loading. It can also be useful to completely hide the outlet, by passing the value zero to it.

The code above will add the outlet to the form of every record in our project, but you can also add some settings to the plugin to ie. let the final user pick only some specific models:

itemFormOutlets(model, ctx: ItemFormOutletsCtx) {
  const { modelApiKeys } = ctx.plugin.attributes.parameters;

  if (!modelApiKeys.includes(model.attributes.api_key)) {
    // Don't add the outlet!
    return [];
  }

  // Add the outlet!
}

The final step is to actually render the outlet itself by implementing the renderItemFormOutlet hook.

Inside of this hook we can 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, RenderItemFormOutletCtx, ItemFormOutletsCtx } from 'datocms-plugin-sdk';
4

5
connect({
6
  itemFormOutlets(model, ctx: ItemFormOutletsCtx) { ... },
7
  renderItemFormOutlet(
8
    outletId,
9
    ctx: RenderItemFormOutletCtx,
10
  ) {
11
    ReactDOM.render(
12
      <React.StrictMode>
13
        <MyCustomOutlet ctx={ctx} />
14
      </React.StrictMode>,
15
      document.getElementById('root'),
16
    );
17
  },
18
});

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

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

function MyCustomOutlet({ ctx }) {
  return (
    <Canvas ctx={ctx}>
      Hello from the record form outlet!
    </Canvas>
  );
}

Always use the canvas!

If you want to render something inside the outlet, 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.

If you want the outlet to be hidden from the interface, just return null and set an initialHeight: 0 in the itemFormOutlets hook.

Record Collection Outlets

Record collection outlets allow you to add custom areas to the page that displays a collection of records for a specific model.

The implementation is exactly the same as the one we just saw for the Record Form Outlets. The only thing that changes is the hooks to be used:

To declare the intention to offer Record Collection Outlets, use itemCollectionOutlets;
To actually render the outlets, use renderItemCollectionOutlet.

Here's a full example:

1
import React from 'react';
2
import ReactDOM from 'react-dom';
3
import { connect, ItemCollectionOutletsCtx, RenderItemCollectionOutletCtx } from 'datocms-plugin-sdk';
4
import { Canvas, Button } from 'datocms-react-ui';
5

6
connect({
7
  itemCollectionOutlets(model, ctx: ItemCollectionOutletsCtx) {
8
    // Optional: Add conditions to show the outlet only for specific models
9
    const { modelApiKeys } = ctx.plugin.attributes.parameters;
10
    if (!modelApiKeys.includes(model.attributes.api_key)) {
11
      return [];
12
    }
13

14
    return [
15
      {
16
        id: 'myCollectionOutlet',
17
        initialHeight: 100,
18
      },
19
    ];
20
  },
21
  renderItemCollectionOutlet(outletId, ctx: RenderItemCollectionOutletCtx) {
22
    render(<MyCustomCollectionOutlet ctx={ctx} />);
23
  },
24
});
25

26
function MyCustomCollectionOutlet({ ctx }) {
27
  return (
28
    <Canvas ctx={ctx}>
29
      <h3>Custom Collection Outlet</h3>
30
      <p>This outlet appears above the record listing for {ctx.itemType.attributes.name}.</p>
31
    </Canvas>
32
  );
33
}

`itemCollectionOutlets(itemType: ItemType, ctx)`

Use this function to declare custom outlets to be shown at the top of a collection of records of a particular model.

Return value

The function must return: ItemCollectionOutlet[].

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

Plugin SDK > Outlets

Types of Outlets

Record Form Outlets

Implementing a Record Form Outlet

Record Collection Outlets

itemCollectionOutlets(itemType: ItemType, ctx)

Return value

Context object

renderItemCollectionOutlet(itemCollectionOutletId: string, ctx)

Context object

itemFormOutlets(itemType: ItemType, ctx)

Return value

Context object

renderItemFormOutlet(itemFormOutletId: string, ctx)

Context object

`itemCollectionOutlets(itemType: ItemType, ctx)`

`renderItemCollectionOutlet(itemCollectionOutletId: string, ctx)`

`itemFormOutlets(itemType: ItemType, ctx)`

`renderItemFormOutlet(itemFormOutletId: string, ctx)`