How to Add Hooks

Contents 1 Overview 2 How to define the hook in the base module 3 How to provide logic in external modules 4 Example 5 Hooks in Web POS

Overview

Hooks provide an easy mechanism to extend functionality from external module. It basically consists on a lightweight mechanism that allows to inject dependencies from third party modules.

There are two roles for hooks:

• Base module that provides the standard functionality and defines some point in its flow that can be extended by external modules
• External modules that provide extra functionality to the base one. Logic for this extra functionality is executed in the point the base module defines for this purpose.

How to define the hook in the base module

Base module needs to define which are the points other modules can extend through hooks. This is done with the following code:

 
  OB.UTIL.HookManager.executeHooks(hookName, args, callback);

When this code is reached, all the hooks defined by external modules for this hookName will be sequentially executed. Finally the callback function will be invoked.

In case there are no external modules providing functionality for this hook, callback function will be directly executed.

The 3 parameters this method accept are:

• hookName: it is a string that identifies the hook. It will be used by external modules to identify the hook they provide logic for. It is recommended this string to start with the base module's DB prefix in order to avoid possible clashes between different base modules providing different hooks.
• args: any object the hooks will receive as parameter, this object is defined by the base module and should be considered as part of the API provided to external modules to implement the hook.
• callback: function to be executed after finishing with all hooks execution.

How to provide logic in external modules

When there is a base module that defines a hook as mentioned in the previous section, external modules can provide logic to be executed at that point in the following manner:

 
OB.UTIL.HookManager.registerHook('BASMOD_HookName', function (args, callbacks) {
  // execute all your logic here
  
  // This is a MUST to properly manage callbacks
  OB.UTIL.HookManager.callbackExecutor(args, callbacks);
});

registerHook function receives 2 parameters:

• Hook name: which is the name that the base module defined for the hook.
• Function to be executed, which is the logic the hook implements. In order to properly manage the chain of other implementations for this same hook and to finally invoke the callback function the base module defines, callbackExecutor method needs to be invoked when the hook logic is done.

Example

This example shows how is code for hooks in both sides, base and external module.

 
// This emulates the code in external modules
OB.UTIL.HookManager.registerHook('test1', function(args, c){
  console.log('  test 1 f1');
  OB.UTIL.HookManager.callbackExecutor(args, c);
});
 
OB.UTIL.HookManager.registerHook('test1', function(args, c){
  console.log('  test 1 f2');
  OB.UTIL.HookManager.callbackExecutor(args, c);
});
 
OB.UTIL.HookManager.registerHook('test2', function(args, c){
  console.log('  test 2 f1', args);
  OB.UTIL.HookManager.callbackExecutor(args, c);
});
 
OB.UTIL.HookManager.registerHook('test2', function(args, c){
  console.log('  test 2 f2', args);
  OB.UTIL.HookManager.callbackExecutor(args, c);
});
 
 
// This is the code that would be in the base module
console.log('start test1 hook');
OB.UTIL.HookManager.executeHooks('test1', null, function(){
  console.log('done test1');
}); // call with callback, no args
 
console.log('\nstart test2 hook');
OB.UTIL.HookManager.executeHooks('test2', 'args'); // call without callback
 
console.log('\nstart test3 hook');
OB.UTIL.HookManager.executeHooks('test3', 'args', function(){
  console.log('done test3');
}); // call without hooks
 
console.log('\nstart test4 hook');
OB.UTIL.HookManager.executeHooks('test4'); //no hooks, no callback
 
console.log('\ndone all');

The output of this example is:

start test1 hook
  test 1 f1
  test 1 f2
done test1

start test2 hook
  test 2 f1 args
  test 2 f2 args

start test3 hook
done test3

start test4 hook

done all

Hooks in Web POS

This document lists the hooks available in Web POS.

Categories: Retail Developers Guide | Mobile Developers Guide