Plugin SDK

Event hooks

In addition to all the render<LOCATION> hooks, the SDK also exposes a number of hooks that can be useful to intercept specific events happening on the interface, and execute custom code, or change the way the regular interface behaves.

All these event hooks follow the same on<EVENT> naming convention.

Execute custom code when the plugin loads up

There are situations where a plugin needs to execute code as soon as the DatoCMS interface is loaded. For example, a plugin may need to contact third party systems to verify some information, or maybe notify the user in some way.

In these scenarios you can use the onBoot hook, and have the guarantee that it will be called as soon as the main DatoCMS application is loaded:

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

connect({
  async onBoot(ctx) {
    ctx.notice('Hi there!');
  }
});

Inside this hook there is no point in rendering anything, because it won't be displayed anywhere. For a concrete use case of this hook, please have a look at the chapter Releasing new plugin versions.

Intercept actions on records

Another useful group of event hooks can be used to intercept when the user wants to perform a specific action on one (or multiple) records:

onBeforeItemUpsert: called when the user wants to save a record (both creation or update);
onBeforeItemsDestroy: called when the user wants to delete one (or more) records;
onBeforeItemsPublish: called when the user wants to publish one (or more) records;
onBeforeItemsUnpublish: called when the user wants to unpublish one (or more) records;

All these hooks can return the value false to stop the relative action from happening.

In the following example we're using the onBeforeItemUpsert hook to check if the user is saving articles with the "highlighted" flag turned on, and if that's the case we show them an additional confirmation, to make sure they know what they're doing:

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

3
connect({
4
  async onBeforeItemUpsert(createOrUpdateItemPayload, ctx) {
5
    const item = createOrUpdateItemPayload.data;
6

7
    // get the ID of the Article model
8
    const articleItemTypeId = Object.values(ctx.itemTypes).find(itemType => itemType.attributes.api_key === 'article').id;
9

10
    // fast return for any record that's not an Article
11
    if (item.relationships.item_type.data.id !== articleItemTypeId) {
12
      return;
13
    }
14

15
    // fast return if the article is not highlighted
16
    if (!item.attributes.highlighted) {
17
      return;
18
    }
19

20
    const confirmation = await ctx.openConfirm({
21
      title: 'Mark Article as highlighted?',
22
      content: 'Highlighted articles are displayed on the homepage of the site!',
23
      cancel: { label: 'Cancel', value: false },
24
      choices: [
25
        { label: 'Yes, save as highlighted', value: true, intent: 'negative' },
26
      ],
27
    });
28

29
    if (!confirmation) {
30
      ctx.notice('The article has not been saved, you can unflag the "highlighted" field.');
31
      // returning false blocks the action
32
      return false;
33
    }
34
  }
35
});

We can also do something similar to confirm if the user really wants to publish a record. The onBeforeItemsPublish hook is also called when the user is selecting multiple records from the collection page, and applying a batch publish operation:

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

3
connect({
4
  async onBeforeItemsPublish(items, ctx) {
5
    return await ctx.openConfirm({
6
      title: `Publish ${items.length} records?`,
7
      content: `This action will make the records visibile on the public website!`,
8
      cancel: { label: 'Cancel', value: false },
9
      choices: [{ label: 'Yes, publish', value: true }],
10
    });
11
  }
12
});

`onBoot(ctx)`

This function will be called once at boot time and can be used to perform ie. some initial integrity checks on the configuration.

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

Event hooks

Execute custom code when the plugin loads up

Intercept actions on records

onBoot(ctx)

Context object

onBeforeItemsDestroy(items: Item[], ctx)

Return value

Context object

onBeforeItemsPublish(items: Item[], ctx)

Return value

Context object

onBeforeItemsUnpublish(items: Item[], ctx)

Return value

Context object

onBeforeItemUpsert(createOrUpdateItemPayload: ItemUpdateSchema | ItemCreateSchema, ctx)

Return value

Context object

`onBoot(ctx)`

`onBeforeItemsDestroy(items: Item[], ctx)`

`onBeforeItemsPublish(items: Item[], ctx)`

`onBeforeItemsUnpublish(items: Item[], ctx)`

`onBeforeItemUpsert(createOrUpdateItemPayload: ItemUpdateSchema | ItemCreateSchema, ctx)`