The Sahana Code Base

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

Back to outline

Contents 1 Sahana Modules 2 The File Structure of a Sahana Module 3 The conf.inc File 4 The main.inc File 4.1 The mainmenu() Function 4.2 The default() Function

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;

?>
<div id="home">


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

<?php
}

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

Back to outline