The Sahana Code Base

This page provides an overview for programmers of the organization of the Sahana source code.

Sahana Modules
Sahana is a modular and extensible system. Different software components, or modules, each reside in their own folder in the mod/ directory. Each module has a short name, which is the name of the module's folder, and is used to refer to the module in code. For example, the Volunteer Management module's short name is vm. Sahana comes with many modules pre-installed. You can see this by looking at the contents of the mod/ folder of a fresh install.

$ ls mod cms   cs   gis    hr    mpr  or    rms   skel  vm admin  cr   dvr    home  ims  msg   pref  rs    sync  vol

The File Structure of a Sahana Module
The skel module is the skeleton module, a simple module that serves as an example and a framework for module developers. It contains code to display a simple message, populate Sahana's menu navigation system, and display an HTML form with various types of inputs. The skeleton module is a good place to start when creating a new module.

Within the skeleton module there are 3 files:

$ ls mod/skel admin.inc  conf.inc   main.inc

When Sahana loads a module, it looks for the main.inc file in the module's folder. The admin.inc and conf.inc files store administration and configuration info about the module. It's not strictly necessary to have these files, but it's a good convention.

The conf.inc File
The conf.inc file is inserts the module into Sahana's main menu: /** * Gives the nice name of the module */ $conf['mod_skel_name'] = _("Skeleton Module");

/** * Gives the priority order in the main menu when listed */ $conf['mod_skel_menuorder'] = 21;

The main.inc File
The bulk of the skeleton module is contained in main.inc. This file contains several functions but the two main functions are:

shn_skel_mainmenu shn_skel_default

The naming convention in Sahana is to name functions with shn_{module name}_{function name}. This is to prevent colliding function names for different modules, as they share the same namespace.

The mainmenu Function
The shn_skel_mainmenu and shn_skel_default functions are special. The mainmenu function is called by Sahana to populate the navigation menu on the left side of the page: function shn_skel_mainmenu {   global $global; $module = $global['module'];

// Create the module menu shn_mod_menuopen(_('Skeleton Module'));

shn_mod_menuitem('default',_('Home')); shn_sub_mod_menuopen(_('Sub Menu')); shn_sub_mod_menuitem('mio',_('Menu Item 1')); shn_sub_mod_menuitem('mit',_('Menu Item 2')); shn_sub_mod_menuclose;

shn_sub_mod_menuopen(_('Sub Menu 2')); shn_mod_menuitem('form',_('Form')); shn_mod_menuitem('report',_('Report')); shn_sub_mod_menuclose;

shn_mod_menuclose;

// include the main menu so that the user can navigate outside the module include $global['approot'].'/inc/handler_mainmenu.inc'; }

The default Function
The default function is the function that gets called when a module is first loaded:

function shn_skel_default {

global $global;

?>

<?= _('Skeleton Module'); ?> <?= _('This is a description of the module that we typically give on the first page with it\' features listed below')?> <?= _('Features include:');?>  <?=_('Give a description of the features')?> <?=_('Feature 2')?> 

<?php }

We will use the examples in the skeleton module to create our own helloworld module.