How to Add Hooks
Contents |
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.
![]() | Note from Retail version 2014Q3 the recommended API has changed, instead of OB.MobileApp.model.hookManager use OB.UTIL.HookManager to access the hook manager |
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.