Hook system - CityWebConsultants/Iris GitHub Wiki

• Registering a hook
  • thisHook
    • Finishing a hook call
  • data
• Triggering a hook

Most of the core Iris functionality is based around a system of hooks.

Hooks are chains of events that a module can latch onto and optionally pass/change parameters passed in to it to subsequent hooks in the chain.

Registering a hook

Hooks need to be registered by Iris modules (see the section on creating Iris modules).

Only one instance of the same hook can be registered by a single Iris module using its registerHook function.

Here's an example:

iris.modules.myModule.registerHook("hook_my_hook", 0, function(thisHook, data){

  if(thisHook.context.good === true) {

    thisHook.pass(data);

  } else {

    thisHook.fail(data);

  }

})

The first parameter to registerHook is the name of the hook. The second is the weight/rank of the hook instance (higher weights get called later in the chain), the final parameter is the function that contains the actual hook callback.

This always gets two parameters.

thisHook

The thisHook parameter stores information about the currently called hook, any parameters passed to it by the first triggering of the hook, the user that triggered the initial hook and callbacks for success or fail actions.

• thisHook.context - This stores parameters that are accessible to every hook in the chain. Its contents cannot be changed.
• thisHook.authPass - This is the authPass of the user that called the hook, containing their user id, roles and session information if available.
• thisHook.pass - This is a function that allows a user to finish the current hook instance and pass onto the next one
• thisHook.fail - This is a function that allows a user to finish the current hook instance and abort the rest of the hook chain (ending the initial hook call promise in a fail).

Finishing a hook call

In order for a hook to move along in the chain, each instance must finish or the hook will stall forever. It can either pass or fail. Both pass and fail are triggered through the thisHook.pass or thisHook.fail function.

The parameter to these closing functions is a data object (usually the same or modified data object that the hook instance was passed) to pass to the next hook or the hook's fail function.

For example

data.hello = "world"; // Extend the data object that was passed

thisHook.pass(data);

adds the hello property to the data object and passes that to the next hook in the chain.

data

This is the optional, mutable data object that is passed between hooks in a chain.

Triggering a hook

To trigger a hook, use the (globally available) iris.invokeHook function.

For example

iris.invokeHook("hook_example", req.authPass, constants, variables).then(function(success){

  iris.log("info", success);

}, function(fail){

  iris.log("error", fail)

})

The parameters, in order are:

• The name of the hook
• The authPass of the user calling the hook. You can also pass in the string "root" to run the hook as an admin user or "anon" to run the hook as an anonymous user.
• An context object to pass through to the hook that is available to every hook in the chain.
• Additional variables to pass through the hook (this forms the data parameter for the first hook instance in the chain)

The hook returns a JavaScript promise so you can respond with a different function after the hook chain completes depending on if it passes or fails. This complete function gets the final data object that was passed to the final thisHook.pass or thisHook.fail function in the chain.