Creating a New Form Field

This tutorial applies to version 4.0 of the iHRIS Suite.

In this tutorial, we will create new form field data type. This form field will be a one line string which is capitalized. The capitalization will be enforced on the server-side as well as the client-side via java-script. We will wrap all of this into a module, CapField so that it can be shared easily.

Creating the Module

In one of your module directories (e.g. your site's modules directory) do the following:

mkdir CapField
mkdir CapField/templates
mkdir CapField/lib
gedit CapField/CapField.xml

and add in the following lines: <source lang='xml'>

<?xml version="1.0"?>       

<!DOCTYPE I2CEConfiguration SYSTEM "I2CE_Configuration.dtd"> <I2CEConfiguration name='CapField'>

 <metadata>
   <displayName>Capitalized Field</displayName>   
   <category>System Component</category>
   <description>Provides an always capitalized field</description>
   <creator>Intrahealth Informatics</creator>
   <email>hris@capacityproject.org</email>
   <version>4.0.0</version> 
   <requirement name='i2ce'>
     <atleast version='4.0'/>
     <lessThan version='4.1'/>
   </requirement>
   <priority>200</priority>
   <path name='classes'>
     <value>./lib</value>
   </path>
   <path name='templates'>
     <value>./templates</value>
   </path>
 </metadata>
 <configurationGroup name='CapField' path='/'>
 </configuratioGroup>

<I2CEConfiguration> </source>

I2CE_FormField_STRING_CAP

We need to create a PHP class to handle the client-side validation of our capitalized field. The field we want has input which is a one line string, so we will subclass the existing one. We do this as follows:

cd CapField/lib
gedit I2CE_FormField_STRING_CAP.php

and add in the following: <source lang='php'>

public class I2CE_FormField_STRING_CAP extends I2CE_FormField_STRING_LINE  {

   /**
    *This is the method to create the input element for the capitalized input string
    * @param DOMNode $node  The node that we wish to add out input element to
    * @param I2CE_Tempalte $template.  The page template object that we are working in
    * @parma DOMNode $form_node  The node from the html template file that requested this form field be displayed
    */
   public function processDOMEditable($node,$template,$form_node) {
       $ele_name = $this->getHTMLName();  //this gets the name of the input element which is used for the GET and POST variables
       $template->addHeaderLink('mootools.js'); //makes sure that the mootools javascript library is avaiable to us
       $element = $template->createElement(  //creates the input element that we will add 
             "input", 
             array( 
                   "name" => $ele_name, 
                   "id" => $ele_name, 
                   "type" => "text", 
                   "onblur"=> "this.setValue(this.getValue().capitalize());"
                   "value" => $this->getDBValue() 
                   ) );
       $this->setElement($element);  //registers the input element that we created
       $node->appendChild( $element);  //add the input element node we just created to the node it needs to be under
   }

} </source>

Here is some more background on the functions.

ProcessDOMEdiable

iHRIS uses version 1.2 of the mootools javascript library. Mootools has a handy capitalization function that we will incorporate into our form field so that on a "blur" event the input element will capitalize.