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:

import { connect } from 'datocms-plugin-sdk';
connect({
  async onBeforeItemUpsert(createOrUpdateItemPayload, ctx) {
    const item = createOrUpdateItemPayload.data;
    
    // get the ID of the Article model
    const articleItemTypeId = Object.values(ctx.itemTypes).find(itemType => itemType.attributes.api_key === 'article').id;
    // fast return for any record that's not an Article
    if (item.relationships.item_type.data.id !== articleItemTypeId) {
      return;
    }
    
    // fast return if the article is not highlighted
    if (!item.attributes.highlighted) {
      return;
    }
    
    const confirmation = await ctx.openConfirm({
      title: 'Mark Article as highlighted?',
      content: 'Highlighted articles are displayed on the homepage of the site!',
      cancel: { label: 'Cancel', value: false },
      choices: [
        { label: 'Yes, save as highlighted', value: true, intent: 'negative' },
      ],
    });
    
    if (!confirmation) {
      ctx.notice('The article has not been saved, you can unflag the "highlighted" field.');
      // returning false blocks the action
      return false;
    }
  } 
});

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:

import { connect } from 'datocms-plugin-sdk';
connect({
  async onBeforeItemsPublish(items, ctx) {
    return await ctx.openConfirm({
      title: `Publish ${items.length} records?`,
      content: `This action will make the records visibile on the public website!`,
      cancel: { label: 'Cancel', value: false },
      choices: [{ label: 'Yes, publish', value: true }],
    });
  } 
});