Plugin SDK

Asset sources

By default, to add new assets to the Media Area through the interface, you can upload files from your computer. But plugins can define custom asset sources to allow contributors to upload assets from external providers.

For example, the Unsplash plugin in our Marketplace allows to upload royalty-free high-resolution images:

Define custom asset sources

Within a plugin you can define the assetSources hook to expose new asset sources. Every source must specify an internal ID, and a name and a representative icon that will be shown in the interface.

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

3
connect({
4
  assetSources() {
5
    return [
6
      {
7
        id: 'unsplash',
8
        name: 'Unsplash',
9
        icon: {
10
          type: 'svg',
11
          viewBox: '0 0 448 512',
12
          content:
13
            '<path fill="currentColor" d="M448,230.17V480H0V230.17H141.13V355.09H306.87V230.17ZM306.87,32H141.13V156.91H306.87Z" class=""></path>',
14
        },
15
        modal: {
16
          width: 'm',
17
        },
18
      },
19
    ];
20
  },
21
});

Rendering the custom asset source

When the user selects the custom source, a modal will be opened with the size you specified, and the renderAssetSource hook will be called. Inside of this hook we initialize React and render a custom component called AssetBrowser, passing down as a prop the second ctx argument, which provides a series of information and methods for interacting with the main application:

import { connect } from 'datocms-plugin-sdk';

connect({
  assetSources() {
    return [{...}];
  },
  renderAssetSource(sourceId: string, ctx: RenderAssetSourceCtx) {
    render(<AssetBrowser ctx={ctx} />);
  },
});

As we just saw, a plugin might offer different asset sources, so we can use the sourceId argument to know which one we are requested to render, and write a specific React component for each of them.

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

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

7
function AssetBrowser({ 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.

We can use this component to render whatever we want. The important thing is to call the ctx.select method to communicate to the main DatoCMS app the selected asset URL:

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

3
function AssetBrowser({ ctx }: PropTypes) {
4
  const handleSelect = () => {
5
    ctx.select({
6
      resource: {
7
        url: 'https://unsplash.com/photos/yf8qPXQFDJE',
8
        filename: `sky.jpg`,
9
      },
10
    });
11
  }
12

13
  return (
14
    <Canvas ctx={ctx}>
15
      <Button onClick={handleSelect}>Select</Button>
16
    </Canvas>
17
  );
18
}

If you're generating your asset on the fly (ie. by rendering on a canvas), instead of a regular URL you can also pass a base64-encoded data URI:

ctx.select({
  resource: {
    base64: 'data:image/png;base64,PD94bWwgd..',
    filename: `generated-image.png`,
  },
});

You can also optionally specify some metadata to associate with the newly created upload:

1
ctx.select({
2
  resource: {
3
    url:
4
      'https://images.unsplash.com/photo-1416339306562-f3d12fefd36f',
5
    filename: 'man-drinking-coffee.jpg',
6
  },
7
  copyright: 'Royalty free (Unsplash)',
8
  author: 'Jeff Sheldon',
9
  notes: 'A man drinking a coffee',
10
  tags: ['man', 'coffee'],
11
});

`assetSources(ctx)`

Use this function to declare additional sources to be shown when users want to upload new assets.

Return value

The function must return: AssetSource[] | undefined.

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

Asset sources

Define custom asset sources

Rendering the custom asset source

assetSources(ctx)

Return value

Context object

renderAssetSource(assetSourceId: string, ctx)

Context object

`assetSources(ctx)`

`renderAssetSource(assetSourceId: string, ctx)`