BMO Hooks

1 GUI Hooks
- 1.1 Explicitly intercepting the output of a legacy module, and altering it.
- 1.2 Intercepting a GUI Elements page
2 Dialplan Hooks
3 HTTP Hooks (Config Page Inits)
4 Writing Files (from retrieve_conf)
5 General Module Hooks
- 5.1 Setup the Hook Call
- 5.2 Setup the Hook Processor

Hooks can be explicitly requested inside a module by defining static functions:

public static function myGuiHooks() { return array(); }
public static function myDialplanHooks() { return array(); }
public static function myConfigPageInits() { return array(); }

Writing files (as part of retrieve_conf) can be requested by creating the functions

public function genConfig() { return Config; }
public function writeConfig($config) { $this->FreePBX->WriteConfig($config); }

GUI Hooks

See BMO/GuiHooks.class.php

Note that all the hook function must be 'public static function' (except for getConfig/writeConfig, documented further down)

Explicitly intercepting the output of a legacy module, and altering it.

This uses the magic 'INTERCEPT' key, which requests the function 'doGuiIntercept' is called when any of the pages returned are about to be displayed

public static function myGuiHooks() {
    return array("INTERCEPT" => "modules/modulename/pagename.modulename.php");
    // or
    return array("INTERCEPT" => array("modules/modulename/page.moduleame.php", "modules/module2/page.module2.php"));
}
 
public function doGuiIntercept($filename, &$output) {
    if ($filename == "modules/modulename/pagename.modulename.php") {
        $output = "<h2>I just added this to the top of the page</h2>\n".$output;
    } elseif ( $filename == "modules/anothermodule/anotherpagename.php") {
        $output = "This totally replaces the page<br>\n";
    }
}

Intercepting a GUI Elements page

This is just an array of strings returned by myGuiHooks(). Returning 'core' means that your function doGuiHook will be handed the GUI Elements $currentcomponent after if has been processed by the page. Note that if the page you're requesting doesn't use GUI Elements, you'll need to use the INTERCEPT key, above.

This requires a reload to work.

Dialplan Hooks

See BMO/DialplanHooks.class.php

Most modules don't specify a priority, however, to ensure you're run last, you can set your priority to 900 to ensure you're handed a complete $ext object before it is written. You can also return an array:

HTTP Hooks (Config Page Inits)

See BMO/GuiHooks.class.php

Note that the 'owning' page will ALWAYS have its callbacks processed first. There is currently no way to hook in prior to the owning page having access to the $_REQUEST.

Writing Files (from retrieve_conf)

See BMO/FileHooks.class.php

Both genConfig and writeConfig must be defined.

General Module Hooks

Say we created a module called SMS and we want other modules to be able to hook into a certain function from within SMS. The way to do that is as follows.

Setup the Hook Call

In SMS we need to add this function call to the method we want to expose (Usually in <modulename>.class.php, ex: Sms.class.php):

We can pass processHooks any data we want as well:

Process Hooks will then call all modules which have requested to hook into SMS (see below). It will return an array like so:

Setup the Hook Processor

To be able to hook into SMS you need to tell FreePBX about yourself and what you are trying to request. Here is an example from the SIPStation module

First start off by modifying module.xml

Let's break this apart, every hook will have a declaration, you define that with this line:

If the module you are trying to hook into doesn't have a namespace you can omit that, however you can NOT omit class (which is case sensitive)

To add a priority to your call just add a "priority" attribute. If no priority attribute is added the priority will be set at 500

Next we declare who we are and the method we want to hook into ("callingMethod").

namespace: The namespace of this module
class: The class of this module
callingMethod: The method we want to hook into

Finally we add our method name (which is the method that will be called from within SMS), which we have named "smsAdaptor":

In SIPStation we have now added our method:

After all of this is through you'll then need to run retrieve_conf so the caching engine will pickup on your changes.

FreePBX Open Source