ModuleHooks

Modules can add to the GUI and adjust the dialplan logic created by other modules. This is done using ModuleHooks.

Getting Hooked

A module developer has control over where foreign module html is displayed. A $module_hook object is available to all modules, and should be included in their display by calling its hookHtml function.

Putting the following in your module will display any options provided by other modules:

	// implementation of module hook
	echo $module_hook->hookHtml;

Providing Hook Html

Calling the hookHtml method above will not display anything unless another module defines what should be displayed. This is done by creating an appropriately named "hook" function.

This "hook" function should be defined in the functions.inc.php of the module that wants to hook a target module. The return from the function must be html that can be directly displayed in the target module's output.

The name of the "hook" function is very important. It must be called:

hooking-module-name_hook_target-module-name

So, if a module called "myhookmod" is adding to the Inbound Routes (DID) admin, which is part of "core", the function would be named myhookmod_hook_core:

function myhookmod_hook_core($viewing_itemid, $target_menuid) {
   return "hello world!";
}

The arguments $viewing_itemid and $target_menuid will contain the currently viewed item (ie: DID #1234567) and the currently viewed page within the module (ie: "did" - remember that a single module can have more than one page/menu-item). Using these arguments, our "hook" function can intelligently return the proper html options and default values:

function myhookmod_hook_core($viewing_itemid, $target_menuid) {
	switch ($target_menuid) {
                // only provide display for inbound routing
		case 'did':
			//get the current setting for this display (if any)
			$alertinfo = myhookmod_get_currentOption($viewing_itemid);
        	return '
				<tr>
					<td><a href="#" class="info">'._("Alert Info").'<span>'._('ALERT_INFO can be used for distinctive ring with SIP devices.').'</span></a>:</td>
					<td><input type="text" name="alertinfo" size="10" value="'.(($alertinfo) ? $alertinfo : "") .'"></td>
				</tr>
			';
		break;
		default:
			return false;
		break;
	}
}

Processing submits (hookProcess)

In the above example, we added a text input to the core_DID's form. When that form is submitted, we need a way for our hooking module to process the posted data. To do this, we must also define a "hookProcess" function.

Similar to the "hook" function, the "hookProcess" function must be named:

hooking-module-name_hookProcess_target-module-name

Again, if a module called "myhookmod" is adding to the Inbound Routes (DID) admin, which is part of "core", the function would be named myhookmod_hookProcess_core:

function myhookmod_hookProcess_core($viewing_itemid, $request) {
   // store the selection in the DB
   myhookmod_add($viewing_itemid, $request['alertinfo']);
}

The options $viewing_itemid and $request contain the id of the item being modified, and all the available _REQUEST variables.

Generating Dialplan

Most useful modules will probably need to also generate Asterisk dialplan. In the case of ModuleHooks, that dialplan logic probably only makes sense if the priorities exist directly in the target module's context.

The extensions class provides a "splice()" method that allows a module to insert dialplan priorities into that created by another module.

After all the module dialplan is generated, the retrieve_conf? script will look for and execute active modulename_hookGet_config functions. By defining this function for our hooking module, we are able to make use of the "splice()" method.

myhookmod_hookGet_config($engine) {
	global $ext;
	switch($engine) {
		case "asterisk":
			$hooklist = myhookmod_list();
			if(is_array($hooklist)) {
				foreach($hooklist as $item) {
					$thisitem = myhookmod_get(ltrim($item['hook_id']));
					// add dialplan
					$ext->splice('ext-did', $thisitem['itemid'], 1, $ext->add('ext-did', $thisitem['itemid'], '', new ext_setvar("__ALERT_INFO", $thisitem['alertinfo']));
				}
			}
		break;
	}
}

The above function will insert a SetVar? command after the 1st priority for each Inbound Route.