FreePBX API: Modules

Part of the ApiDocs.

The module system is designed to allow distinct modules to provide specific behaviour and enhancements to FreePBX, allowing users to mix and match specific functionality they want without having to have extra "bloat".

Modules are stored in individual directories inside the webroot/admin/modules directory. They must be 'enabled' in the module administration page in the web GUI after being placed (or downloaded via the GUI) into this directory. This runs install scripts, and records the currently installed version into the database (for upgrade purposes).

Files

module.xml

This file defines the basic module information. See module.xml

functions.inc.php

This file is always included when running any part of freepbx, including generating configuration. This allows modules to optionally include functionality from other modules.

This file contains functions called by various parts of the module to save/add/load the items it creates (eg, in the case of a ringgroup module, it has functions like ringgroup_add() ringgroup_load() etc). These must always be prefixed with the module name followed by an underscore. This avoids conflicts with other modules.

It also contains various other functions:

modulename_destinations()

Returns a 2-dimensional associative array of destinations this module provides, for things like inbound routing, IVR, ring group failover, etc.

This array is as follows:

  return array(
    array(
      'destination' => 'app-blackhole,hangup,1', 
      'description' => 'Hangup',
    ),
    array(
      'destination' => 'app-blackhole,congestion,1', 
      'description' => 'Congestion'
    ),
  );

The 'destination' value must be a valid destination in the dialplan in the form context,extension,priority. The 'description' value is shown in a drop-down list in the destinations box.

modulename_get_config()

This function takes one parameter, $engine, which is the current engine being used. Currently the only engine is 'asterisk' but you should always check for this anyways.

This function should also declare $ext global, which is the extensions object that will become the dialplan. See ApiExtensions for more detailed information about using the extensions API.

Example:

function mymodule_get_config($engine) {
  global $ext;
  switch($engine) {
    case 'asterisk':
      // "blackhole" destinations
      $ext->add('app-blackhole', 'hangup', '', new ext_noop('Blackhole Dest: Hangup'));
      $ext->add('app-blackhole', 'hangup', '', new ext_hangup());

      $ext->add('app-blackhole', 'congestion', '', new ext_noop('Blackhole Dest: Congestion'));
      $ext->add('app-blackhole', 'congestion', '', new ext_answer());
      $ext->add('app-blackhole', 'congestion', '', new ext_playtones('congestion'));
      $ext->add('app-blackhole', 'congestion', '', new ext_congestion());
      $ext->add('app-blackhole', 'congestion', '', new ext_hangup());
    break;
  }
}

install.sql

A straight SQL file that is run (if it exists) during installation and upgrade.

install.php

A PHP script that is run (by being include()'ed) during installation and upgrade.

It is possible for this script to use the database and access other parts of the system. todo: document this more

uninstall.sql

A straight SQL file that is run (if it exists) during uninstallation.

uninstall.php

A PHP script that is run (by being include()'ed) during uninstallation.

page.menitem.php

This is the GUI page that is displayed when the menuitem is loaded. See modules.xml? for more information on menuitem.

NOTE: As of early 2007, we do NOT recommend using guielements, it will be depreciated in the future in favour of QuickForms?. For now, use the regular HTML method. Guielements was never fully finished and has some serious flaws.

There are currently (8/01/2006) two ways to create modules. The old way is to define all the HTML and form processing in the file (for example: freepbx/trunk/amp_conf/htdocs/admin/modules/core/page.routing.php).

The new way is to use the GUI Elements API to define the elements and form processing in functions inside functions.inc.php, and then this page becomes very basic. For an example see freepbx/trunk/amp_conf/htdocs/admin/modules/core/page.users.php and freepbx/trunk/amp_conf/htdocs/admin/modules/core/functions.inc.php.

CSS/JS files

Modules can have CSS and or Javascript files automatically included in the main template. A file named either modulename.css, menuitem.css, modulename.js, or menuitem.js will be included in the <head> section of the main template.

Installing system files

It is possible for a module to include files that go to other areas of the system, such as an agi script.

See ModuleSubdirectories for more information.

Installing/Uninstalling Modules

See ApiModulesSystem?