The process of creating a module for FreePBX is, in theory, documented in a number of wiki pages, but these are worse than nothing. Full of outdated information — some of it labeled as such, some of it not — as well as broken links and vague promises of information “to be determined,” this collection of pages does more harm than good. Here, then, are some pointers to get a module working, presented as a list of files you need to have in your module’s directory.
- One of the few well documented pages in the wiki, this determines how the module is displayed within the FreePBX menu structure, as well as information on version, change logs, etc. that will be displayed in the module administration page.
- Any code that needs to be executed when the module is installed should be placed here. This includes database setup; the wiki will tell you that install.sql fulfills this purpose, but it doesn’t. Within this file you have access to the
$dbobject, which is a PEAR::DB object. Note that this file gets executed during upgrades as well. So for example if you add a column to an existing FreePBX database table, make sure to catch any errors that might happen if the column already exists from a previous install.
- Similarly, this file is used to clean up after the module is uninstalled. Again, uninstall.sql is not processed properly so all database cleanup should be in this file.
- This file is necessary if you want to interact with other FreePBX modules; for example, to add a drop-down box while editing an extension. How is this done? During the initialisation stage of the page, before anything is output,
config.phpruns through the list of installed modules and includes all their
functions.inc.phpfiles. It then checks for a function called
modulename_configpageinitand executes it if found.
Within this function you can call
addguifuncto specify a function to be run when the page displays, and
addprocessfuncfor one that is run after the page has been submitted for changes. The simple act of adding a drop-down box to a page requires you to prepare a list of items at the initialisation stage (using
addoptlistitem) and then refer to that list during page output in your GUI function to actually output the drop-down box (using the
gui_selectboxobject.) To save the value, your process function is called, and you are given the chance to do what you like with the POST request.
- This is one of the many things in the wiki marked as “deprecated” with no mention of what replaces it. So I’ve continued to use it for the module’s own page. Unlike other modules’ pages, when you’re creating your own module’s page it is largely included as-is, meaning you can write it like most any PHP page. If you want to do anything “AJAX” in your pages, you’ll need to
exitfrom the page when you return an XML or JSON value; this will prevent FreePBX from tacking it’s own stuff onto the output.