Adding Fields to the Person Form - 3.1

In this tutorial, we will look at adding a new fields to the person form to version 3.1 of iHRIS Manage. We will add two fields, one called "Favorite Color" which will be a drop-down list of values, and one will be "Favorite Animal" which will be a free-text field. There are many ways to skin my favorite animal, a cat. Likewise, there are many ways to add a field to a form. In order to better maintain the code and the customizations we are making, we will do so by creating a sub-module Demo_ManagePerson of the Demo site-module which contain the all of our changes. To look at a similar customization, look at [CSSC]'s customizations and in particular under modules/Person

Pre-Requisites

Please read over the following articles:

• Technical Overview: Module Structure
• Technical Overview: Configuration (Magic) Data

Directories

We will make our customizations to the iHRIS Manage Demo site. On unix you might be working under:

<Base Dir>

/var/lib/iHRIS

<Site Dir>

/var/lib/iHRIS/3.1/ihris-manages/sites/Demo

If you have installed Windows iHRIS Manage you will be working under the directories:

<Base Dir>

C:\Program Files\ihris-suite

<Site Dir>

C:\Program Files\ihris-suite\sites\ihris-manage

Creating a New Module

The looking a <SITE DIR>/iHRIS-Manage-Demo.xml we see that we can put sub-modules into the subdirectory modules of the site directory, which already exists. So lets do (on unix):

mkdir <SITE DIR>/modules/DemoPerson

which will contains our DemoPerson sub-module. Then save to the file:

<SITE DIR>/modules/DemoPerson/DemoPerson.xml

the following contents:

<?xml version="1.0"?>       
<!DOCTYPE I2CEConfiguration SYSTEM "I2CE_Configuration.dtd">
<I2CEConfiguration name='DemoPerson'>      
 <metadata>
   <displayName>Demo Person</displayName>   
   <category>Form</category>
   <description>Sets up the Demo Person form with extra fields for favorite animals and favorite color</description>
   <version>3.1.0</version> 
   <requirement name='Person'>
     <atLeast version='3.1.4'/>
     <lessThan version='3.2'/>
   </requirement>
   <priority>300</priority>  
 </metadata>
</I2CEConfiguration>

This is (almost) the minimal amount of things we need to do create a new module. Right now, there is no functionality, but we have said that the module DemoPerson requires the module Person, which is incidentally a sub-module of ihris-common. We also set the priority for the module, so that we know that the template files we will create will take precedence over anything in the modules ihris-manage or ihris-common.

Forms and Form Classes and Inheritance

There are really two parts to defining a "form", a form and a form class. The forms are referenced by their shortname, for example person. The second is referenced by the name of a PHP class, for example, iHRIS_Person.

All of the magic data for forms lives under /modules/forms. The magic data to define forms is under /modules/forms/forms and for form classes under /modules/forms/formClasses. For example, the configuration file <BASE DIR>/ihris-common/modules/Person/Person.xml defines the Person module. Here you will see two nodes:

<configrationGroup name='person'>
</configurationGroup>

and

<configrationGroup name='iHRIS_Person'>
</configurationGroup>

The later defines some of the fields associated with the class iHRIS_Person, and the former tells us the class that the person form uses is iHRIS_Person.

Now if we look at the configuration file <BASE DIR>/ihris-manage/iHRIS-Manage-Configuration.xml we will see two things: that ihris-manage requires the module Person, and we will also see a similar <configurationGroup name='person'> node. This time the person form now uses the class iHRIS_ManagePerson. Since ihris-manage requires Person, the class associated to the form person is loaded from iHRIS-Manage-Configuration.xml and not from Person.xml

If we look further in the this file, we will see the <configurationGroup name='iHRIS_ManagePerson'> node which defines the iHRIS_ManagePerson class. Here you will notice two things:

• iHRIS_ManagePerson extends iHRIS_Person, so it has all of the same fields of iHRIS_Person
• iHRIS_ManagePerson adds in the field named password with type 'STRING_PASS' but that this field is not saved to the database

Adding the Fields to Magic Data

We will add the two fields fav_color and fav_animal to the DemoPerson class. Since we wish for fav_color to be a drop-down list, we will also need to create a form called fav_color which will contain the colors we wish. To setup these forms and fields, we are going to have to add in configuration (magic) data. Add to:

<SITE DIR>/modules/DemoPerson/DemoPerson.xml

the following:

<configurationGroup name='DemoPerson' path='/'>
  <configurationGroup name='forms' path='/modules/forms/forms'>
    <configurationGroup name='fav_color'>
       < !-- define the 'fav_color' form -->
       <configuration name='class' values='single'>  
         <value>I2CE_SimpleList</value>
         < !-- fav_color uses the 'I2CE_SimpleList' form defined in i2ce/modules/Forms/modules/Lists-->
       </configuration>
       <configuration name='display' values='single'>         
         <value>Favorite Color</value>  
         < !-- the name of this form that is displayed to a user is 'Favorite Color'-->
       </configuration>
    </configurationGroup>
    <configurationGroup name='person'>
      < !-- the form 'person' is defined in ihris-common/modules/Person/Person.xml. -->
      <configuration name='class'> 
         <value>DemoPerson</value>
         < !-- Here we are changing the form class it uses to be 'DemoPerson' which is defined below -->
      </configuration>
    </configurationGroup>
  </configurationGroup>
  <configurationGroup name='formClasses' path='/modules/forms/formClasses'>
    <configurationGroup name='DemoPerson'>
       < !-- We are defining the DemoPerson class -->
       <configuration name='extends'>
          <value>iHRIS_ManagePerson</value>
           < !-- The DemoPerson class extends the 'iHRIS_ManagePerson' class defined in <BASE DIR>/iHRIS-Manage-Configuration.xml -->
       </configuration>
       <configurationGroup name='fields'>
          < !-- Under here we add in the new fields that DemoPerson has --> 
       </configurationGroup>
    </configurationGroup>
  </configurationGroup>
</configurationGroup>

either leaving out what is in bold (or at least remove the space between < and !-- ).

Enabling the Module

Now that we have everything good to go, we just need to enabled the 'DemoPerson' module in the site. Open up the file:

<SITE DIR>/iHRIS-Manage-Demo.xml

and add in the following:

<requirement name='DemoPerson'> 
 <atLeast version='3.2'>
 <lessThan version='3.3'>
</requirement>

in the <metadata> section after the requirement for ihris-manage.

Happy Debugging