Creating a Hello World Module

[article] [edit page] [discussion] [history]

From Humanitarian-FOSS Project Development Site

One way to extend the functionality of VMOSS (or Sahana) is to create a new, independent module. In this exercise we create the Hello World module. The module will consist of a simple menu structure. It will display the "Hello World" message when its main page is opened and give the user the option to select "hello" greetings from a menu.

Incorporating a new module into VMOSS requires three steps:

  1. Creating a directory for the new module in the mod directory.
  2. Creating main.inc and conf.inc files for the module.
  3. Modifying the database to allow certain users access to the module.


Contents

Setting Up

  1. Create a directory named hw in VMOSS's mod directory.
  2. Copy the main.inc and conf.inc files from the skel directory to your hw directory. The hw directory will now contain the following files:
    main.inc           -- Required main file for the module. Contains shn_hw_default() method.
    conf.inc           -- Required conf file. Adds the hw module to the main menu.
    
  3. Using PhpMyadmin, run the following SQL query by choosing the sql option on the vmoss database.
     INSERT INTO sys_group_to_module (group_id, module, status) VALUES (4, "hw", "enabled");
     INSERT INTO sys_group_to_module (group_id, module, status) VALUES (4, "skel", "enabled");
    

    This will allow any ADMIN user (group_id=4) to access the hw and skel (Skeleton) modules.

Once these three steps are performed, the hw module should appear on the VMOSS main menu once you login as admin.

Creating/Editing the Conf File

The conf.inc file is used to configure your module. It contains any configuration variables that you would like to be accessible for modification by the administrator. For this example, we simply provide a long name for the module ("Hello World") and designate its place in Sahana's main menu (2). Edit conf.inc to contain the following statements. Note the use of the PhpDoc comments.

/**
 * Sets the nice name for this module
 */
$conf['mod_hw_name'] = _("Hello World");

/**
 * Sets the priority order for this module in the main menu
 */
$conf['mod_hw_menuorder'] = 2;

TODO: Edit the conf.inc as illustrated.

Creating/Editing the Main File

The main.inc file receives control whenever the module is selected from the VMOSS menu. It processes all actions performed by the module. It must contain the shn_hw_mainmenu() method, which is used to construct the module's main menu. In this example we create a single main menu ("Home") and a single submenu ("Greetings"), which contains two menu items, "Hello" and "Ciao."

/**
 * This function allows you to override the mainmenu. This is often done
 * to include the modules own menu
 *
 * @access public
 * @return void
 */
function shn_hw_mainmenu()
{
    global $global;
    $module = $global['module'];

    // Create the module menu
    shn_mod_menuopen(_('Hello World'));

    shn_mod_menuitem('default',_('Home'));
    shn_sub_mod_menuopen(_('Greetings'));
    shn_sub_mod_menuitem('hello',_('Hello'));  // Calls the hello() function
    shn_sub_mod_menuitem('ciao',_('Ciao'));    // Calls the ciao() function
    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';

}

As you can see here, the shn_sub_mod_menuitem() takes two parameters. The first is the name of the function to call when that item is selected--e.g., hello()--and the second is the text for the menu item--Hello. Here is sample code for the hello() function.

/**
 * This function is called from the greeting sub menu
 *
 * @access public
 * @return void
 */
function shn_hw_hello()
{
    echo '<center><h1>'._('Hello World!').'</h1></center>';
    shn_hw_default();
}

TO DO: Edit the shn_hw_mainmenu() function as illustrated.

The shn_hw_default() method is called when the hw module is selected from VMOSS's main method. In this example it simply displays a greeting message in HTML code. This function MUST exist. Note the mixing of PHP and HTML code in this example.

/**
 * This function displays the default page of the module when it is selected
 * This function has to exist!
 *
 * @access public
 * @return void
 */
function shn_hw_default()
{
?>
<div id="home">
    <?=_("<h2>Welcome to the Hello World Module<BR>Choose an item from the Greetings menu.</h2>")?>
</div>
<br />
<?php
}



Exercises

Perform the following exercises on the hw module.

  1. Add a menu item under the Home menu named About me that gives your brief bio. You will need to add a function to process this new menu item.
  2. Prettify the default page by incorporating an unnumbered HTML list giving the module's main features.


Solution

Click here to reveal a complete Solution.

Optional Extensions

Personal tools