Table of Contents
The module structure is Sahana is built for flexibility and automation with the least amount of technical configuration details. All you effectively need to do to install a module is untar it in the /mod directory and to remove it just delete the directory.
Some recommendations before you start a module
Sahana is a disaster managment system, however the Sahana base can be used for other humanitarian-ICT requirements as well. The recommended approach in designing a new module is as follows:
- Document your requirements and specification for your module in the Sahana “Module Ideas” Forum here.
- Share your requirements at humanitarian-ICT mailing list and get some initial feedback and input from the community. The people on this list consist of emergency management practitioners, humanitarian workers and academics and they can help you refine your requirements a great deal.
- Work with the community to define the rest of your module requirements (optional). We recommend the following.
- vision and scope
- paper prototype of application (i.e. UI screen flows)
- logical schema
- Navigation graph
- The next stage is start developing the module or get some people to work with you to build the module. You should now share this with the sahana-maindev list where all the sahana developers are registered.
- The steps below are an initial guide, but it is not complete. Thus it is essential for you to collaborate on the sahana-maindev list in building your module.
Main Module Files
Here are some conventions that have to be followed for all modules to make them more integrated to the Sahana system and automation that is provided.
- main.inc (required only for sub-application) - This file is the front-controller for the sub-application that you hope to build. Most functionality is directed through this file. This file is not required if the module is a pure admin module.
- conf.inc (required) - Configuration values that a administrator is permitted to change in your module. The configuration values are automatically picked up in the admin section for the administrator to modify and tweak you module.
- admin.inc (optional) - A specific admin function that your module needs to make available to the administrator. Each module can have it's own admin page in the admin panel if this file is included.
- inst/dbcreate.sql (required) - The MySQL database creation script for module installation. This is automatically used by the web installer or the package installer.
- inst/setup.inc (optional) - A setup script beyond the MySQL database creation for module installation. This is automatically used by the web installer or the package installer. The basic version will have the package version and details, whist the advanced form of this script will have installation, upgrade and uninstallation functions
Main Module Skeleton and Convention
As mentioned earlier Sahana dynamic plugin architecture is based on certain naming conventions of files and functions.
To create a skeleton for a new module use the following steps:
1. decide on a name unique to it amongst modules, (lets say myapp)
2. make sure your module's name conforms to these requirements: http://wiki.sahana.lk/doku.php/dev:php_coding_convention#choosing_a_name_for_a_module_in_sahana_module
3. create a directory called myapp in the /mod
mkdir -p mod/myapp
4. Add the following files as required above ration variables
5. Add the default function for main.inc
<?php function shn_myapp_default() { print "<p>Hello World!</p>"; } ?>
main.inc (required)
This is the file that the Sahana framework looks up for an actions and page section overrides.
Module Actions
functions that implement actions have to follow the following convention for them to be automatically picked up by the framework.
shn_<module name>_<action>() { * module name - has to be the same as the directory name of the module - set by the mod POST parameter * action - is the same as the act POST parameter
For example the following POST:
index.php?mod=dvr&act=delp
will call:
shn_dvr_delp() function in /mod/dvr/main.inc file
Page Sections
Page sections provide CSS blocks for things such as the page header, mainmenu and footer. All the default behaviour of this can be overridden by the module to give a completly different layout for the page. The sahana framework checks for the existence of these override functions and passes control to them if they exist without executing the default behaviour. The following convention is used for the section overrides:
shn_<module name>_<section>() {
Right now there are three section overrides possible for header, footer and mainmenu
e.g. shn_dvr_mainmenu()
Creating your own main menu for your module
You can find details on creating your own main menu here
admin.inc
If you require to provide the administrator an interface to configure your module you need to include an admin.inc in your module base directory. The functions in this file are called automatically and included through the Administration Section.
e.g. $SAHANA_APPROOT/mod/mpr/admin.inc
The admin section groups all the modules that have an admin.inc within the modules subsection. All functions in the admin.inc file should be prefixed with shn_<mod dir>_adm and the default function that is called is shn_<mod dir>_adm_default.
For example in organization registry with directory name or:
file: $SAHANA_APPROOT/mod/or/admin.inc admin function prefix: shn_or_adm default admin function: shn_or_adm_default()
conf.inc
The conf.inc file is used for a few purposes. Please do not add you other module specific configurations into this as all conf.inc files included for every HTTP request. The primary use of the conf.inc is to provide a nice name and display order for your module in the main menu. The two variable set for this are $conf['mod_'.<mod>.'_name'] and $conf['mod_'.<mod>.'_menuorder'], where <mod> is the directory of your module.
Typical usage is as follows
<?php $conf['mod_mpr_name'] = _("Missing Person Registry"); $conf['mod_mpr_menuorder'] = 3; ?>
menu order The typical menuorder range is 1-20 where the lowest number get the highest priority in the display. If no value is set then the default value of 10 is used.
module nice name This is the name displayed in the menu. If no nice name is provided you modules base directory name is used
inst/setup.inc
The inst/setup.inc will have some meta-data at the head specifying the classification of the package, as well as installation, upgrade and uninstallation functions.
$package['mod_mpr_version'] = '0.4'; $package['mod_vm_depends'] = array( 'mpr/0.2', 'or', 'gis/0.3-0.4'); $package['mod_vm_conflicts'] = array ( 'vol', 'dvr/0.3-0.5'); function shn_vm_install() {.. function shn_vm_upgrade() {.. function shn_vm_uninstall() { ..
Module Dependencies
Checking Module Dependencies
Now that Sahana modules have become far more integrated, it is important for us to check if modules we are depending on exist before we present a feature in our module. E.g. Inventory management's dependency on the catalog system or providing a link to add camp in the camp registry from the situation mapping module only if the module 'cr' exists.
To that effect use the following function:
shn_module_exists('<module short/dir name>')
which returns true if that module exists in this particular deployment.
the function lives in /inc/lib_modules.inc so it has to be included before you call it.
Module Database Dependencies
As Sahana becomes more integrated you may find yourself referencing and even creating data in tables belonging to other modules. For example adding an item in your module to the gis. Remember that it is your responsibility to clean up after yourself. So remember to use the aproprate Create Modify and Delete interfaces in other modules so as not to leave residual/incorect references lying around in the system.