Creating a Hello World Module

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:

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

Setting Up
 Create a directory named hw in VMOSS's mod directory. 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.

 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;

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 ' '._('Hello World!').' '; 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 { ?> &lt;div id="home"&gt; &lt;?=_("&lt;h2&gt;Welcome to the Hello World Module&lt;BR&gt;Choose an item from the Greetings menu.&lt;/h2&gt;")?&gt; &lt;/div&gt; &lt;br /&gt; &lt;?php }

Exercises
Perform the following exercises on the hw module.  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. 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

 * Forms Processing in VMOSS (Sahana)
 * Adding a Multilingual Hello Form to the Hello World Module