• Triggers
  • Triggers API - defining events in modules
  • Triggers API - triggering events in modules
  • Triggers API - defining actions in modules
  • Triggers API - Acting on actions

Triggers

The triggers module allows you to trigger actions that happen when a specific event and specific conditions occur.

Actions have to be triggered by events. Events provide variables that can be used in conditions.

For example, the page visit action provides the variables [url], [userid] and [roles] referring to the path that was visited, the userid of the user visiting the page and a list of roles they have.

You can use these in the conditons section of the triggers interface by pasting in the token (including the square brackets).

For example, if your condition is [url] is /news the action would only fire if the page /news was visited.

Actions themselves, for example a log action also take parameters. For example a log action would take the log type (error, info...) and the log message. The variables from the event can also be used in this part of the form.

Triggers API - defining events in modules

Registering an event in a custom module is done by calling a simple one line function that defines white name of the event and an array of variables it provides.

For example:

iris.modules.triggers.globals.registerEvent("page_visit", ["url", "userid", "roles"]);

Triggers API - triggering events in modules

To trigger an event within an Iris module, run the Triggers module's triggerEvent function. Passing in the name of the event, the authPass for the user triggering the event and an object containing the variables listed when the event was defined.

  iris.modules.triggers.globals.triggerEvent("page_visit", thisHook.authPass, {
    "url": thisHook.context.req.url,
    "userid": thisHook.authPass.userid,
    "roles": thisHook.authPass.roles.join(",")
  });

Triggers API - defining actions in modules

To define an action you will first need to create a JSON schema for a form (see form system documenation or the JSONform docs). This is the form that will be presented in the triggers user interface. This form is for putting in the parameters that this action takes.

The registration of the log event looks like this:

iris.modules.triggers.globals.registerAction("log", {

  message: {
    "type": "textarea",
    "title": "Message",
    "required": true
  },
  level: {
    "type": "text",
    "title": "Log level",
    "required": true,
    "enum": ["error", "info"]
  }

});

Triggers API - Acting on actions

Once an API action has been registered, if it is successfully triggered a hook fires passing in any parameters that have been passed to the action.

thisHook.context.params stores the parameters of the action.

The log action, for example, looks like this:

iris.modules.actions.registerHook("hook_action_log", 0, function (thisHook, data) {

  iris.log(thisHook.context.params.level, thisHook.context.params.message)

  thisHook.pass(data);

})

As it is an ordinary hook (see the hook system documentation), responses to actions can be chained into multiple actions.