Adding Fields to the Person Form - 3.1

This tutorial applies to version 3.1 of iHRIS Manage. To see this tutorial for different versions of the software see the following:

For other versions, see Adding Fields to the Person Form (versions) .

In this tutorial, we will look at adding a new fields to the person form 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.

Warning: In this tutorial we will be modifying the Demo site of ihris-manage directly. This is not the recommended method for doing this in a production environment. Please read Creating a Site for details on creating a site.

Pre-Requisites

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

• Module Structure
• Configuration (Magic) Data
• Forms and Fields

Directories

You may wish to look at Customizing iHRIS Manage for an overview of some of the directories that are relevant for customizations. 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>
   <path name='templates'>
      <value>./templates</value>
   </path>
   <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' type='delimited' values='many'> 
              <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' type='delimited' values='many'> 
              <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
• Editing 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

Displaying the Favorites

The page titled View Person and referenced in the URL as view is first provided in the Person sub-module of ihris-common. Here, looking at <BASE DIR>/ihris-common/modules/Person/Person.xml we see that the page view loads the default template file view.html which can be found in <BASE DIR>/ihris-common/modules/Person/templates/view.html.

The ihris-manage module overides the view.html by providing it in <BASE DIR>/templates/view.html

Since the view.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) command:

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

To display the favorite animal and color of a person after their nationality, open up the newly created <SITE DIR>/templates/view.html. Find the line:

<span type="form" name="person:nationality" showhead="default" class="even"></span>

and add the following to lines just after it:

<span type="form" name="person:fav_color" showhead="default" ></span>
<span type="form" name="person:fav_animal" showhead="default" class="even"></span>

Editing the Favorites

In the View Person, the first Update This Information link lets us changes the person's basic information such as name and nationality. We will add the fields to change their favorite color and animal to this page. Clicking on the link and looking at the URL, we see that this page is named person.

We start by looking at the Person sub-module of ihris-common to find correct template file to edit. Looking at <BASE DIR>/ihris-common/modules/Person/Person.xml, we see that person page is loads the default html template file form_person.html. This file is found in <BASE DIR>/ihris-common/modules/Person/templates/form_person.html. It is not overidden by ihris-manage.

Since this template file is specific to a person and does not involve any other forms, we will put this in our DemoPerson module. We will create a templates sub-directory and copy this file over to this directory. Here are the (unix) commands:

 mkdir <SITE DIR>/modules/DemoPerson/templates
 cp <BASE DIR>/ihris-common/modules/Person/tempaltes/form_person.html <SITE DIR>/modules/DemoPerson/templates/form_person.html

Now we open the newly created <SITE DIR>/modules/DemoPerson/templates/form_person.html and find the following line:

<span type="form" name="othername" showhead="default"></span>

and add the following:

<span type="form" name="fav_color" showhead="default"></span>
<span type="form" name="fav_animal" showhead="default"></span>

just after it.

Add to 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) command:

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 (Optional)

In the last section, we made use of a task can_edit_database_list. In this section we perform the optional task of addding 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 -->
  </configuration>
</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.1'>
 <lessThan version='3.2'>
</requirement>

in the <metadata> section after the requirement for ihris-manage. Also, ensure you have: <source lang='xml'>

  <path name='modules'>
     <value>./modules</value>
  </path>

</source>

Happy Debugging