Forms Processing in VMOSS (Sahana)

This page describes how to add an HTML form to the Hello World module that we created in the previous exercise.

Overview
HTML forms provide a simple way to input various types of information in a web page. VMOSS (i.e, Sahana) makes using forms even easier by including a form library in PHP that automatically formats HTML form elements according to the style sheets used in Sahana. Therefore, when using Sahana, it is best to use the Sahana form functions rather than your own HTML forms to ensure consistency with the entire system.

The skel module contains a nice form example in its main.inc file. Its shn_skel_form function illustrates how to use many of the form-library functions:

function shn_skel_form {   echo ' '._('Example Form').' ';

shn_form_fopen("form", null,array('req_message'=>true)); shn_form_fsopen("Fieldset One"); shn_form_text("Text Field 0","tf",null,array("req"=>true, "help"=>"testing help")); shn_form_text("Text Field 1","tf2","size='40'"); shn_form_submit("Clear", $submit_opts = null); shn_form_fsclose; shn_form_fsopen("Fieldset Two"); shn_form_button("Button", $button_opts = null, $extra_opts = null); shn_form_hidden(array("h1"=>"hidden value")); shn_form_checkbox("Check Box", "check", $text_opts = null, $extra_opts = null); shn_form_select(array("o1"=>"option1","o2"=>"option2","o3"=>"option3"),"Select", "sel",$select_opts = "", $extra_opts = null); shn_form_radio(array("o1"=>"Option1","o2"=>"Option2","o3"=>"Option3"),"Radio",'op[]',$select_opts = "", $extra_opts = null); shn_form_opt_select('opt_camp_service', "Opt Select", $select_opts = "", $extra_opts = null); shn_form_opt_multi_select('opt_camp_service',"Opt multi Select", $select_opts = "", $extra_opts = null); shn_form_multi_select("ms",array("o1"=>"option1","o2"=>"option2","o3"=>"option3"),"Multi Select", $select_opts = "", $extra_opts = null); shn_form_opt_checkbox('opt_camp_service',$extra_opts=null); shn_form_textarea("Text area", "add", $text_opt, $extra_opts = null); shn_form_upload("Upload File", 'file', $extra_opts = null); shn_form_label("Label", "cap", $extra_opts = null); shn_form_password("Password", "pass", null, $extra_opts = null); shn_form_date("Input Date","dob",$extra_opts = null); shn_form_fsclose; shn_form_submit("Add", $submit_opts = null); shn_form_submit("Delete", $submit_opts = null); shn_form_fclose; }

TODO: To see how the form generated by this function would look, open the Skeleton Module  in VMOSS and choose the Form item under Sub Menu 2.

Including the Form Library
To use the Sahana form library, be sure to include the "lib_form.inc" file:

global $global; require_once $global['approot'].'/inc/lib_form.inc';

Opening and Closing a Form
Opening and closing a form is simple. To open and close a form, use

shn_form_fopen("form-action");

shn_form_fclose;

where form-action is any string that you would like. When the form is submitted, Sahana will automatically call the function shn__ to process the data, where mod-id is the id of your module and form-action is the name you specified above.

Form Sections
All of your form code should therefore go between the shn_form_fopen and shn_form_fclose function calls. You can also create subsections within your form. To open and close subsections, use the following functions:

shn_form_fsopen("name");

shn_form_fsclose;

where name is the name displayed at the top of your subsection.

Form Function Parameters
Many of these functions allow a final optional parameter of $extra_opts. This parameter represents any Sahana-based extra options to add to the form element. If specified, this parameter should be an associative array, and below is a list of some possible key-value pairs for this parameter. Any combination (or none at all) may be specified.

array(   'value' => [specify the value to preset into the element]    'help'  => [specify the text for a help bubble that will be displayed next to the element]    'req'   => [specify "true" to display a required flag next to the element] )

Commonly Used Form Functions
A few of the more useful form functions are described below. For a complete list, consult the shn_skel_form method above or the /inc/lib_form.inc form library.

shn_form_submit($name, $submit_opts)
 * Description: Displays a submit button for the form.
 * Parameters:
 * $name - the text to display on the button
 * $submit_opts - (optional) any extra HTML attribute=value pairs to add in (represent as one string)

shn_form_text($label, $name, $text_opts, $extra_opts)
 * Description: Displays a single line text input.
 * Parameters:
 * $label - the text to display next to the text input
 * $name - the HTML name attribute to assign the input in the form
 * $text_opts - (optional) any extra HTML attribute=value pairs to add in (represent as one string)
 * $extra_opts - (optional) an array of any extra Sahana-specific extra options

shn_form_password($label, $name, $text_opts = null, $extra_opts = null)
 * Description: Displays a single line text input for entering passwords (obscures what is being typed)
 * Parameters:
 * $label - the text to display next to the password input
 * $name - the HTML name attribute to assign the input in the form
 * $text_opts - (optional) any extra HTML attribute=value pairs to add in (represent as one string)
 * $extra_opts - (optional) an array of any extra Sahana-specific extra options

shn_form_select($options, $label, $name, $select_opts, $extra_opts)
 * Description: Displays a drop-down box
 * Parameters:
 * $options - an associative array of options to display, where each key of the array is the HTML value of the option, and each value of the array is the text to display for that option
 * $label - the text to display next to the select box
 * $name - the HTML name attribute to assign the input in the form
 * $select_opts - (optional) any extra HTML attribute=value pairs to add in (represent as one string)
 * $extra_opts - (optional) an array of any extra Sahana-specific extra options. To have a certain option in the select box be automatically selected, include an entry in $extra_opts with key 'value' and make it be the HTML value of the option to preset.

shn_form_checkbox($label, $name, $text_opts, $extra_opts)
 * Description: Displays a checkbox
 * Parameters:
 * $label - the text to display next to the checkbox
 * $name - the HTML name attribute to assign the input in the form
 * $text_opts - (optional) any extra HTML attribute=value pairs to add in (represent as one string)
 * $extra_opts - (optional) an array of any extra Sahana-specific extra options

shn_form_radio($options, $label, $name, $select_opts, $extra_opts)
 * Description: Displays a series of radio buttons
 * Parameters:
 * $options - an associative array of options to display, where each key of the array is the HTML value of the option, and each value of the array is the text to display for that option
 * $label - the text to display next to the series of radio buttons
 * $name - the HTML name attribute to assign each of the radio buttons in the form
 * $select_opts - (optional) any extra HTML attribute=value pairs to add in (represent as one string)
 * $extra_opts - (optional) an array of any extra Sahana-specific extra options. To have a certain option in the select box be automatically selected, include an entry in $extra_opts with key 'value' and make it be the HTML value of the option to preset.

Example
$user_extra_opts = array("req" => true); $pass_extra_opts = array("req" => true,                        "help" => "If you forgot your password, you are in trouble"); $select = array("day" => "1 day", "week" => "1 Week", "forever" => "Forever");

shn_form_fopen("my_action"); shn_form_fsopen("Section 1"); shn_form_text("Username", "user", "", $user_extra_opts); shn_form_password("Password", "pass", "", $pass_extra_opts); shn_form_fsclose; shn_form_fsopen("Section 2"); shn_form_select($select, "Session Length", "sess"); shn_form_fsclose; shn_form_submit("Submit"); shn_form_fclose;

The above code will generate a form looking like this: