How to create custom scripts in Agility CMS | Agility CMS Docs

Custom Scripts

Custom Scripts allow developers to write logic that will run on certain events within a Content Model or Page Module's input form.

Use Cases

The primary use case for Custom Scripts are to perform custom content validation based on some business logic.

For example, if a user enters a Product SKU value that does not match an actual Product SKU registered in an external system, you can prevent the content from being saved of published.

Only Executed within the Browser

If content is updated outside of the input form UI, these events will not run. If you want some logic to run when ANY content is changed in any environment, consider using Webhooks.

Type of Events

  • onLoad - The hook when the input form is loaded, before the user has interacted with it.
  • onBeforeSave - The hook when the editor has clicked the Save button. You can decide whether to allow the save (onContinue) or prevent the content from being saved (onCancel).
  • onAfterSave - The hook when the input form has been saved. This is an opportunity to notify any external services about a change.
  • onBeforePublish - The hook when the editor has clicked Publish. You can decide whether to allow the publish(onContinue) or prevent the content from being published (onCancel).
  • onAfterPublish - The hook when the content has been published. This is an opportunity to notify any external services about a change.
contentViewModel.CustomEvents = {
  onLoad: function (contentItem) {
    //PERFORM TASKS ON ITEM LOAD
  },
  onBeforeSave: function (contentItem, onContinue, onCancel) {
    //PERFORM TASKS BEFORE SAVE
    //use the onCancel callback function to cancel the save
    onContinue();
  },
  onAfterSave: function (contentItem, onContinue) {
    //PERFORM TASKS AFTER SAVE
    onContinue();
  },
  onBeforePublish: function (contentItem, onContinue, onCancel) {
    //PERFORM TASKS BEFORE PUBLISH
    //use the onCancel callback function to cancel the save
    onContinue();
  },
  onAfterPublish: function (contentItem) {
    //PERFORM TASKS AFTER PUBLISH
  }
};

Parameters

Each event will supply a contentItem parameter which you can use to inspect the values of the content item.

Events which support the cancellation of an event such as onBeforeSave and onBeforePublish will provide onContinue and onCancel callbacks to either continue or cancel the event.

Cancelling an Event

If you want to prevent a save or a publish from completing, you need to invoke the onCancel() function.

You should also provide some sort of feedback to the user of exactly why the event was cancelled. The easiest way to do this is to use the built-in alert() function in JavaScript to alert the user with a useful message.

Using Custom Scripts

Navigate to Models > Content Models or Page Modules and select the model you'd like to add a custom event script to.

Select the ellipsis menu and click Settings.

Using custom scripts in Agility CMS

Next, click the Edit Custom Scripts button. 

You'll be presented with a boilerplate script to help get you started.

Add your code, and when you are ready click Save to apply the changes.