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:
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 just after the </metadata> tag:
<configurationGroup name='DemoPerson' path='/'> <status>overwrite:true</status> <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 name='fav_animal'> <!-- The data definining the 'fav_animal' field of DemoPerson --> <configuration name='formfield'> <value>STRING_LINE</value> <!-- Set the field to have type 'STRING_LINE' which is a single line of text e.g. an <input type='text'> in a form--> <configuration> <configuration name='headers'> <value>default:Favorite Animal</value> <!-- Set the default header for this field to be 'Favorite Animal'--> </configuration> </configurationGroup> <configurationGroup name='fav_color'> <!-- The data definining the 'fav_color' field of DemoPerson --> <configuration name='formfield'> <value>INT</value> <!-- Set the field to have type INT. We will set this to be a map below--> <configuration> <configuration name='headers'> <value>default:Favorite Color</value> <!-- Set the default header for this field to be 'Favorite Color'--> </configuration> <configurationGroup name="setMap"> <!-- The mapping information used to associate the value of this field with our list of colors--> <configuration name="useMap" type="boolean"> <value>true</value> <!-- Turn the map on--> </configuration> </configurationGroup> </configurationGroup> </configurationGroup> </configurationGroup> </configurationGroup> </configurationGroup>
The tomato colored text are comments which you may leave out if you wish.
Customizing the Template Files
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.
