Creating HTML Forms in Sahana

The Sahana source code comes with a library that is useful for creating HTML form elements. However, the library is not extensively documented. This document tries to provide a bit of guidance on how to use the library functions.

Setting Up
The example described here can be [[Media:Helloworld.tar|downloaded]]. We will create a simple Hello World module. Thus, we will create a directory named hw in Sahana's mod directory. The hw directory will 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. say_hello.inc     -- Creates the HTML form process_hello.inc -- Process the HTML form POST query. lib_vr.inc        -- A library containing local (Trinity) form-processing functions

The conf.inc file contains the following statements, which add the hw module to the main menu. The module's menu item is named Hello World

$conf['mod_hw_name'] = _("Hello World"); $conf['mod_hw_menuorder'] = 2;

The main.inc file contains two key methods, shn_hw_mainmenu, and shn_hw_default. The first method is used to construct the module's main menu. In this case we are adding a single menu item titled Say Hello. This is the menu item that will bring up the form by invoking the say_hello method. The menu entry associates the menu item with that method:

function shn_hw_mainmenu {   global $global; $module = $global['module']; shn_mod_menuopen(_lc("Hello World"));                   // Create the module menue shn_mod_menuitem("say_hello","Say Hello"); shn_mod_menuclose; include $global['approot']."/inc/handler_mainmenu.inc"; // Include the main menu }

The other method is the default method that is called when the hello world module is selected of Sahana's main method. It simply displays a message in HTML code:

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 Hello World menu.&lt;/h2&gt;")?&gt; &lt;/div&gt; &lt;br /&gt; &lt;?php }

Libraries To Include
Since you will be using library functions for this task, you need to include the correct libraries. Here are the libraries that are used in this example. These include statements should be placed at the beginning of your main file.

global $global; include_once $global['approot']."/inc/lib_form.inc";      // Include the forms library include_once $global['approot']."/inc/lib_menu.inc";      // Needed for the HW menu. include_once $global['approot']."/inc/lib_validate.inc";  // Needed to validate menu items. include_once ("lib_vr.inc");           // Local Library: Contains the _shn_form_select_gender function include_once ("say_hello.inc");        // Contains the code for the form. include_once ("process_hello.inc");    // Contains the method to process the form.

Coding the Form
For our example, all of the code that creates the HTML form is contained in the shn_hw_say_hello method in the say_hello.inc</tt> file:

function shn_hw_say_hello {

?> &lt;center&gt;&lt;h2&gt;&lt;?=_("Hello Form - Give me your name and I'll say hello")?&gt; &lt;/h2&gt; &lt;h2&gt;&lt?;=_("When you are finished, click \"Submit\".")?&gt; &lt;/h2&gt;&lt;/center&gt;&lt;BR&gt; &lt;div id="formcontainer"&gt; &lt;?php shn_form_fopen("process_hello");                                  // Open the Form shn_form_fsopen('Get the Name');                                  // The group of fields get's the user's name $extra_opts['req']=true;                                          // The name is a required field shn_form_text(_("Your name : "),'name','size="50"',$extra_opts);  // Create a text field element shn_form_date(_("Date of Birth : "),'dob', $initdate=NULL);       // Create a date element echo "&lt;br&gt;"; _shn_form_select_gender($error,NULL);                             // Create a gender drop-down menu (Trinity library) echo "&lt;br&gt;"; shn_form_fsclose;                                               // Close this group of elements ?&gt; &lt;br /&gt; &lt;center&gt; &lt;?php shn_form_submit("Submit");                      // Create the submit button ?&gt; &lt;/center&gt; &lt;br /&gt; &lt;?php shn_form_fclose;                              // Close the form ?> &lt;/div&gt; &lt;?php } // say_hello

As you can see, the form is created by a mixture of PHP and HTML code. Creating HTML elements, such as text fields, date fields, is done by calling functions such as shn_form_date</tt> that are available in the Sahana library or the Trinity library. These are described below.

One important point is that the call to the shn_form_open</tt> function, must pass it the name of the function that will process the form data. In this case, the name of the function that handles the data is process_hello</tt>.

Another important point is that you must remember the symbolic names that you give the various form elements. For example, the textfield in this example is given the name name because it inputs the user's name. This symbolic name will be used to retrieve the form data.

Processing Form Data
Sahana form data is processed as a POST query. This means that the data is stored by the server in a variable named $_POST. This variable is an associative array whose elements are indexed by the names of the various HTML elements. For example, if the textfield in your form is named name, you would retrieve the value from that textfield with the expression $_POST['name']</tt>.

Here's the process_hello</tt> function (from the process_hello</tt> file:

function shn_hw_process_hello {

global $global; //   include_once $global['approot']."/mod/vr/utility_functions.inc";   // Local Library: Contains dbgpost //   dbgpost($_POST);                                                   // Uncomment to display post values

$name = $_POST['name']; if (!shn_validate_field($name, 'Name', $max_len=30, $check_null=true)){ // If name is null $error=true; }   $gender = $_POST['opt_gender']; $gender_str = "male"; if ($gender != "mal") { $gender_str = "female"; }

$dob_entered = $_POST['dobY']. $_POST['dobM']. $_POST['dobD']; if (!shn_valid_date($dob_entered, $check_null=false, $pattern='/^\d{4}\d{2}\d{2}$/')){ // If date is invalid $error=true; add_error(SHN_ERR_DOB_INCORRECT); } else if (shn_is_null($dob_entered)) {       // If date is null $dob_formatted = "unknown"; } else { $dob_formatted = $_POST['dobM']. "-" . $_POST['dobD']. "-" . $_POST['dobY']; // Format the date }

if ($error) { display_errors; $hellostring = "Sorry. Please try again."; } else { $hellostring = "Hello ". $name. ". &lt;BR&gt;You are a ". $gender_str. " and your birthday is ". $dob_formatted; } ?&gt; &lt;div id="hello"&gt; &lt;?=_("&lt;center&gt;&lt;h2&gt; $hellostring &lt;/h2&gt;&lt;/center&gt;")?&gt; &lt;/div&gt; &lt;br /&gt; &lt;?php } // process_hello

As you can see, in the case of the date field, Sahana contains library functions that can be used to validate form input data. For example, in this example, we are validating that the name field is not null and that the date is properly formatted.

Forms Function Library
The Sahana library for building forms is the lib_forms.inc</tt>, which is stored in the inc</tt> directory. Here is a list of the functions and a brief description.

Additional Form Functions
We have created some additional form elements that are contained in the vr</tt> module in the file vr_lib.inc</tt>. These functions all require access to the Sahana database in order to initialize drop-down menus.

To use these functions you must include the vr/vr_lib.inc</tt> file.