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

It is recommended to read over the following articles and to refer to them as you read through this tutorial:

• Technical Overview: Module Structure
• Technical Overview: Configuration (Magic) Data
• Technical Overview: Forms and Fields

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.

The olive colored text can be removed before release, but it is useful for development purposes. It ensures that any changes that you make to the configuration file will be updated.

Normally, in version 3.1, values from the configuration file are saved into magic data if they do not exist. So, if you make a change to your configuration file, it will not update the magic data, unless the <status>overwrite:true</status> is set. In a production environment (again in version 3.1) you would not need to turn on overwrite as, on initialization, all the magic data in all the modules are loaded together and the default status is to overwrite. This behavior is a bit problematic as it can cause some unexpected results. For this reason, versions 3.2 and above will give you better control over how the magic data is loaded.

Customizing the Template Files

In the previous step, we enabled the two fields to be saved to the database. We now need to edit the user interface to show the fields where appropriate. There are three areas we need to add these fields:

• Displaying a person's record shows their favorite animal and color
• Update a person's record lets you update favorite animal and color
• Add a place in the Administer Database page to and in the allowed colors

Add the the Database Lists

The lists stored in the database are managed though the page titled Administer Database and referenced by lists. We need to add a link to administer the Favorite Color list.

This basic functionality of the list page is provided by I2CE by the Lists sub-module of the Forms sub-module. Here the lists page is handled by the class in <BASE DIR>/I2CE/modules/Forms/modules/Lists/lib/I2CE_PageFormLists, and we we see that a template file lists.html is loaded. The lists.html is a template file which contains all of the database lists that we wish to administer. (Technically, we should have a file <BASE DIR>/I2CE/modules/Forms/modules/Lists/templates/lists.html but we forgot to add it.)

The lists pages is extended in ihris-common through the class at <BASE DIR>/ihris-common/lib/iHRIS_PageFormLists. We also notice there is a template file <BASE DIR>/ihris-common/templates/lists.html that has all the lists provided by ihris-common.

The ihris-manage module overrides the lists.html provided by ihris-common by providing its own at <BASE DIR>/ihris-manage/tempalte/lists.html. You will see that it has all the lists provided by ihris-common as well the new lists provided by ihris-manage. This is the template file we will modify for our site to add it the Favorite Color list.

Since the lists.html file is not specific to the DemoPerson module, it is not appropriate to put our modified version in the DemoPerson sub-moudule. Instead we will put in the templates directory of the Demo site module. Here is the (unix) commands:

cp <BASE DIR>/ihris-manage/templates/lists.html <SITE DIR>/templates/lists.html

Now open the file <SITE DIR>/templates/lists.html and add the following line:

<li task='can_edit_database_list_fav_color' ><a  href="lists?type=fav_color">Favorite Color</a></li>

in the <ul> block under Employee Lists.

You will notice, that we have a task attribute in the <li> tag. A user with the role HR Manager or Administrator can edit any database list. However, for purposes of an example, we will add this task which we can assign to a user with the Training Manager role. This we do in the next section

Setting the Edit Database List Favorite Color Task

In the last section, we made use of a task can_edit_database_list we will need to add this to the configuration data. Insert the following code into <SITE DIR>/modules/DemoPerson/DemoPerson.xml just after the <status>overwrite:true</status> tag:

<configurationGroup name='tasks' path='/I2CE/tasks/task_description'>
   <!-- This node has all of the tasks available to the system and a description of what they are -->
   <configuration name='can_edit_database_list_fav_color'>
      <!-- This is the task that we added to edit the database list associated with the form fav_color
           The class I2CE_PageFormList checks for the existence of "can_edit_database_list_$formname" for editing the list in the action() method-->
      <value>Edit the Favorite Color list</value>
      <!-- The description of the task.  It is displayed in the task/role management page -->
   </configuration>
   <configuration name='can_view_database_list_fav_color'>
      <!-- This is the task that we added to view an existing entry in the database list associated with the form fav_color
           The class I2CE_PageViewList checks for the existence of "can_view_database_list_$formname" for editing the list in the action() method-->
      <value>View the training course status list</value>
      <!-- The description of the task.  It is displayed in the task/role management page -->
   </configuration>
</configurationGroup>
<configurationGroup name='tasks_trickle_down' path='/I2CE/tasks/task_trickle_down/' >
  <!-- This node is used to describes all the sub-tasks that are a specific task has-->
  <configuration name='can_view_database_list_fav_color' values='many'> 
    <!--If we can view the database list for 'fav_color' we want to make sure we have permission to view 
         database lists in general. 
         The 'many' attribute says to treat this like an array of values -->
    <value>can_view_database_lists</value>
  </configuration>
  <configuration name='can_edit_database_list_fav_color' values='many'> 
    <!-- If we can edit the database list 'fav_color' we need to make sure we can view it as well as edit 
         database lists in general.
         The 'many' attribute says to treat this like an array of values -->
    <value>can_view_database_list_fav_color</value>
    <value>can_edit_database_lists</value>
  </configuration>
</configurationGroup>
<configurationGroup name='role_trickle_down' path='/I2CE/tasks/role_trickle_down'>
  <!-- This node is used to describes all the tasks that are assigned to various role -->
  <configuration name='training_manager' values='many'>
     <!-- This node defines the tasks that are assigned to the 'training_manager' role.  
          The 'many' attribute says to treat this like an array of values -->  
     <status>uniquemerge:true</status>
     <!-- We want to merge the existing tasks for the training_manager role to the ones we define below.
          The existing values for 'training_manager' are defined in <BASE DIR>/ihris-common/modules/TrainingCourse/TrainingCourse.xml -->
     <value>can_edit_database_list_fav_color</value>
      <!-- Here we assign the 'can_edit_database_list_fav_color' to the 'training_manager' role -->
   </congurationGroup>
 </configurationGroup>

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