Dropdown actions

`executeFieldDropdownAction(actionId: string, ctx)`

Use this function to execute a particular dropdown action defined via the fieldDropdownActions() hook.

Return value

The function must return: Promise<void>.

Context object

The following properties and methods are available in the ctx argument:

This hook exposes additional information and operations specific to the context in which it operates.

These information describe the current state of the field where this plugin is applied to.

Whether the field is currently disabled or not.

View on Github

The path in the formValues object where to find the current value for the field.

View on Github

The field where the field extension is installed to.

View on Github

If the field extension is installed in a field of a block, returns the top level Modular Content/Structured Text field containing the block itself.

View on Github

If the field extension is installed in a field of a block, returns the ID of the block — or undefined if the block is still not persisted — and the block model.

View on Github

These methods can be used to interact with the form that's being shown to the end-user to edit a record.

Hides/shows a specific field in the form. Please be aware that when a field is hidden, the field editor for that field will be removed from the DOM itself, including any associated plugins. When it is shown again, its plugins will be reinitialized.

View on Github

1
const fieldPath = prompt(
2
  'Please insert the path of a field in the form',
3
  ctx.fieldPath,
4
);
5

6
await ctx.toggleField(fieldPath, true);

Disables/re-enables a specific field in the form.

View on Github

1
const fieldPath = prompt(
2
  'Please insert the path of a field in the form',
3
  ctx.fieldPath,
4
);
5

6
await ctx.disableField(fieldPath, true);

Smoothly navigates to a specific field in the form. If the field is localized it will switch language tab and then navigate to the chosen field.

View on Github

1
const fieldPath = prompt(
2
  'Please insert the path of a field in the form',
3
  ctx.fieldPath,
4
);
5

6
await ctx.scrollToField(fieldPath);

Changes a specific path of the formValues object.

View on Github

1
const fieldPath = prompt(
2
  'Please insert the path of a field in the form',
3
  ctx.fieldPath,
4
);
5

6
await ctx.setFieldValue(fieldPath, 'new value');

Takes the internal form state, and transforms it into an Item entity compatible with DatoCMS API.

When skipUnchangedFields, only the fields that changed value will be serialized.

If the required nested blocks are still not loaded, this method will return undefined.

View on Github

1
await ctx.formValuesToItem(ctx.formValues, false);

Takes an Item entity, and converts it into the internal form state.

View on Github

1
await ctx.itemToFormValues(ctx.item);

Triggers a submit form for current record.

View on Github

1
await ctx.saveCurrentItem();

These information describe the current state of the form that's being shown to the end-user to edit a record.

The currently active locale for the record.

View on Github

If an already persisted record is being edited, returns the full record entity.

View on Github

The model for the record being edited.

View on Github

The complete internal form state.

View on Github

The current status of the record being edited.

View on Github

Whether the form is currently submitting itself or not.

View on Github

Whether the form has some non-persisted changes or not.

View on Github

Provides information on how many blocks are currently present in the form.

View on Github

Every hook available in the Plugin SDK shares the same minumum set of properties and methods.

Information about the current user using the CMS.

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

View on Github

The role for the current DatoCMS user.

View on Github

The access token to perform API calls on behalf of the current user. Only available if currentUserAccessToken additional permission is granted.

View on Github

These methods can be used to open custom dialogs/confirmation panels.

Opens a custom modal. Returns a promise resolved with what the modal itself returns calling the resolve() function.

View on Github

1
const result = await ctx.openModal({
2
  id: 'regular',
3
  title: 'Custom title!',
4
  width: 'l',
5
  parameters: { foo: 'bar' },
6
});
7

8
if (result) {
9
  ctx.notice(`Success! ${JSON.stringify(result)}`);
10
} else {
11
  ctx.alert('Closed!');
12
}

Opens a UI-consistent confirmation dialog. Returns a promise resolved with the value of the choice made by the user.

View on Github

1
const result = await ctx.openConfirm({
2
  title: 'Custom title',
3
  content:
4
    'Lorem Ipsum is simply dummy text of the printing and typesetting industry',
5
  choices: [
6
    {
7
      label: 'Positive',
8
      value: 'positive',
9
      intent: 'positive',
10
    },
11
    {
12
      label: 'Negative',
13
      value: 'negative',
14
      intent: 'negative',
15
    },
16
  ],
17
  cancel: {
18
    label: 'Cancel',
19
    value: false,
20
  },
21
});
22

23
if (result) {
24
  ctx.notice(`Success! ${result}`);
25
} else {
26
  ctx.alert('Cancelled!');
27
}

These properties provide access to "entity repos", that is, the collection of resources of a particular type that have been loaded by the CMS up to this moment. The entity repos are objects, indexed by the ID of the entity itself.

All the models of the current DatoCMS project, indexed by ID.

View on Github

All the fields currently loaded for the current DatoCMS project, indexed by ID. If some fields you need are not present, use the loadItemTypeFields function to load them.

View on Github

All the fieldsets currently loaded for the current DatoCMS project, indexed by ID. If some fields you need are not present, use the loadItemTypeFieldsets function to load them.

View on Github

All the regular users currently loaded for the current DatoCMS project, indexed by ID. It will always contain the current user. If some users you need are not present, use the loadUsers function to load them.

View on Github

All the SSO users currently loaded for the current DatoCMS project, indexed by ID. It will always contain the current user. If some users you need are not present, use the loadSsoUsers function to load them.

View on Github

These methods let you open the standard DatoCMS dialogs needed to interact with records.

Opens a dialog for creating a new record. It returns a promise resolved with the newly created record or null if the user closes the dialog without creating anything.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const item = await ctx.createNewItem(itemTypeId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for selecting one (or multiple) record(s) from a list of existing records of type itemTypeId. It returns a promise resolved with the selected record(s), or null if the user closes the dialog without choosing any record.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const items = await ctx.selectItem(itemTypeId, { multiple: true });
4

5
if (items) {
6
  ctx.notice(`Success! ${items.map((i) => i.id).join(', ')}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for editing an existing record. It returns a promise resolved with the edited record, or null if the user closes the dialog without persisting any change.

View on Github

1
const itemId = prompt('Please insert a record ID:');
2

3
const item = await ctx.editItem(itemId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

These methods can be used to asyncronously load additional information your plugin needs to work.

Loads all the fields for a specific model (or block). Fields will be returned and will also be available in the the fields property.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const fields = await ctx.loadItemTypeFields(itemTypeId);
4

5
ctx.notice(
6
  `Success! ${fields
7
    .map((field) => field.attributes.api_key)
8
    .join(', ')}`,
9
);

Loads all the fieldsets for a specific model (or block). Fieldsets will be returned and will also be available in the the fieldsets property.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const fieldsets = await ctx.loadItemTypeFieldsets(itemTypeId);
4

5
ctx.notice(
6
  `Success! ${fieldsets
7
    .map((fieldset) => fieldset.attributes.title)
8
    .join(', ')}`,
9
);

Loads all the fields in the project that are currently using the plugin for one of its manual field extensions.

View on Github

1
const fields = await ctx.loadFieldsUsingPlugin();
2

3
ctx.notice(
4
  `Success! ${fields
5
    .map((field) => field.attributes.api_key)
6
    .join(', ')}`,
7
);

Loads all regular users. Users will be returned and will also be available in the the users property.

View on Github

1
const users = await ctx.loadUsers();
2

3
ctx.notice(`Success! ${users.map((user) => user.id).join(', ')}`);

Loads all SSO users. Users will be returned and will also be available in the the ssoUsers property.

View on Github

1
const users = await ctx.loadSsoUsers();
2

3
ctx.notice(`Success! ${users.map((user) => user.id).join(', ')}`);

These methods can be used to take the user to different pages.

Moves the user to another URL internal to the backend.

View on Github

1
await ctx.navigateTo('/');

Information about the current plugin. Useful to access the plugin's global configuration object.

The current plugin.

View on Github

The current DatoCMS project.

View on Github

The ID of the current environment.

View on Github

The account/organization that is the project owner.

View on Github

UI preferences of the current user (right now, only the preferred locale is available).

View on Github

An object containing the theme colors for the current DatoCMS project.

View on Github

These methods can be used to show UI-consistent toast notifications to the end-user.

Triggers an "error" toast displaying the selected message.

View on Github

1
const message = prompt(
2
  'Please insert a message:',
3
  'This is an alert message!',
4
);
5

6
await ctx.alert(message);

Triggers a "success" toast displaying the selected message.

View on Github

1
const message = prompt(
2
  'Please insert a message:',
3
  'This is a notice message!',
4
);
5

6
await ctx.notice(message);

Triggers a custom toast displaying the selected message (and optionally a CTA).

View on Github

1
const result = await ctx.customToast({
2
  type: 'warning',
3
  message: 'Just a sample warning notification!',
4
  dismissOnPageChange: true,
5
  dismissAfterTimeout: 5000,
6
  cta: {
7
    label: 'Execute call-to-action',
8
    value: 'cta',
9
  },
10
});
11

12
if (result === 'cta') {
13
  ctx.notice(`Clicked CTA!`);
14
}

These methods can be used to update both plugin parameters and manual field extensions configuration.

Updates the plugin parameters.

Always check ctx.currentRole.meta.final_permissions.can_edit_schema before calling this, as the user might not have the permission to perform the operation.

View on Github

1
await ctx.updatePluginParameters({ debugMode: true });
2
await ctx.notice('Plugin parameters successfully updated!');

Performs changes in the appearance of a field. You can install/remove a manual field extension, or tweak their parameters. If multiple changes are passed, they will be applied sequencially.

Always check ctx.currentRole.meta.final_permissions.can_edit_schema before calling this, as the user might not have the permission to perform the operation.

View on Github

1
const fields = await ctx.loadFieldsUsingPlugin();
2

3
if (fields.length === 0) {
4
  ctx.alert('No field is using this plugin as a manual extension!');
5
  return;
6
}
7

8
for (const field of fields) {
9
  const { appearance } = field.attributes;
10
  const operations = [];
11

12
  if (appearance.editor === ctx.plugin.id) {
13
    operations.push({
14
      operation: 'updateEditor',
15
      newParameters: {
16
        ...appearance.parameters,
17
        foo: 'bar',
18
      },
19
    });
20
  }
21

22
  appearance.addons.forEach((addon, i) => {
23
    if (addon.id !== ctx.plugin.id) {
24
      return;
25
    }
26

27
    operations.push({
28
      operation: 'updateAddon',
29
      index: i,
30
      newParameters: { ...addon.parameters, foo: 'bar' },
31
    });
32
  });
33

34
  await ctx.updateFieldAppearance(field.id, operations);
35
  ctx.notice(`Successfully edited field ${field.attributes.api_key}`);
36
}

These methods let you open the standard DatoCMS dialogs needed to interact with Media Area assets.

Opens a dialog for selecting one (or multiple) existing asset(s). It returns a promise resolved with the selected asset(s), or null if the user closes the dialog without selecting any upload.

View on Github

1
const item = await ctx.selectUpload({ multiple: false });
2

3
if (item) {
4
  ctx.notice(`Success! ${item.id}`);
5
} else {
6
  ctx.alert('Closed!');
7
}

Opens a dialog for editing a Media Area asset. It returns a promise resolved with:

The updated asset, if the user persists some changes to the asset itself
null, if the user closes the dialog without persisting any change
An asset structure with an additional deleted property set to true, if the user deletes the asset.

View on Github

1
const uploadId = prompt('Please insert an asset ID:');
2

3
const item = await ctx.editUpload(uploadId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for editing a "single asset" field structure. It returns a promise resolved with the updated structure, or null if the user closes the dialog without persisting any change.

View on Github

1
const uploadId = prompt('Please insert an asset ID:');
2

3
const result = await ctx.editUploadMetadata({
4
  upload_id: uploadId,
5
  alt: null,
6
  title: null,
7
  custom_data: {},
8
  focal_point: null,
9
});
10

11
if (result) {
12
  ctx.notice(`Success! ${JSON.stringify(result)}`);
13
} else {
14
  ctx.alert('Closed!');
15
}

`executeItemFormDropdownAction(actionId: string, ctx)`

Use this function to execute a particular dropdown action defined via the itemFormDropdownActions() hook.

Return value

The function must return: Promise<void>.

Context object

The following properties and methods are available in the ctx argument:

This hook exposes additional information and operations specific to the context in which it operates.

These methods can be used to interact with the form that's being shown to the end-user to edit a record.

Hides/shows a specific field in the form. Please be aware that when a field is hidden, the field editor for that field will be removed from the DOM itself, including any associated plugins. When it is shown again, its plugins will be reinitialized.

View on Github

1
const fieldPath = prompt(
2
  'Please insert the path of a field in the form',
3
  ctx.fieldPath,
4
);
5

6
await ctx.toggleField(fieldPath, true);

Disables/re-enables a specific field in the form.

View on Github

1
const fieldPath = prompt(
2
  'Please insert the path of a field in the form',
3
  ctx.fieldPath,
4
);
5

6
await ctx.disableField(fieldPath, true);

Smoothly navigates to a specific field in the form. If the field is localized it will switch language tab and then navigate to the chosen field.

View on Github

1
const fieldPath = prompt(
2
  'Please insert the path of a field in the form',
3
  ctx.fieldPath,
4
);
5

6
await ctx.scrollToField(fieldPath);

Changes a specific path of the formValues object.

View on Github

1
const fieldPath = prompt(
2
  'Please insert the path of a field in the form',
3
  ctx.fieldPath,
4
);
5

6
await ctx.setFieldValue(fieldPath, 'new value');

Takes the internal form state, and transforms it into an Item entity compatible with DatoCMS API.

When skipUnchangedFields, only the fields that changed value will be serialized.

If the required nested blocks are still not loaded, this method will return undefined.

View on Github

1
await ctx.formValuesToItem(ctx.formValues, false);

Takes an Item entity, and converts it into the internal form state.

View on Github

1
await ctx.itemToFormValues(ctx.item);

Triggers a submit form for current record.

View on Github

1
await ctx.saveCurrentItem();

These information describe the current state of the form that's being shown to the end-user to edit a record.

The currently active locale for the record.

View on Github

If an already persisted record is being edited, returns the full record entity.

View on Github

The model for the record being edited.

View on Github

The complete internal form state.

View on Github

The current status of the record being edited.

View on Github

Whether the form is currently submitting itself or not.

View on Github

Whether the form has some non-persisted changes or not.

View on Github

Provides information on how many blocks are currently present in the form.

View on Github

Every hook available in the Plugin SDK shares the same minumum set of properties and methods.

Information about the current user using the CMS.

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

View on Github

The role for the current DatoCMS user.

View on Github

The access token to perform API calls on behalf of the current user. Only available if currentUserAccessToken additional permission is granted.

View on Github

These methods can be used to open custom dialogs/confirmation panels.

Opens a custom modal. Returns a promise resolved with what the modal itself returns calling the resolve() function.

View on Github

1
const result = await ctx.openModal({
2
  id: 'regular',
3
  title: 'Custom title!',
4
  width: 'l',
5
  parameters: { foo: 'bar' },
6
});
7

8
if (result) {
9
  ctx.notice(`Success! ${JSON.stringify(result)}`);
10
} else {
11
  ctx.alert('Closed!');
12
}

Opens a UI-consistent confirmation dialog. Returns a promise resolved with the value of the choice made by the user.

View on Github

1
const result = await ctx.openConfirm({
2
  title: 'Custom title',
3
  content:
4
    'Lorem Ipsum is simply dummy text of the printing and typesetting industry',
5
  choices: [
6
    {
7
      label: 'Positive',
8
      value: 'positive',
9
      intent: 'positive',
10
    },
11
    {
12
      label: 'Negative',
13
      value: 'negative',
14
      intent: 'negative',
15
    },
16
  ],
17
  cancel: {
18
    label: 'Cancel',
19
    value: false,
20
  },
21
});
22

23
if (result) {
24
  ctx.notice(`Success! ${result}`);
25
} else {
26
  ctx.alert('Cancelled!');
27
}

These properties provide access to "entity repos", that is, the collection of resources of a particular type that have been loaded by the CMS up to this moment. The entity repos are objects, indexed by the ID of the entity itself.

All the models of the current DatoCMS project, indexed by ID.

View on Github

All the fields currently loaded for the current DatoCMS project, indexed by ID. If some fields you need are not present, use the loadItemTypeFields function to load them.

View on Github

All the fieldsets currently loaded for the current DatoCMS project, indexed by ID. If some fields you need are not present, use the loadItemTypeFieldsets function to load them.

View on Github

All the regular users currently loaded for the current DatoCMS project, indexed by ID. It will always contain the current user. If some users you need are not present, use the loadUsers function to load them.

View on Github

All the SSO users currently loaded for the current DatoCMS project, indexed by ID. It will always contain the current user. If some users you need are not present, use the loadSsoUsers function to load them.

View on Github

These methods let you open the standard DatoCMS dialogs needed to interact with records.

Opens a dialog for creating a new record. It returns a promise resolved with the newly created record or null if the user closes the dialog without creating anything.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const item = await ctx.createNewItem(itemTypeId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for selecting one (or multiple) record(s) from a list of existing records of type itemTypeId. It returns a promise resolved with the selected record(s), or null if the user closes the dialog without choosing any record.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const items = await ctx.selectItem(itemTypeId, { multiple: true });
4

5
if (items) {
6
  ctx.notice(`Success! ${items.map((i) => i.id).join(', ')}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for editing an existing record. It returns a promise resolved with the edited record, or null if the user closes the dialog without persisting any change.

View on Github

1
const itemId = prompt('Please insert a record ID:');
2

3
const item = await ctx.editItem(itemId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

These methods can be used to asyncronously load additional information your plugin needs to work.

Loads all the fields for a specific model (or block). Fields will be returned and will also be available in the the fields property.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const fields = await ctx.loadItemTypeFields(itemTypeId);
4

5
ctx.notice(
6
  `Success! ${fields
7
    .map((field) => field.attributes.api_key)
8
    .join(', ')}`,
9
);

Loads all the fieldsets for a specific model (or block). Fieldsets will be returned and will also be available in the the fieldsets property.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const fieldsets = await ctx.loadItemTypeFieldsets(itemTypeId);
4

5
ctx.notice(
6
  `Success! ${fieldsets
7
    .map((fieldset) => fieldset.attributes.title)
8
    .join(', ')}`,
9
);

Loads all the fields in the project that are currently using the plugin for one of its manual field extensions.

View on Github

1
const fields = await ctx.loadFieldsUsingPlugin();
2

3
ctx.notice(
4
  `Success! ${fields
5
    .map((field) => field.attributes.api_key)
6
    .join(', ')}`,
7
);

Loads all regular users. Users will be returned and will also be available in the the users property.

View on Github

1
const users = await ctx.loadUsers();
2

3
ctx.notice(`Success! ${users.map((user) => user.id).join(', ')}`);

Loads all SSO users. Users will be returned and will also be available in the the ssoUsers property.

View on Github

1
const users = await ctx.loadSsoUsers();
2

3
ctx.notice(`Success! ${users.map((user) => user.id).join(', ')}`);

These methods can be used to take the user to different pages.

Moves the user to another URL internal to the backend.

View on Github

1
await ctx.navigateTo('/');

Information about the current plugin. Useful to access the plugin's global configuration object.

The current plugin.

View on Github

The current DatoCMS project.

View on Github

The ID of the current environment.

View on Github

The account/organization that is the project owner.

View on Github

UI preferences of the current user (right now, only the preferred locale is available).

View on Github

An object containing the theme colors for the current DatoCMS project.

View on Github

These methods can be used to show UI-consistent toast notifications to the end-user.

Triggers an "error" toast displaying the selected message.

View on Github

1
const message = prompt(
2
  'Please insert a message:',
3
  'This is an alert message!',
4
);
5

6
await ctx.alert(message);

Triggers a "success" toast displaying the selected message.

View on Github

1
const message = prompt(
2
  'Please insert a message:',
3
  'This is a notice message!',
4
);
5

6
await ctx.notice(message);

Triggers a custom toast displaying the selected message (and optionally a CTA).

View on Github

1
const result = await ctx.customToast({
2
  type: 'warning',
3
  message: 'Just a sample warning notification!',
4
  dismissOnPageChange: true,
5
  dismissAfterTimeout: 5000,
6
  cta: {
7
    label: 'Execute call-to-action',
8
    value: 'cta',
9
  },
10
});
11

12
if (result === 'cta') {
13
  ctx.notice(`Clicked CTA!`);
14
}

These methods can be used to update both plugin parameters and manual field extensions configuration.

Updates the plugin parameters.

Always check ctx.currentRole.meta.final_permissions.can_edit_schema before calling this, as the user might not have the permission to perform the operation.

View on Github

1
await ctx.updatePluginParameters({ debugMode: true });
2
await ctx.notice('Plugin parameters successfully updated!');

Performs changes in the appearance of a field. You can install/remove a manual field extension, or tweak their parameters. If multiple changes are passed, they will be applied sequencially.

Always check ctx.currentRole.meta.final_permissions.can_edit_schema before calling this, as the user might not have the permission to perform the operation.

View on Github

1
const fields = await ctx.loadFieldsUsingPlugin();
2

3
if (fields.length === 0) {
4
  ctx.alert('No field is using this plugin as a manual extension!');
5
  return;
6
}
7

8
for (const field of fields) {
9
  const { appearance } = field.attributes;
10
  const operations = [];
11

12
  if (appearance.editor === ctx.plugin.id) {
13
    operations.push({
14
      operation: 'updateEditor',
15
      newParameters: {
16
        ...appearance.parameters,
17
        foo: 'bar',
18
      },
19
    });
20
  }
21

22
  appearance.addons.forEach((addon, i) => {
23
    if (addon.id !== ctx.plugin.id) {
24
      return;
25
    }
26

27
    operations.push({
28
      operation: 'updateAddon',
29
      index: i,
30
      newParameters: { ...addon.parameters, foo: 'bar' },
31
    });
32
  });
33

34
  await ctx.updateFieldAppearance(field.id, operations);
35
  ctx.notice(`Successfully edited field ${field.attributes.api_key}`);
36
}

These methods let you open the standard DatoCMS dialogs needed to interact with Media Area assets.

Opens a dialog for selecting one (or multiple) existing asset(s). It returns a promise resolved with the selected asset(s), or null if the user closes the dialog without selecting any upload.

View on Github

1
const item = await ctx.selectUpload({ multiple: false });
2

3
if (item) {
4
  ctx.notice(`Success! ${item.id}`);
5
} else {
6
  ctx.alert('Closed!');
7
}

Opens a dialog for editing a Media Area asset. It returns a promise resolved with:

The updated asset, if the user persists some changes to the asset itself
null, if the user closes the dialog without persisting any change
An asset structure with an additional deleted property set to true, if the user deletes the asset.

View on Github

1
const uploadId = prompt('Please insert an asset ID:');
2

3
const item = await ctx.editUpload(uploadId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for editing a "single asset" field structure. It returns a promise resolved with the updated structure, or null if the user closes the dialog without persisting any change.

View on Github

1
const uploadId = prompt('Please insert an asset ID:');
2

3
const result = await ctx.editUploadMetadata({
4
  upload_id: uploadId,
5
  alt: null,
6
  title: null,
7
  custom_data: {},
8
  focal_point: null,
9
});
10

11
if (result) {
12
  ctx.notice(`Success! ${JSON.stringify(result)}`);
13
} else {
14
  ctx.alert('Closed!');
15
}

`executeItemsDropdownAction(actionId: string, items: Item[], ctx)`

Use this function to execute a particular dropdown action defined via the itemsDropdownActions() hook.

Return value

The function must return: Promise<void>.

Context object

The following properties and methods are available in the ctx argument:

This hook exposes additional information and operations specific to the context in which it operates.

View on Github

Every hook available in the Plugin SDK shares the same minumum set of properties and methods.

Information about the current user using the CMS.

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

View on Github

The role for the current DatoCMS user.

View on Github

The access token to perform API calls on behalf of the current user. Only available if currentUserAccessToken additional permission is granted.

View on Github

These methods can be used to open custom dialogs/confirmation panels.

Opens a custom modal. Returns a promise resolved with what the modal itself returns calling the resolve() function.

View on Github

1
const result = await ctx.openModal({
2
  id: 'regular',
3
  title: 'Custom title!',
4
  width: 'l',
5
  parameters: { foo: 'bar' },
6
});
7

8
if (result) {
9
  ctx.notice(`Success! ${JSON.stringify(result)}`);
10
} else {
11
  ctx.alert('Closed!');
12
}

Opens a UI-consistent confirmation dialog. Returns a promise resolved with the value of the choice made by the user.

View on Github

1
const result = await ctx.openConfirm({
2
  title: 'Custom title',
3
  content:
4
    'Lorem Ipsum is simply dummy text of the printing and typesetting industry',
5
  choices: [
6
    {
7
      label: 'Positive',
8
      value: 'positive',
9
      intent: 'positive',
10
    },
11
    {
12
      label: 'Negative',
13
      value: 'negative',
14
      intent: 'negative',
15
    },
16
  ],
17
  cancel: {
18
    label: 'Cancel',
19
    value: false,
20
  },
21
});
22

23
if (result) {
24
  ctx.notice(`Success! ${result}`);
25
} else {
26
  ctx.alert('Cancelled!');
27
}

These properties provide access to "entity repos", that is, the collection of resources of a particular type that have been loaded by the CMS up to this moment. The entity repos are objects, indexed by the ID of the entity itself.

All the models of the current DatoCMS project, indexed by ID.

View on Github

All the fields currently loaded for the current DatoCMS project, indexed by ID. If some fields you need are not present, use the loadItemTypeFields function to load them.

View on Github

All the fieldsets currently loaded for the current DatoCMS project, indexed by ID. If some fields you need are not present, use the loadItemTypeFieldsets function to load them.

View on Github

All the regular users currently loaded for the current DatoCMS project, indexed by ID. It will always contain the current user. If some users you need are not present, use the loadUsers function to load them.

View on Github

All the SSO users currently loaded for the current DatoCMS project, indexed by ID. It will always contain the current user. If some users you need are not present, use the loadSsoUsers function to load them.

View on Github

These methods let you open the standard DatoCMS dialogs needed to interact with records.

Opens a dialog for creating a new record. It returns a promise resolved with the newly created record or null if the user closes the dialog without creating anything.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const item = await ctx.createNewItem(itemTypeId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for selecting one (or multiple) record(s) from a list of existing records of type itemTypeId. It returns a promise resolved with the selected record(s), or null if the user closes the dialog without choosing any record.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const items = await ctx.selectItem(itemTypeId, { multiple: true });
4

5
if (items) {
6
  ctx.notice(`Success! ${items.map((i) => i.id).join(', ')}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for editing an existing record. It returns a promise resolved with the edited record, or null if the user closes the dialog without persisting any change.

View on Github

1
const itemId = prompt('Please insert a record ID:');
2

3
const item = await ctx.editItem(itemId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

These methods can be used to asyncronously load additional information your plugin needs to work.

Loads all the fields for a specific model (or block). Fields will be returned and will also be available in the the fields property.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const fields = await ctx.loadItemTypeFields(itemTypeId);
4

5
ctx.notice(
6
  `Success! ${fields
7
    .map((field) => field.attributes.api_key)
8
    .join(', ')}`,
9
);

Loads all the fieldsets for a specific model (or block). Fieldsets will be returned and will also be available in the the fieldsets property.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const fieldsets = await ctx.loadItemTypeFieldsets(itemTypeId);
4

5
ctx.notice(
6
  `Success! ${fieldsets
7
    .map((fieldset) => fieldset.attributes.title)
8
    .join(', ')}`,
9
);

Loads all the fields in the project that are currently using the plugin for one of its manual field extensions.

View on Github

1
const fields = await ctx.loadFieldsUsingPlugin();
2

3
ctx.notice(
4
  `Success! ${fields
5
    .map((field) => field.attributes.api_key)
6
    .join(', ')}`,
7
);

Loads all regular users. Users will be returned and will also be available in the the users property.

View on Github

1
const users = await ctx.loadUsers();
2

3
ctx.notice(`Success! ${users.map((user) => user.id).join(', ')}`);

Loads all SSO users. Users will be returned and will also be available in the the ssoUsers property.

View on Github

1
const users = await ctx.loadSsoUsers();
2

3
ctx.notice(`Success! ${users.map((user) => user.id).join(', ')}`);

These methods can be used to take the user to different pages.

Moves the user to another URL internal to the backend.

View on Github

1
await ctx.navigateTo('/');

Information about the current plugin. Useful to access the plugin's global configuration object.

The current plugin.

View on Github

The current DatoCMS project.

View on Github

The ID of the current environment.

View on Github

The account/organization that is the project owner.

View on Github

UI preferences of the current user (right now, only the preferred locale is available).

View on Github

An object containing the theme colors for the current DatoCMS project.

View on Github

These methods can be used to show UI-consistent toast notifications to the end-user.

Triggers an "error" toast displaying the selected message.

View on Github

1
const message = prompt(
2
  'Please insert a message:',
3
  'This is an alert message!',
4
);
5

6
await ctx.alert(message);

Triggers a "success" toast displaying the selected message.

View on Github

1
const message = prompt(
2
  'Please insert a message:',
3
  'This is a notice message!',
4
);
5

6
await ctx.notice(message);

Triggers a custom toast displaying the selected message (and optionally a CTA).

View on Github

1
const result = await ctx.customToast({
2
  type: 'warning',
3
  message: 'Just a sample warning notification!',
4
  dismissOnPageChange: true,
5
  dismissAfterTimeout: 5000,
6
  cta: {
7
    label: 'Execute call-to-action',
8
    value: 'cta',
9
  },
10
});
11

12
if (result === 'cta') {
13
  ctx.notice(`Clicked CTA!`);
14
}

These methods can be used to update both plugin parameters and manual field extensions configuration.

Updates the plugin parameters.

Always check ctx.currentRole.meta.final_permissions.can_edit_schema before calling this, as the user might not have the permission to perform the operation.

View on Github

1
await ctx.updatePluginParameters({ debugMode: true });
2
await ctx.notice('Plugin parameters successfully updated!');

Performs changes in the appearance of a field. You can install/remove a manual field extension, or tweak their parameters. If multiple changes are passed, they will be applied sequencially.

Always check ctx.currentRole.meta.final_permissions.can_edit_schema before calling this, as the user might not have the permission to perform the operation.

View on Github

1
const fields = await ctx.loadFieldsUsingPlugin();
2

3
if (fields.length === 0) {
4
  ctx.alert('No field is using this plugin as a manual extension!');
5
  return;
6
}
7

8
for (const field of fields) {
9
  const { appearance } = field.attributes;
10
  const operations = [];
11

12
  if (appearance.editor === ctx.plugin.id) {
13
    operations.push({
14
      operation: 'updateEditor',
15
      newParameters: {
16
        ...appearance.parameters,
17
        foo: 'bar',
18
      },
19
    });
20
  }
21

22
  appearance.addons.forEach((addon, i) => {
23
    if (addon.id !== ctx.plugin.id) {
24
      return;
25
    }
26

27
    operations.push({
28
      operation: 'updateAddon',
29
      index: i,
30
      newParameters: { ...addon.parameters, foo: 'bar' },
31
    });
32
  });
33

34
  await ctx.updateFieldAppearance(field.id, operations);
35
  ctx.notice(`Successfully edited field ${field.attributes.api_key}`);
36
}

These methods let you open the standard DatoCMS dialogs needed to interact with Media Area assets.

Opens a dialog for selecting one (or multiple) existing asset(s). It returns a promise resolved with the selected asset(s), or null if the user closes the dialog without selecting any upload.

View on Github

1
const item = await ctx.selectUpload({ multiple: false });
2

3
if (item) {
4
  ctx.notice(`Success! ${item.id}`);
5
} else {
6
  ctx.alert('Closed!');
7
}

Opens a dialog for editing a Media Area asset. It returns a promise resolved with:

The updated asset, if the user persists some changes to the asset itself
null, if the user closes the dialog without persisting any change
An asset structure with an additional deleted property set to true, if the user deletes the asset.

View on Github

1
const uploadId = prompt('Please insert an asset ID:');
2

3
const item = await ctx.editUpload(uploadId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for editing a "single asset" field structure. It returns a promise resolved with the updated structure, or null if the user closes the dialog without persisting any change.

View on Github

1
const uploadId = prompt('Please insert an asset ID:');
2

3
const result = await ctx.editUploadMetadata({
4
  upload_id: uploadId,
5
  alt: null,
6
  title: null,
7
  custom_data: {},
8
  focal_point: null,
9
});
10

11
if (result) {
12
  ctx.notice(`Success! ${JSON.stringify(result)}`);
13
} else {
14
  ctx.alert('Closed!');
15
}

`executeUploadsDropdownAction(actionId: string, uploads: Upload[], ctx)`

Use this function to execute a particular dropdown action defined via the uploadsDropdownActions() hook.

Return value

The function must return: Promise<void>.

Context object

The following properties and methods are available in the ctx argument:

This hook exposes additional information and operations specific to the context in which it operates.

View on Github

Every hook available in the Plugin SDK shares the same minumum set of properties and methods.

Information about the current user using the CMS.

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

View on Github

The role for the current DatoCMS user.

View on Github

The access token to perform API calls on behalf of the current user. Only available if currentUserAccessToken additional permission is granted.

View on Github

These methods can be used to open custom dialogs/confirmation panels.

Opens a custom modal. Returns a promise resolved with what the modal itself returns calling the resolve() function.

View on Github

1
const result = await ctx.openModal({
2
  id: 'regular',
3
  title: 'Custom title!',
4
  width: 'l',
5
  parameters: { foo: 'bar' },
6
});
7

8
if (result) {
9
  ctx.notice(`Success! ${JSON.stringify(result)}`);
10
} else {
11
  ctx.alert('Closed!');
12
}

Opens a UI-consistent confirmation dialog. Returns a promise resolved with the value of the choice made by the user.

View on Github

1
const result = await ctx.openConfirm({
2
  title: 'Custom title',
3
  content:
4
    'Lorem Ipsum is simply dummy text of the printing and typesetting industry',
5
  choices: [
6
    {
7
      label: 'Positive',
8
      value: 'positive',
9
      intent: 'positive',
10
    },
11
    {
12
      label: 'Negative',
13
      value: 'negative',
14
      intent: 'negative',
15
    },
16
  ],
17
  cancel: {
18
    label: 'Cancel',
19
    value: false,
20
  },
21
});
22

23
if (result) {
24
  ctx.notice(`Success! ${result}`);
25
} else {
26
  ctx.alert('Cancelled!');
27
}

These properties provide access to "entity repos", that is, the collection of resources of a particular type that have been loaded by the CMS up to this moment. The entity repos are objects, indexed by the ID of the entity itself.

All the models of the current DatoCMS project, indexed by ID.

View on Github

All the fields currently loaded for the current DatoCMS project, indexed by ID. If some fields you need are not present, use the loadItemTypeFields function to load them.

View on Github

All the fieldsets currently loaded for the current DatoCMS project, indexed by ID. If some fields you need are not present, use the loadItemTypeFieldsets function to load them.

View on Github

All the regular users currently loaded for the current DatoCMS project, indexed by ID. It will always contain the current user. If some users you need are not present, use the loadUsers function to load them.

View on Github

All the SSO users currently loaded for the current DatoCMS project, indexed by ID. It will always contain the current user. If some users you need are not present, use the loadSsoUsers function to load them.

View on Github

These methods let you open the standard DatoCMS dialogs needed to interact with records.

Opens a dialog for creating a new record. It returns a promise resolved with the newly created record or null if the user closes the dialog without creating anything.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const item = await ctx.createNewItem(itemTypeId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for selecting one (or multiple) record(s) from a list of existing records of type itemTypeId. It returns a promise resolved with the selected record(s), or null if the user closes the dialog without choosing any record.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const items = await ctx.selectItem(itemTypeId, { multiple: true });
4

5
if (items) {
6
  ctx.notice(`Success! ${items.map((i) => i.id).join(', ')}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for editing an existing record. It returns a promise resolved with the edited record, or null if the user closes the dialog without persisting any change.

View on Github

1
const itemId = prompt('Please insert a record ID:');
2

3
const item = await ctx.editItem(itemId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

These methods can be used to asyncronously load additional information your plugin needs to work.

Loads all the fields for a specific model (or block). Fields will be returned and will also be available in the the fields property.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const fields = await ctx.loadItemTypeFields(itemTypeId);
4

5
ctx.notice(
6
  `Success! ${fields
7
    .map((field) => field.attributes.api_key)
8
    .join(', ')}`,
9
);

Loads all the fieldsets for a specific model (or block). Fieldsets will be returned and will also be available in the the fieldsets property.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const fieldsets = await ctx.loadItemTypeFieldsets(itemTypeId);
4

5
ctx.notice(
6
  `Success! ${fieldsets
7
    .map((fieldset) => fieldset.attributes.title)
8
    .join(', ')}`,
9
);

Loads all the fields in the project that are currently using the plugin for one of its manual field extensions.

View on Github

1
const fields = await ctx.loadFieldsUsingPlugin();
2

3
ctx.notice(
4
  `Success! ${fields
5
    .map((field) => field.attributes.api_key)
6
    .join(', ')}`,
7
);

Loads all regular users. Users will be returned and will also be available in the the users property.

View on Github

1
const users = await ctx.loadUsers();
2

3
ctx.notice(`Success! ${users.map((user) => user.id).join(', ')}`);

Loads all SSO users. Users will be returned and will also be available in the the ssoUsers property.

View on Github

1
const users = await ctx.loadSsoUsers();
2

3
ctx.notice(`Success! ${users.map((user) => user.id).join(', ')}`);

These methods can be used to take the user to different pages.

Moves the user to another URL internal to the backend.

View on Github

1
await ctx.navigateTo('/');

Information about the current plugin. Useful to access the plugin's global configuration object.

The current plugin.

View on Github

The current DatoCMS project.

View on Github

The ID of the current environment.

View on Github

The account/organization that is the project owner.

View on Github

UI preferences of the current user (right now, only the preferred locale is available).

View on Github

An object containing the theme colors for the current DatoCMS project.

View on Github

These methods can be used to show UI-consistent toast notifications to the end-user.

Triggers an "error" toast displaying the selected message.

View on Github

1
const message = prompt(
2
  'Please insert a message:',
3
  'This is an alert message!',
4
);
5

6
await ctx.alert(message);

Triggers a "success" toast displaying the selected message.

View on Github

1
const message = prompt(
2
  'Please insert a message:',
3
  'This is a notice message!',
4
);
5

6
await ctx.notice(message);

Triggers a custom toast displaying the selected message (and optionally a CTA).

View on Github

1
const result = await ctx.customToast({
2
  type: 'warning',
3
  message: 'Just a sample warning notification!',
4
  dismissOnPageChange: true,
5
  dismissAfterTimeout: 5000,
6
  cta: {
7
    label: 'Execute call-to-action',
8
    value: 'cta',
9
  },
10
});
11

12
if (result === 'cta') {
13
  ctx.notice(`Clicked CTA!`);
14
}

These methods can be used to update both plugin parameters and manual field extensions configuration.

Updates the plugin parameters.

Always check ctx.currentRole.meta.final_permissions.can_edit_schema before calling this, as the user might not have the permission to perform the operation.

View on Github

1
await ctx.updatePluginParameters({ debugMode: true });
2
await ctx.notice('Plugin parameters successfully updated!');

Performs changes in the appearance of a field. You can install/remove a manual field extension, or tweak their parameters. If multiple changes are passed, they will be applied sequencially.

Always check ctx.currentRole.meta.final_permissions.can_edit_schema before calling this, as the user might not have the permission to perform the operation.

View on Github

1
const fields = await ctx.loadFieldsUsingPlugin();
2

3
if (fields.length === 0) {
4
  ctx.alert('No field is using this plugin as a manual extension!');
5
  return;
6
}
7

8
for (const field of fields) {
9
  const { appearance } = field.attributes;
10
  const operations = [];
11

12
  if (appearance.editor === ctx.plugin.id) {
13
    operations.push({
14
      operation: 'updateEditor',
15
      newParameters: {
16
        ...appearance.parameters,
17
        foo: 'bar',
18
      },
19
    });
20
  }
21

22
  appearance.addons.forEach((addon, i) => {
23
    if (addon.id !== ctx.plugin.id) {
24
      return;
25
    }
26

27
    operations.push({
28
      operation: 'updateAddon',
29
      index: i,
30
      newParameters: { ...addon.parameters, foo: 'bar' },
31
    });
32
  });
33

34
  await ctx.updateFieldAppearance(field.id, operations);
35
  ctx.notice(`Successfully edited field ${field.attributes.api_key}`);
36
}

These methods let you open the standard DatoCMS dialogs needed to interact with Media Area assets.

Opens a dialog for selecting one (or multiple) existing asset(s). It returns a promise resolved with the selected asset(s), or null if the user closes the dialog without selecting any upload.

View on Github

1
const item = await ctx.selectUpload({ multiple: false });
2

3
if (item) {
4
  ctx.notice(`Success! ${item.id}`);
5
} else {
6
  ctx.alert('Closed!');
7
}

Opens a dialog for editing a Media Area asset. It returns a promise resolved with:

The updated asset, if the user persists some changes to the asset itself
null, if the user closes the dialog without persisting any change
An asset structure with an additional deleted property set to true, if the user deletes the asset.

View on Github

1
const uploadId = prompt('Please insert an asset ID:');
2

3
const item = await ctx.editUpload(uploadId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for editing a "single asset" field structure. It returns a promise resolved with the updated structure, or null if the user closes the dialog without persisting any change.

View on Github

1
const uploadId = prompt('Please insert an asset ID:');
2

3
const result = await ctx.editUploadMetadata({
4
  upload_id: uploadId,
5
  alt: null,
6
  title: null,
7
  custom_data: {},
8
  focal_point: null,
9
});
10

11
if (result) {
12
  ctx.notice(`Success! ${JSON.stringify(result)}`);
13
} else {
14
  ctx.alert('Closed!');
15
}

`fieldDropdownActions(field: Field, ctx)`

Use this function to define custom actions (or groups of actions) to be displayed at the individual field level in the record editing form.

The executeFieldDropdownAction() hook will be triggered once the user clicks on one of the defined actions.

Return value

The function must return: Array<DropdownAction | DropdownActionGroup>.

Context object

The following properties and methods are available in the ctx argument:

This hook exposes additional information and operations specific to the context in which it operates.

These information describe the current state of the field where this plugin is applied to.

Whether the field is currently disabled or not.

View on Github

The path in the formValues object where to find the current value for the field.

View on Github

The field where the field extension is installed to.

View on Github

If the field extension is installed in a field of a block, returns the top level Modular Content/Structured Text field containing the block itself.

View on Github

If the field extension is installed in a field of a block, returns the ID of the block — or undefined if the block is still not persisted — and the block model.

View on Github

These information describe the current state of the form that's being shown to the end-user to edit a record.

The currently active locale for the record.

View on Github

If an already persisted record is being edited, returns the full record entity.

View on Github

The model for the record being edited.

View on Github

The complete internal form state.

View on Github

The current status of the record being edited.

View on Github

Whether the form is currently submitting itself or not.

View on Github

Whether the form has some non-persisted changes or not.

View on Github

Provides information on how many blocks are currently present in the form.

View on Github

Every hook available in the Plugin SDK shares the same minumum set of properties and methods.

Information about the current user using the CMS.

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

View on Github

The role for the current DatoCMS user.

View on Github

The access token to perform API calls on behalf of the current user. Only available if currentUserAccessToken additional permission is granted.

View on Github

These methods can be used to open custom dialogs/confirmation panels.

Opens a custom modal. Returns a promise resolved with what the modal itself returns calling the resolve() function.

View on Github

1
const result = await ctx.openModal({
2
  id: 'regular',
3
  title: 'Custom title!',
4
  width: 'l',
5
  parameters: { foo: 'bar' },
6
});
7

8
if (result) {
9
  ctx.notice(`Success! ${JSON.stringify(result)}`);
10
} else {
11
  ctx.alert('Closed!');
12
}

Opens a UI-consistent confirmation dialog. Returns a promise resolved with the value of the choice made by the user.

View on Github

1
const result = await ctx.openConfirm({
2
  title: 'Custom title',
3
  content:
4
    'Lorem Ipsum is simply dummy text of the printing and typesetting industry',
5
  choices: [
6
    {
7
      label: 'Positive',
8
      value: 'positive',
9
      intent: 'positive',
10
    },
11
    {
12
      label: 'Negative',
13
      value: 'negative',
14
      intent: 'negative',
15
    },
16
  ],
17
  cancel: {
18
    label: 'Cancel',
19
    value: false,
20
  },
21
});
22

23
if (result) {
24
  ctx.notice(`Success! ${result}`);
25
} else {
26
  ctx.alert('Cancelled!');
27
}

These properties provide access to "entity repos", that is, the collection of resources of a particular type that have been loaded by the CMS up to this moment. The entity repos are objects, indexed by the ID of the entity itself.

All the models of the current DatoCMS project, indexed by ID.

View on Github

All the fields currently loaded for the current DatoCMS project, indexed by ID. If some fields you need are not present, use the loadItemTypeFields function to load them.

View on Github

All the fieldsets currently loaded for the current DatoCMS project, indexed by ID. If some fields you need are not present, use the loadItemTypeFieldsets function to load them.

View on Github

All the regular users currently loaded for the current DatoCMS project, indexed by ID. It will always contain the current user. If some users you need are not present, use the loadUsers function to load them.

View on Github

All the SSO users currently loaded for the current DatoCMS project, indexed by ID. It will always contain the current user. If some users you need are not present, use the loadSsoUsers function to load them.

View on Github

These methods let you open the standard DatoCMS dialogs needed to interact with records.

Opens a dialog for creating a new record. It returns a promise resolved with the newly created record or null if the user closes the dialog without creating anything.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const item = await ctx.createNewItem(itemTypeId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for selecting one (or multiple) record(s) from a list of existing records of type itemTypeId. It returns a promise resolved with the selected record(s), or null if the user closes the dialog without choosing any record.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const items = await ctx.selectItem(itemTypeId, { multiple: true });
4

5
if (items) {
6
  ctx.notice(`Success! ${items.map((i) => i.id).join(', ')}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for editing an existing record. It returns a promise resolved with the edited record, or null if the user closes the dialog without persisting any change.

View on Github

1
const itemId = prompt('Please insert a record ID:');
2

3
const item = await ctx.editItem(itemId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

These methods can be used to asyncronously load additional information your plugin needs to work.

Loads all the fields for a specific model (or block). Fields will be returned and will also be available in the the fields property.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const fields = await ctx.loadItemTypeFields(itemTypeId);
4

5
ctx.notice(
6
  `Success! ${fields
7
    .map((field) => field.attributes.api_key)
8
    .join(', ')}`,
9
);

Loads all the fieldsets for a specific model (or block). Fieldsets will be returned and will also be available in the the fieldsets property.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const fieldsets = await ctx.loadItemTypeFieldsets(itemTypeId);
4

5
ctx.notice(
6
  `Success! ${fieldsets
7
    .map((fieldset) => fieldset.attributes.title)
8
    .join(', ')}`,
9
);

Loads all the fields in the project that are currently using the plugin for one of its manual field extensions.

View on Github

1
const fields = await ctx.loadFieldsUsingPlugin();
2

3
ctx.notice(
4
  `Success! ${fields
5
    .map((field) => field.attributes.api_key)
6
    .join(', ')}`,
7
);

Loads all regular users. Users will be returned and will also be available in the the users property.

View on Github

1
const users = await ctx.loadUsers();
2

3
ctx.notice(`Success! ${users.map((user) => user.id).join(', ')}`);

Loads all SSO users. Users will be returned and will also be available in the the ssoUsers property.

View on Github

1
const users = await ctx.loadSsoUsers();
2

3
ctx.notice(`Success! ${users.map((user) => user.id).join(', ')}`);

These methods can be used to take the user to different pages.

Moves the user to another URL internal to the backend.

View on Github

1
await ctx.navigateTo('/');

Information about the current plugin. Useful to access the plugin's global configuration object.

The current plugin.

View on Github

The current DatoCMS project.

View on Github

The ID of the current environment.

View on Github

The account/organization that is the project owner.

View on Github

UI preferences of the current user (right now, only the preferred locale is available).

View on Github

An object containing the theme colors for the current DatoCMS project.

View on Github

These methods can be used to show UI-consistent toast notifications to the end-user.

Triggers an "error" toast displaying the selected message.

View on Github

1
const message = prompt(
2
  'Please insert a message:',
3
  'This is an alert message!',
4
);
5

6
await ctx.alert(message);

Triggers a "success" toast displaying the selected message.

View on Github

1
const message = prompt(
2
  'Please insert a message:',
3
  'This is a notice message!',
4
);
5

6
await ctx.notice(message);

Triggers a custom toast displaying the selected message (and optionally a CTA).

View on Github

1
const result = await ctx.customToast({
2
  type: 'warning',
3
  message: 'Just a sample warning notification!',
4
  dismissOnPageChange: true,
5
  dismissAfterTimeout: 5000,
6
  cta: {
7
    label: 'Execute call-to-action',
8
    value: 'cta',
9
  },
10
});
11

12
if (result === 'cta') {
13
  ctx.notice(`Clicked CTA!`);
14
}

These methods can be used to update both plugin parameters and manual field extensions configuration.

Updates the plugin parameters.

Always check ctx.currentRole.meta.final_permissions.can_edit_schema before calling this, as the user might not have the permission to perform the operation.

View on Github

1
await ctx.updatePluginParameters({ debugMode: true });
2
await ctx.notice('Plugin parameters successfully updated!');

Performs changes in the appearance of a field. You can install/remove a manual field extension, or tweak their parameters. If multiple changes are passed, they will be applied sequencially.

Always check ctx.currentRole.meta.final_permissions.can_edit_schema before calling this, as the user might not have the permission to perform the operation.

View on Github

1
const fields = await ctx.loadFieldsUsingPlugin();
2

3
if (fields.length === 0) {
4
  ctx.alert('No field is using this plugin as a manual extension!');
5
  return;
6
}
7

8
for (const field of fields) {
9
  const { appearance } = field.attributes;
10
  const operations = [];
11

12
  if (appearance.editor === ctx.plugin.id) {
13
    operations.push({
14
      operation: 'updateEditor',
15
      newParameters: {
16
        ...appearance.parameters,
17
        foo: 'bar',
18
      },
19
    });
20
  }
21

22
  appearance.addons.forEach((addon, i) => {
23
    if (addon.id !== ctx.plugin.id) {
24
      return;
25
    }
26

27
    operations.push({
28
      operation: 'updateAddon',
29
      index: i,
30
      newParameters: { ...addon.parameters, foo: 'bar' },
31
    });
32
  });
33

34
  await ctx.updateFieldAppearance(field.id, operations);
35
  ctx.notice(`Successfully edited field ${field.attributes.api_key}`);
36
}

These methods let you open the standard DatoCMS dialogs needed to interact with Media Area assets.

Opens a dialog for selecting one (or multiple) existing asset(s). It returns a promise resolved with the selected asset(s), or null if the user closes the dialog without selecting any upload.

View on Github

1
const item = await ctx.selectUpload({ multiple: false });
2

3
if (item) {
4
  ctx.notice(`Success! ${item.id}`);
5
} else {
6
  ctx.alert('Closed!');
7
}

Opens a dialog for editing a Media Area asset. It returns a promise resolved with:

The updated asset, if the user persists some changes to the asset itself
null, if the user closes the dialog without persisting any change
An asset structure with an additional deleted property set to true, if the user deletes the asset.

View on Github

1
const uploadId = prompt('Please insert an asset ID:');
2

3
const item = await ctx.editUpload(uploadId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for editing a "single asset" field structure. It returns a promise resolved with the updated structure, or null if the user closes the dialog without persisting any change.

View on Github

1
const uploadId = prompt('Please insert an asset ID:');
2

3
const result = await ctx.editUploadMetadata({
4
  upload_id: uploadId,
5
  alt: null,
6
  title: null,
7
  custom_data: {},
8
  focal_point: null,
9
});
10

11
if (result) {
12
  ctx.notice(`Success! ${JSON.stringify(result)}`);
13
} else {
14
  ctx.alert('Closed!');
15
}

`itemFormDropdownActions(itemType: ItemType, ctx)`

Use this function to define custom actions (or groups of actions) to be displayed at when editing a particular record.

The executeItemFormDropdownAction() hook will be triggered once the user clicks on one of the defined actions.

Return value

The function must return: Array<DropdownAction | DropdownActionGroup>.

Context object

The following properties and methods are available in the ctx argument:

This hook exposes additional information and operations specific to the context in which it operates.

These information describe the current state of the form that's being shown to the end-user to edit a record.

The currently active locale for the record.

View on Github

If an already persisted record is being edited, returns the full record entity.

View on Github

The model for the record being edited.

View on Github

The complete internal form state.

View on Github

The current status of the record being edited.

View on Github

Whether the form is currently submitting itself or not.

View on Github

Whether the form has some non-persisted changes or not.

View on Github

Provides information on how many blocks are currently present in the form.

View on Github

Every hook available in the Plugin SDK shares the same minumum set of properties and methods.

Information about the current user using the CMS.

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

View on Github

The role for the current DatoCMS user.

View on Github

The access token to perform API calls on behalf of the current user. Only available if currentUserAccessToken additional permission is granted.

View on Github

These methods can be used to open custom dialogs/confirmation panels.

Opens a custom modal. Returns a promise resolved with what the modal itself returns calling the resolve() function.

View on Github

1
const result = await ctx.openModal({
2
  id: 'regular',
3
  title: 'Custom title!',
4
  width: 'l',
5
  parameters: { foo: 'bar' },
6
});
7

8
if (result) {
9
  ctx.notice(`Success! ${JSON.stringify(result)}`);
10
} else {
11
  ctx.alert('Closed!');
12
}

Opens a UI-consistent confirmation dialog. Returns a promise resolved with the value of the choice made by the user.

View on Github

1
const result = await ctx.openConfirm({
2
  title: 'Custom title',
3
  content:
4
    'Lorem Ipsum is simply dummy text of the printing and typesetting industry',
5
  choices: [
6
    {
7
      label: 'Positive',
8
      value: 'positive',
9
      intent: 'positive',
10
    },
11
    {
12
      label: 'Negative',
13
      value: 'negative',
14
      intent: 'negative',
15
    },
16
  ],
17
  cancel: {
18
    label: 'Cancel',
19
    value: false,
20
  },
21
});
22

23
if (result) {
24
  ctx.notice(`Success! ${result}`);
25
} else {
26
  ctx.alert('Cancelled!');
27
}

These properties provide access to "entity repos", that is, the collection of resources of a particular type that have been loaded by the CMS up to this moment. The entity repos are objects, indexed by the ID of the entity itself.

All the models of the current DatoCMS project, indexed by ID.

View on Github

All the fields currently loaded for the current DatoCMS project, indexed by ID. If some fields you need are not present, use the loadItemTypeFields function to load them.

View on Github

All the fieldsets currently loaded for the current DatoCMS project, indexed by ID. If some fields you need are not present, use the loadItemTypeFieldsets function to load them.

View on Github

All the regular users currently loaded for the current DatoCMS project, indexed by ID. It will always contain the current user. If some users you need are not present, use the loadUsers function to load them.

View on Github

All the SSO users currently loaded for the current DatoCMS project, indexed by ID. It will always contain the current user. If some users you need are not present, use the loadSsoUsers function to load them.

View on Github

These methods let you open the standard DatoCMS dialogs needed to interact with records.

Opens a dialog for creating a new record. It returns a promise resolved with the newly created record or null if the user closes the dialog without creating anything.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const item = await ctx.createNewItem(itemTypeId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for selecting one (or multiple) record(s) from a list of existing records of type itemTypeId. It returns a promise resolved with the selected record(s), or null if the user closes the dialog without choosing any record.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const items = await ctx.selectItem(itemTypeId, { multiple: true });
4

5
if (items) {
6
  ctx.notice(`Success! ${items.map((i) => i.id).join(', ')}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for editing an existing record. It returns a promise resolved with the edited record, or null if the user closes the dialog without persisting any change.

View on Github

1
const itemId = prompt('Please insert a record ID:');
2

3
const item = await ctx.editItem(itemId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

These methods can be used to asyncronously load additional information your plugin needs to work.

Loads all the fields for a specific model (or block). Fields will be returned and will also be available in the the fields property.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const fields = await ctx.loadItemTypeFields(itemTypeId);
4

5
ctx.notice(
6
  `Success! ${fields
7
    .map((field) => field.attributes.api_key)
8
    .join(', ')}`,
9
);

Loads all the fieldsets for a specific model (or block). Fieldsets will be returned and will also be available in the the fieldsets property.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const fieldsets = await ctx.loadItemTypeFieldsets(itemTypeId);
4

5
ctx.notice(
6
  `Success! ${fieldsets
7
    .map((fieldset) => fieldset.attributes.title)
8
    .join(', ')}`,
9
);

Loads all the fields in the project that are currently using the plugin for one of its manual field extensions.

View on Github

1
const fields = await ctx.loadFieldsUsingPlugin();
2

3
ctx.notice(
4
  `Success! ${fields
5
    .map((field) => field.attributes.api_key)
6
    .join(', ')}`,
7
);

Loads all regular users. Users will be returned and will also be available in the the users property.

View on Github

1
const users = await ctx.loadUsers();
2

3
ctx.notice(`Success! ${users.map((user) => user.id).join(', ')}`);

Loads all SSO users. Users will be returned and will also be available in the the ssoUsers property.

View on Github

1
const users = await ctx.loadSsoUsers();
2

3
ctx.notice(`Success! ${users.map((user) => user.id).join(', ')}`);

These methods can be used to take the user to different pages.

Moves the user to another URL internal to the backend.

View on Github

1
await ctx.navigateTo('/');

Information about the current plugin. Useful to access the plugin's global configuration object.

The current plugin.

View on Github

The current DatoCMS project.

View on Github

The ID of the current environment.

View on Github

The account/organization that is the project owner.

View on Github

UI preferences of the current user (right now, only the preferred locale is available).

View on Github

An object containing the theme colors for the current DatoCMS project.

View on Github

These methods can be used to show UI-consistent toast notifications to the end-user.

Triggers an "error" toast displaying the selected message.

View on Github

1
const message = prompt(
2
  'Please insert a message:',
3
  'This is an alert message!',
4
);
5

6
await ctx.alert(message);

Triggers a "success" toast displaying the selected message.

View on Github

1
const message = prompt(
2
  'Please insert a message:',
3
  'This is a notice message!',
4
);
5

6
await ctx.notice(message);

Triggers a custom toast displaying the selected message (and optionally a CTA).

View on Github

1
const result = await ctx.customToast({
2
  type: 'warning',
3
  message: 'Just a sample warning notification!',
4
  dismissOnPageChange: true,
5
  dismissAfterTimeout: 5000,
6
  cta: {
7
    label: 'Execute call-to-action',
8
    value: 'cta',
9
  },
10
});
11

12
if (result === 'cta') {
13
  ctx.notice(`Clicked CTA!`);
14
}

These methods can be used to update both plugin parameters and manual field extensions configuration.

Updates the plugin parameters.

Always check ctx.currentRole.meta.final_permissions.can_edit_schema before calling this, as the user might not have the permission to perform the operation.

View on Github

1
await ctx.updatePluginParameters({ debugMode: true });
2
await ctx.notice('Plugin parameters successfully updated!');

Performs changes in the appearance of a field. You can install/remove a manual field extension, or tweak their parameters. If multiple changes are passed, they will be applied sequencially.

Always check ctx.currentRole.meta.final_permissions.can_edit_schema before calling this, as the user might not have the permission to perform the operation.

View on Github

1
const fields = await ctx.loadFieldsUsingPlugin();
2

3
if (fields.length === 0) {
4
  ctx.alert('No field is using this plugin as a manual extension!');
5
  return;
6
}
7

8
for (const field of fields) {
9
  const { appearance } = field.attributes;
10
  const operations = [];
11

12
  if (appearance.editor === ctx.plugin.id) {
13
    operations.push({
14
      operation: 'updateEditor',
15
      newParameters: {
16
        ...appearance.parameters,
17
        foo: 'bar',
18
      },
19
    });
20
  }
21

22
  appearance.addons.forEach((addon, i) => {
23
    if (addon.id !== ctx.plugin.id) {
24
      return;
25
    }
26

27
    operations.push({
28
      operation: 'updateAddon',
29
      index: i,
30
      newParameters: { ...addon.parameters, foo: 'bar' },
31
    });
32
  });
33

34
  await ctx.updateFieldAppearance(field.id, operations);
35
  ctx.notice(`Successfully edited field ${field.attributes.api_key}`);
36
}

These methods let you open the standard DatoCMS dialogs needed to interact with Media Area assets.

Opens a dialog for selecting one (or multiple) existing asset(s). It returns a promise resolved with the selected asset(s), or null if the user closes the dialog without selecting any upload.

View on Github

1
const item = await ctx.selectUpload({ multiple: false });
2

3
if (item) {
4
  ctx.notice(`Success! ${item.id}`);
5
} else {
6
  ctx.alert('Closed!');
7
}

Opens a dialog for editing a Media Area asset. It returns a promise resolved with:

The updated asset, if the user persists some changes to the asset itself
null, if the user closes the dialog without persisting any change
An asset structure with an additional deleted property set to true, if the user deletes the asset.

View on Github

1
const uploadId = prompt('Please insert an asset ID:');
2

3
const item = await ctx.editUpload(uploadId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for editing a "single asset" field structure. It returns a promise resolved with the updated structure, or null if the user closes the dialog without persisting any change.

View on Github

1
const uploadId = prompt('Please insert an asset ID:');
2

3
const result = await ctx.editUploadMetadata({
4
  upload_id: uploadId,
5
  alt: null,
6
  title: null,
7
  custom_data: {},
8
  focal_point: null,
9
});
10

11
if (result) {
12
  ctx.notice(`Success! ${JSON.stringify(result)}`);
13
} else {
14
  ctx.alert('Closed!');
15
}

`itemsDropdownActions(itemType: ItemType, ctx)`

This function lets you set up custom actions (or groups of actions) that show up when the user:

selects multiple records in the collection view for batch operations, or
starts editing a specific record.

The executeItemsDropdownAction() hook will be triggered once the user clicks on one of the defined actions.

Return value

The function must return: Array<DropdownAction | DropdownActionGroup>.

Context object

The following properties and methods are available in the ctx argument:

This hook exposes additional information and operations specific to the context in which it operates.

View on Github

Every hook available in the Plugin SDK shares the same minumum set of properties and methods.

Information about the current user using the CMS.

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

View on Github

The role for the current DatoCMS user.

View on Github

The access token to perform API calls on behalf of the current user. Only available if currentUserAccessToken additional permission is granted.

View on Github

These methods can be used to open custom dialogs/confirmation panels.

Opens a custom modal. Returns a promise resolved with what the modal itself returns calling the resolve() function.

View on Github

1
const result = await ctx.openModal({
2
  id: 'regular',
3
  title: 'Custom title!',
4
  width: 'l',
5
  parameters: { foo: 'bar' },
6
});
7

8
if (result) {
9
  ctx.notice(`Success! ${JSON.stringify(result)}`);
10
} else {
11
  ctx.alert('Closed!');
12
}

Opens a UI-consistent confirmation dialog. Returns a promise resolved with the value of the choice made by the user.

View on Github

1
const result = await ctx.openConfirm({
2
  title: 'Custom title',
3
  content:
4
    'Lorem Ipsum is simply dummy text of the printing and typesetting industry',
5
  choices: [
6
    {
7
      label: 'Positive',
8
      value: 'positive',
9
      intent: 'positive',
10
    },
11
    {
12
      label: 'Negative',
13
      value: 'negative',
14
      intent: 'negative',
15
    },
16
  ],
17
  cancel: {
18
    label: 'Cancel',
19
    value: false,
20
  },
21
});
22

23
if (result) {
24
  ctx.notice(`Success! ${result}`);
25
} else {
26
  ctx.alert('Cancelled!');
27
}

These properties provide access to "entity repos", that is, the collection of resources of a particular type that have been loaded by the CMS up to this moment. The entity repos are objects, indexed by the ID of the entity itself.

All the models of the current DatoCMS project, indexed by ID.

View on Github

All the fields currently loaded for the current DatoCMS project, indexed by ID. If some fields you need are not present, use the loadItemTypeFields function to load them.

View on Github

All the fieldsets currently loaded for the current DatoCMS project, indexed by ID. If some fields you need are not present, use the loadItemTypeFieldsets function to load them.

View on Github

All the regular users currently loaded for the current DatoCMS project, indexed by ID. It will always contain the current user. If some users you need are not present, use the loadUsers function to load them.

View on Github

All the SSO users currently loaded for the current DatoCMS project, indexed by ID. It will always contain the current user. If some users you need are not present, use the loadSsoUsers function to load them.

View on Github

These methods let you open the standard DatoCMS dialogs needed to interact with records.

Opens a dialog for creating a new record. It returns a promise resolved with the newly created record or null if the user closes the dialog without creating anything.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const item = await ctx.createNewItem(itemTypeId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for selecting one (or multiple) record(s) from a list of existing records of type itemTypeId. It returns a promise resolved with the selected record(s), or null if the user closes the dialog without choosing any record.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const items = await ctx.selectItem(itemTypeId, { multiple: true });
4

5
if (items) {
6
  ctx.notice(`Success! ${items.map((i) => i.id).join(', ')}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for editing an existing record. It returns a promise resolved with the edited record, or null if the user closes the dialog without persisting any change.

View on Github

1
const itemId = prompt('Please insert a record ID:');
2

3
const item = await ctx.editItem(itemId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

These methods can be used to asyncronously load additional information your plugin needs to work.

Loads all the fields for a specific model (or block). Fields will be returned and will also be available in the the fields property.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const fields = await ctx.loadItemTypeFields(itemTypeId);
4

5
ctx.notice(
6
  `Success! ${fields
7
    .map((field) => field.attributes.api_key)
8
    .join(', ')}`,
9
);

Loads all the fieldsets for a specific model (or block). Fieldsets will be returned and will also be available in the the fieldsets property.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const fieldsets = await ctx.loadItemTypeFieldsets(itemTypeId);
4

5
ctx.notice(
6
  `Success! ${fieldsets
7
    .map((fieldset) => fieldset.attributes.title)
8
    .join(', ')}`,
9
);

Loads all the fields in the project that are currently using the plugin for one of its manual field extensions.

View on Github

1
const fields = await ctx.loadFieldsUsingPlugin();
2

3
ctx.notice(
4
  `Success! ${fields
5
    .map((field) => field.attributes.api_key)
6
    .join(', ')}`,
7
);

Loads all regular users. Users will be returned and will also be available in the the users property.

View on Github

1
const users = await ctx.loadUsers();
2

3
ctx.notice(`Success! ${users.map((user) => user.id).join(', ')}`);

Loads all SSO users. Users will be returned and will also be available in the the ssoUsers property.

View on Github

1
const users = await ctx.loadSsoUsers();
2

3
ctx.notice(`Success! ${users.map((user) => user.id).join(', ')}`);

These methods can be used to take the user to different pages.

Moves the user to another URL internal to the backend.

View on Github

1
await ctx.navigateTo('/');

Information about the current plugin. Useful to access the plugin's global configuration object.

The current plugin.

View on Github

The current DatoCMS project.

View on Github

The ID of the current environment.

View on Github

The account/organization that is the project owner.

View on Github

UI preferences of the current user (right now, only the preferred locale is available).

View on Github

An object containing the theme colors for the current DatoCMS project.

View on Github

These methods can be used to show UI-consistent toast notifications to the end-user.

Triggers an "error" toast displaying the selected message.

View on Github

1
const message = prompt(
2
  'Please insert a message:',
3
  'This is an alert message!',
4
);
5

6
await ctx.alert(message);

Triggers a "success" toast displaying the selected message.

View on Github

1
const message = prompt(
2
  'Please insert a message:',
3
  'This is a notice message!',
4
);
5

6
await ctx.notice(message);

Triggers a custom toast displaying the selected message (and optionally a CTA).

View on Github

1
const result = await ctx.customToast({
2
  type: 'warning',
3
  message: 'Just a sample warning notification!',
4
  dismissOnPageChange: true,
5
  dismissAfterTimeout: 5000,
6
  cta: {
7
    label: 'Execute call-to-action',
8
    value: 'cta',
9
  },
10
});
11

12
if (result === 'cta') {
13
  ctx.notice(`Clicked CTA!`);
14
}

These methods can be used to update both plugin parameters and manual field extensions configuration.

Updates the plugin parameters.

Always check ctx.currentRole.meta.final_permissions.can_edit_schema before calling this, as the user might not have the permission to perform the operation.

View on Github

1
await ctx.updatePluginParameters({ debugMode: true });
2
await ctx.notice('Plugin parameters successfully updated!');

Performs changes in the appearance of a field. You can install/remove a manual field extension, or tweak their parameters. If multiple changes are passed, they will be applied sequencially.

Always check ctx.currentRole.meta.final_permissions.can_edit_schema before calling this, as the user might not have the permission to perform the operation.

View on Github

1
const fields = await ctx.loadFieldsUsingPlugin();
2

3
if (fields.length === 0) {
4
  ctx.alert('No field is using this plugin as a manual extension!');
5
  return;
6
}
7

8
for (const field of fields) {
9
  const { appearance } = field.attributes;
10
  const operations = [];
11

12
  if (appearance.editor === ctx.plugin.id) {
13
    operations.push({
14
      operation: 'updateEditor',
15
      newParameters: {
16
        ...appearance.parameters,
17
        foo: 'bar',
18
      },
19
    });
20
  }
21

22
  appearance.addons.forEach((addon, i) => {
23
    if (addon.id !== ctx.plugin.id) {
24
      return;
25
    }
26

27
    operations.push({
28
      operation: 'updateAddon',
29
      index: i,
30
      newParameters: { ...addon.parameters, foo: 'bar' },
31
    });
32
  });
33

34
  await ctx.updateFieldAppearance(field.id, operations);
35
  ctx.notice(`Successfully edited field ${field.attributes.api_key}`);
36
}

These methods let you open the standard DatoCMS dialogs needed to interact with Media Area assets.

Opens a dialog for selecting one (or multiple) existing asset(s). It returns a promise resolved with the selected asset(s), or null if the user closes the dialog without selecting any upload.

View on Github

1
const item = await ctx.selectUpload({ multiple: false });
2

3
if (item) {
4
  ctx.notice(`Success! ${item.id}`);
5
} else {
6
  ctx.alert('Closed!');
7
}

Opens a dialog for editing a Media Area asset. It returns a promise resolved with:

The updated asset, if the user persists some changes to the asset itself
null, if the user closes the dialog without persisting any change
An asset structure with an additional deleted property set to true, if the user deletes the asset.

View on Github

1
const uploadId = prompt('Please insert an asset ID:');
2

3
const item = await ctx.editUpload(uploadId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for editing a "single asset" field structure. It returns a promise resolved with the updated structure, or null if the user closes the dialog without persisting any change.

View on Github

1
const uploadId = prompt('Please insert an asset ID:');
2

3
const result = await ctx.editUploadMetadata({
4
  upload_id: uploadId,
5
  alt: null,
6
  title: null,
7
  custom_data: {},
8
  focal_point: null,
9
});
10

11
if (result) {
12
  ctx.notice(`Success! ${JSON.stringify(result)}`);
13
} else {
14
  ctx.alert('Closed!');
15
}

`uploadsDropdownActions(ctx)`

This function lets you set up custom actions (or groups of actions) that show up when the user:

selects multiple assets in the Media Area for batch operations, or
opens up a specific asset from the Media Area.

The executeUploadsDropdownAction() hook will be triggered once the user clicks on one of the defined actions.

Return value

The function must return: Array<DropdownAction | DropdownActionGroup>.

Context object

The following properties and methods are available in the ctx argument:

Every hook available in the Plugin SDK shares the same minumum set of properties and methods.

Information about the current user using the CMS.

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

View on Github

The role for the current DatoCMS user.

View on Github

The access token to perform API calls on behalf of the current user. Only available if currentUserAccessToken additional permission is granted.

View on Github

These methods can be used to open custom dialogs/confirmation panels.

Opens a custom modal. Returns a promise resolved with what the modal itself returns calling the resolve() function.

View on Github

1
const result = await ctx.openModal({
2
  id: 'regular',
3
  title: 'Custom title!',
4
  width: 'l',
5
  parameters: { foo: 'bar' },
6
});
7

8
if (result) {
9
  ctx.notice(`Success! ${JSON.stringify(result)}`);
10
} else {
11
  ctx.alert('Closed!');
12
}

Opens a UI-consistent confirmation dialog. Returns a promise resolved with the value of the choice made by the user.

View on Github

1
const result = await ctx.openConfirm({
2
  title: 'Custom title',
3
  content:
4
    'Lorem Ipsum is simply dummy text of the printing and typesetting industry',
5
  choices: [
6
    {
7
      label: 'Positive',
8
      value: 'positive',
9
      intent: 'positive',
10
    },
11
    {
12
      label: 'Negative',
13
      value: 'negative',
14
      intent: 'negative',
15
    },
16
  ],
17
  cancel: {
18
    label: 'Cancel',
19
    value: false,
20
  },
21
});
22

23
if (result) {
24
  ctx.notice(`Success! ${result}`);
25
} else {
26
  ctx.alert('Cancelled!');
27
}

These properties provide access to "entity repos", that is, the collection of resources of a particular type that have been loaded by the CMS up to this moment. The entity repos are objects, indexed by the ID of the entity itself.

All the models of the current DatoCMS project, indexed by ID.

View on Github

All the fields currently loaded for the current DatoCMS project, indexed by ID. If some fields you need are not present, use the loadItemTypeFields function to load them.

View on Github

All the fieldsets currently loaded for the current DatoCMS project, indexed by ID. If some fields you need are not present, use the loadItemTypeFieldsets function to load them.

View on Github

All the regular users currently loaded for the current DatoCMS project, indexed by ID. It will always contain the current user. If some users you need are not present, use the loadUsers function to load them.

View on Github

All the SSO users currently loaded for the current DatoCMS project, indexed by ID. It will always contain the current user. If some users you need are not present, use the loadSsoUsers function to load them.

View on Github

These methods let you open the standard DatoCMS dialogs needed to interact with records.

Opens a dialog for creating a new record. It returns a promise resolved with the newly created record or null if the user closes the dialog without creating anything.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const item = await ctx.createNewItem(itemTypeId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for selecting one (or multiple) record(s) from a list of existing records of type itemTypeId. It returns a promise resolved with the selected record(s), or null if the user closes the dialog without choosing any record.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const items = await ctx.selectItem(itemTypeId, { multiple: true });
4

5
if (items) {
6
  ctx.notice(`Success! ${items.map((i) => i.id).join(', ')}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for editing an existing record. It returns a promise resolved with the edited record, or null if the user closes the dialog without persisting any change.

View on Github

1
const itemId = prompt('Please insert a record ID:');
2

3
const item = await ctx.editItem(itemId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

These methods can be used to asyncronously load additional information your plugin needs to work.

Loads all the fields for a specific model (or block). Fields will be returned and will also be available in the the fields property.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const fields = await ctx.loadItemTypeFields(itemTypeId);
4

5
ctx.notice(
6
  `Success! ${fields
7
    .map((field) => field.attributes.api_key)
8
    .join(', ')}`,
9
);

Loads all the fieldsets for a specific model (or block). Fieldsets will be returned and will also be available in the the fieldsets property.

View on Github

1
const itemTypeId = prompt('Please insert a model ID:');
2

3
const fieldsets = await ctx.loadItemTypeFieldsets(itemTypeId);
4

5
ctx.notice(
6
  `Success! ${fieldsets
7
    .map((fieldset) => fieldset.attributes.title)
8
    .join(', ')}`,
9
);

Loads all the fields in the project that are currently using the plugin for one of its manual field extensions.

View on Github

1
const fields = await ctx.loadFieldsUsingPlugin();
2

3
ctx.notice(
4
  `Success! ${fields
5
    .map((field) => field.attributes.api_key)
6
    .join(', ')}`,
7
);

Loads all regular users. Users will be returned and will also be available in the the users property.

View on Github

1
const users = await ctx.loadUsers();
2

3
ctx.notice(`Success! ${users.map((user) => user.id).join(', ')}`);

Loads all SSO users. Users will be returned and will also be available in the the ssoUsers property.

View on Github

1
const users = await ctx.loadSsoUsers();
2

3
ctx.notice(`Success! ${users.map((user) => user.id).join(', ')}`);

These methods can be used to take the user to different pages.

Moves the user to another URL internal to the backend.

View on Github

1
await ctx.navigateTo('/');

Information about the current plugin. Useful to access the plugin's global configuration object.

The current plugin.

View on Github

The current DatoCMS project.

View on Github

The ID of the current environment.

View on Github

The account/organization that is the project owner.

View on Github

UI preferences of the current user (right now, only the preferred locale is available).

View on Github

An object containing the theme colors for the current DatoCMS project.

View on Github

These methods can be used to show UI-consistent toast notifications to the end-user.

Triggers an "error" toast displaying the selected message.

View on Github

1
const message = prompt(
2
  'Please insert a message:',
3
  'This is an alert message!',
4
);
5

6
await ctx.alert(message);

Triggers a "success" toast displaying the selected message.

View on Github

1
const message = prompt(
2
  'Please insert a message:',
3
  'This is a notice message!',
4
);
5

6
await ctx.notice(message);

Triggers a custom toast displaying the selected message (and optionally a CTA).

View on Github

1
const result = await ctx.customToast({
2
  type: 'warning',
3
  message: 'Just a sample warning notification!',
4
  dismissOnPageChange: true,
5
  dismissAfterTimeout: 5000,
6
  cta: {
7
    label: 'Execute call-to-action',
8
    value: 'cta',
9
  },
10
});
11

12
if (result === 'cta') {
13
  ctx.notice(`Clicked CTA!`);
14
}

These methods can be used to update both plugin parameters and manual field extensions configuration.

Updates the plugin parameters.

Always check ctx.currentRole.meta.final_permissions.can_edit_schema before calling this, as the user might not have the permission to perform the operation.

View on Github

1
await ctx.updatePluginParameters({ debugMode: true });
2
await ctx.notice('Plugin parameters successfully updated!');

Performs changes in the appearance of a field. You can install/remove a manual field extension, or tweak their parameters. If multiple changes are passed, they will be applied sequencially.

Always check ctx.currentRole.meta.final_permissions.can_edit_schema before calling this, as the user might not have the permission to perform the operation.

View on Github

1
const fields = await ctx.loadFieldsUsingPlugin();
2

3
if (fields.length === 0) {
4
  ctx.alert('No field is using this plugin as a manual extension!');
5
  return;
6
}
7

8
for (const field of fields) {
9
  const { appearance } = field.attributes;
10
  const operations = [];
11

12
  if (appearance.editor === ctx.plugin.id) {
13
    operations.push({
14
      operation: 'updateEditor',
15
      newParameters: {
16
        ...appearance.parameters,
17
        foo: 'bar',
18
      },
19
    });
20
  }
21

22
  appearance.addons.forEach((addon, i) => {
23
    if (addon.id !== ctx.plugin.id) {
24
      return;
25
    }
26

27
    operations.push({
28
      operation: 'updateAddon',
29
      index: i,
30
      newParameters: { ...addon.parameters, foo: 'bar' },
31
    });
32
  });
33

34
  await ctx.updateFieldAppearance(field.id, operations);
35
  ctx.notice(`Successfully edited field ${field.attributes.api_key}`);
36
}

These methods let you open the standard DatoCMS dialogs needed to interact with Media Area assets.

Opens a dialog for selecting one (or multiple) existing asset(s). It returns a promise resolved with the selected asset(s), or null if the user closes the dialog without selecting any upload.

View on Github

1
const item = await ctx.selectUpload({ multiple: false });
2

3
if (item) {
4
  ctx.notice(`Success! ${item.id}`);
5
} else {
6
  ctx.alert('Closed!');
7
}

Opens a dialog for editing a Media Area asset. It returns a promise resolved with:

The updated asset, if the user persists some changes to the asset itself
null, if the user closes the dialog without persisting any change
An asset structure with an additional deleted property set to true, if the user deletes the asset.

View on Github

1
const uploadId = prompt('Please insert an asset ID:');
2

3
const item = await ctx.editUpload(uploadId);
4

5
if (item) {
6
  ctx.notice(`Success! ${item.id}`);
7
} else {
8
  ctx.alert('Closed!');
9
}

Opens a dialog for editing a "single asset" field structure. It returns a promise resolved with the updated structure, or null if the user closes the dialog without persisting any change.

View on Github

1
const uploadId = prompt('Please insert an asset ID:');
2

3
const result = await ctx.editUploadMetadata({
4
  upload_id: uploadId,
5
  alt: null,
6
  title: null,
7
  custom_data: {},
8
  focal_point: null,
9
});
10

11
if (result) {
12
  ctx.notice(`Success! ${JSON.stringify(result)}`);
13
} else {
14
  ctx.alert('Closed!');
15
}

Plugin SDK > Dropdown actions

Record-Editing actions

Field-Specific Record Actions

Global Record Actions

Asset Management Actions

How to implement a dropdown action

`executeFieldDropdownAction(actionId: string, ctx)`

Return value

Context object

`executeItemFormDropdownAction(actionId: string, ctx)`

Return value

Context object

`executeItemsDropdownAction(actionId: string, items: Item[], ctx)`

Return value

Context object

`executeUploadsDropdownAction(actionId: string, uploads: Upload[], ctx)`

Return value

Context object

`fieldDropdownActions(field: Field, ctx)`

Return value

Context object

`itemFormDropdownActions(itemType: ItemType, ctx)`

Return value

Context object

`itemsDropdownActions(itemType: ItemType, ctx)`

Return value

Context object

`uploadsDropdownActions(ctx)`

Return value

Context object