Module Tutorial

This tutorial walks through the creation of a Time Conditions Module for freePBX 2.0

See ApiModules for more information on the modules API.

Directory and Files

Our module directory should be created in /<webroot>/admin/modules, and the structure will be as follows:

timeconditions/	module.xml
	page.timeconditions.php
	functions.inc.php
	install.sql
	uninstall.sql
	install.php
	uninstall.php

module.xml will describe our module, and define the menu items it provides.

page.timeconditions.php will draw the php page. (see page.modulename.php?)

functions.inc.php? will define all the functions needed for page.timeconditions.php It will also define some special functions used for adding dialplan, and for adding destinations for other modules to use (see below)

install.sql? and uninstall.sql? contain the SQL to create/remove table(s) for this module

install.php? and uninstall.php? (not used in this module) can contain a PHP script that is executed upon installation or uninstallation

---

install.sql?

This contents of this file will executed on the "asterisk" database when we "install" a module from the web admin. Module table names? should be the same as the module name. For this module, we'll need the following fields:

• timeconditions_id (a unique id for each record)
• displayname (the name to display for this record)
• time (the time condition)
• truegoto (the goto destination if true)
• falsegoto (the goto destination if false)
• deptname "(the department this belongs to, if any)"

So, our install.sql will contain:

CREATE TABLE IF NOT EXISTS timeconditions ( timeconditions_id INT NOT NULL AUTO_INCREMENT PRIMARY KEY , displayname VARCHAR( 50 ) , time VARCHAR( 100 ) , truegoto VARCHAR( 50 ) , falsegoto VARCHAR( 50 ), deptname VARCHAR( 50 ));

uninstall.sql?

Just drop the table. This will be executed when we "uninstall" this module from the web admin:

DROP TABLE timeconditions

Global variables

In every php file of your module, you can use 3 different global variables (all of them defined in header.php):

• $amp_conf - a hash which contains the configuration of freePBX (an abstraction of /etc/amportal.conf)
• $asterisk_conf - a hash which contains the asterisk configuration (an abstraction of /etc/asterisk/asterisk.conf)
• $astman - a connection to the asterisk manager, or null if there is no connection to the manager (asterisk is down for example).
• $db - a connection to the database (PEAR DB object)

Until version 2.2, some modules made a manager connection in several functions. This leads to a situation in which every page loaded (or every configuration modification) several connections to the manager are opened and closed. Since version 2.2, one single manager connection is opened in header.php.

In version 2.1, the installer added all the asterisk configuration entries to amportal.conf. This behavior is discouraged since 2.2 and is should not be expected by version 2.3. If you need to know something about asterisk configuration please use $asterisk_conf and not $amp_conf.

module.xml

Our module.xml is pretty basic for this module:

<module>
	<rawname>timeconditions</rawname>
	<name>Time Conditions</name>
	<version>1.0</version>
	<type>setup</type>
	<category>Basic</category>
	<menuitems>
		<timeconditions>Time Conditions</timeconditions>
	</menuitems>
	<location>release/timeconditions-1.0.tgz</location>
	<info>http://freepbx.org/wiki/TimeConditions</info>
</module>

The rawname is "timeconditions", because that is what the directory name is. The display name for the module is "Time Conditions".

The menu item id "timeconditions" displays in the admin as "Time Conditions". Note that a module can define more than one menuitem.

type=setup tells FreePBX that this module should appear in the "Setup" page. type=tool would result in the module going in the "Tools" page.

See module.xml for more info.

page.timeconditions.php

This php page writes the display to for the web interface. It will take care of displaying exiting time conditions, creating new ones, as well as deleting and editing.

Forms should use method="POST". We will call functions in functions.inc.php? to do things like add, delete, edit, and list time conditions.

Have a look at page.timeconditions.php

functions.inc.php

Now for the fun part - our functions. This file contains functions we call these from page.timeconditions.php, as well as functions that get called by freePBX to generate dialplan, and to generate destinations that other modules can use.

To keep things organized, function names should always be prefixed with "modulename_".

There are some ((standard function names)) which this module's php page will use:

timeconditions_list(): lists time conditions that are already defined

timeconditions_get(): gets details for the selected time condition
timeconditions_add(): adds a new time condition
timeconditions_del(): deletes a time condition
timeconditions_edit(): deletes a time condition

As well, we will define:

timeconditions_destinations(): provides destinations that other modules can use

timeconditions_get_config(): adds to asterisk config files (ie: extensions_additional.conf)

Have a look at timecondition's functions.inc.php

Installing files into other directories

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

To do this, create a directory inside the module's directory called agi-bin, and put the agi script in there. When the retrieve_conf script is run, it will create a symlink in /var/lib/asterisk/agi-bin pointing to your file. You can put as many files inside as you want.

See ModuleSubdirectories for more information.

The End

Once creating the above files in the "modules" directory, you can use freePBX's Module Admin to install and enable the module. Since this Time Condition module is now written, I'll include it in the core freePBX package (:biggrin:)