[[PageOutline]] = 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 //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|| '''[wiki:module.xml]''' will describe our module, and define the menu items it provides. '''page.timeconditions.php''' will draw the php page. (see [wiki:page.modulename.php]) '''[#functions.inc.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 install.sql]''' and '''[#uninstall.sql uninstall.sql]''' contain the SQL to create/remove table(s) for this module '''[#install.php install.php]''' and '''[#uninstall.php uninstall.php]''' (not used in this module) can contain a PHP script that is executed upon installation or uninstallation --- == [wiki:install.sql] == This contents of this file will executed on the "asterisk" database when we "install" a module from the web admin. [wiki:ModuleTables 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 ));'' Be sure that the last line of the file has a trailing newline "\n" character after the last SQL command otherwise this file will not be executed properly during module installation and will fail silently. == [wiki:uninstall.sql] == Just drop the table. This will be executed when we "uninstall" this module from the web admin: ''DROP TABLE timeconditions'' Be sure that the last line of the file has a trailing newline "\n" character after the last SQL command otherwise this file will not be executed properly during module uninstallation and will fail silently. == 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 ([http://pear.php.net/manual/en/package.database.db.php 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. == [wiki:module.xml] == Our module.xml is pretty basic for this module: {{{ timeconditions Time Conditions 1.0 setup Basic Time Conditions release/timeconditions-1.0.tgz http://freepbx.org/wiki/TimeConditions }}} 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 [wiki:module.xml] for more information. == 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 [wiki:functions.inc.php] to do things like add, delete, edit, and list time conditions. See [http://svn.sourceforge.net/viewcvs.cgi/amportal/freepbx/branches/2.0/amp_conf/htdocs/admin/modules/timeconditions/page.timeconditions.php?view=markup&rev=1206 page.timeconditions.php] for more information. == [ApiModules#functions.inc.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[[BR]] '''timeconditions_get()''': gets details for the selected time condition[[BR]] '''timeconditions_add()''': adds a new time condition[[BR]] '''timeconditions_del()''': deletes a time condition[[BR]] '''timeconditions_edit()''': edits a time condition As well, we will define: '''timeconditions_destinations()''': provides destinations that other modules can use[[BR]] '''timeconditions_get_config()''': adds to asterisk config files (ie: extensions_additional.conf) Have a look at [http://svn.sourceforge.net/viewcvs.cgi/amportal/freepbx/branches/2.0/amp_conf/htdocs/admin/modules/timeconditions/functions.inc.php?view=markup&rev=1206 timecondition's functions.inc.php] See [ApiModules#functions.inc.php functions.inc.php] for more information. == 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:)