Module Structure

What is a Module?

The iHRIS Suite is based on the Intrahealth Informatics Core Engine (I2CE) which use a module structure to encapsulate and maintain "code" into manageable pieces organized by the functionality provided. By "code" we mean the entire collection of php, html, javascript, xml, image files, css, flash, etc that provide the functionality of a web-based application.

A module may require other modules that it needs to run.

A module is versioned to keep track of the changes to functionality and API that a module has.

Why Modules?

• The main reason to use a module system is to increase code manageability. The various components of the iHRIS Suite (Qualify, Manage, and Plan) are used in a variety of settings each requiring their own customizations.

• Each of the iHRIS Suite's components (Qualify, Manage, Plan) share some common functionality and the module system ensures proper code re-use.

• The module system lets many customizations to be encapsulated without having to change the underlying code base. This allow a local developer to make their changes without worrying about about having to redo those changes anytime the core system is updated.

• As modules are organized by the functionality that they provide to the system, a developer can quickly find the relevant code to change by looking at the relevant modules.

• Customizations to the software encapsulated in a module can be easily shared among developers.

The I2CE Module

The is the "top"-most module. Every module implicitly has this a requirement. It is the core module which provides the minimal functionality including magic data, file search, the templating system, and the module factory. It has no requirements.

I2CE provides many optional sub-modules. For example:

• Admin -- Provides a module management system.
• Background Process -- Provides a platform independent means to launch and monitor background processes
• Custom Reports -- Provides the Custom Reporting functionality
• Flash Charts -- provides a php interface to the maani flash charting system
• Forms -- provides the basic form and field structure used by our software
• MooTools -- provides a php interface to the MooTools javascript library
• Tasks and Roles -- provides a task based management system for user roles

The Site Module

The "bottom"-most module is the Site Module. This module is the one that is loaded by the index.php file and tells the system which modules we are used by your system. It is the appropriate place to perform basic customizations to the system, for example changing the image displayed on the login page or to display your organizations name. See for example Tutorial: Customizing iHRIS Manage

Module Configuration File

A module exists by defining its configuration files. There is one top-level node <I2CEConfiguration> under which there are two possible nodes:

• The <metadata> tag is required.
• The <configurationGroup> tag is optional.

The <I2CEConfiguration> tag has a required attribute name whose values should be a unique short name to describe this module such as I2CE, ihris-manage or mercury_javascript_popup. The DTD which describes the format of the configuration file is located in I2CE/lib/I2CE_Configuration.DTD. As an example:

<?xml version="1.0"?>  
<!DOCTYPE I2CEConfiguration SYSTEM "I2CE_Configuration.dtd">
<I2CEConfiguration name='mercury_javascript_popup'>     
  <metadata>
    Some stuff defined below 
  </metadata>
  <condigurationGroup name='mercury_javascript_popup'>
    Some stuff defined below 
  </configurationGroup>
</I2CEConfiguration>

metadata

The DTD has for the <metadata> tag allows the following nodes:

<!ELEMENT metadata (displayName,className?,category?,description?,creator?,email?,link?,
  version,(enable|requirement|conflict|path)*,priority?)>

For the most part, the orders of these tags matter due to limitations in the structure of DTDs. The exceptions is that the <enabled>, <requirement>, <conflict> and <path> tags can be listed in any order amongst themselves.

displayName

This tag is requireed it is human readable name of this module which is displayed, for example, in the Configure Modules pa

Example: <displayName>Popup Box</displayName>

className

The tag is optional and it associates a class for the module. See #The Module Class for specific information about the module's class

Example: <className>I2CE_Module_JavascriptPopup</className>

category

This is an optional tag that is used to group similar modules together by category in the Configure Modules page.

Example: <category>Javascript Library</category>

description

This is an optional tag which gives a description of this module which is displayed in the Configure Modules page.

Example: <description>Provides a javascript popup box</description>

creator

This is an optional tag which shows the creator in the Configure Modules page.

Example: <creator>Freddy Mercury</creator>

link

This is an optional tag which gives a URL for the module in the 'Configure Modules page.

Example: <link>http://en.wikipedia.org/wiki/Freddie_Mercury</link>

version

This is a required tag which you can use to version your module.

Example: <version>1.0.0</version>

requirement

This is an optional tag, of which you can have as many as you want. Each tag needs to have the attribute name whose the value is the name of a module required by this module. This tag can have up to four possible sub-tags:

• atLeast
• atMost
• lessThan
• greaterThan

each of which need to have the attribute version with a value of a version of the module. As an example:

<requirement name='I2CE'>
 <atLeast version='3.1'/>
 </lessThan version='3.2'/>
</requirement>

says that our module requires that I2CE have version at least 3.1 and less than version 3.2.

In order for a module to be loaded, it must successfully meet all of its requirements.

conflict

This is an optional tag of which you can have as many as you wish. This is opposite of the <requirement> tag and lists all the modules that this module conflicts with. As an example:

<conflict name='plant_javascript_popup'>
</conflict>
<conflict name='ringo_javascript_popup'>
  <lessThan version=3.2/>
</conflict>

Says that our module conflicts's with all versions of Robert Plant's javascript popup, but only conflicts with Starr's popup for versions less that 3.2.

A module will fail to load if it conflicts with any other modules that are already loaded.

enable

This tag is optional of which you can have as many as you wish. This tag requires the attribute name with the value the short name of a module. This tag is weaker than the <requirement> tag in that it will try to enable the named module, but it will not cause the cause this module to fail to load if it can't. It also differs from the <requirement> and <conflict> tags as there is no version information (under the subtags atLeast,atMost, lessThan, greaterThan). As an example:

<enable name='alex_patterson_javascript_paginator'/>

Says that if the Alex Patterson's javascript paginator module is able to loaded, then load it. Otherwise don't worry about it.

path

This is an optional tag of which there can be as many as you wish. Each <path> tag requires the attribute name and can have as many sub-tags <value> as you wish. The <path> tag enables a module to specify directories to be added to the file search utility group by category. The categories are specified by the name attribute and some commonly used names are:

• templates These are the directories to search for html template files
• images These are the directories to search for image files
• css These are the directories to search for CSS files
• scripts These are the directories to search for javascript files
• classes These are the directories to search for files containing php classes. The convention here is that MyClass is located in the file MyClass.php
• modules These are the directories to look for (sub-)modules of the current module.

For more information about the paths allowed, see Technical Overview: File Search Paths

priority

This tag is optional. If not set, the priority of a module is 50.

Example: <priority>50</priority>

Here are some standard priorities:

• I2CE 0
• sub-modules of I2CE 50
• ihris-common 100
• sub-modules of ihris-common 150
• ihris-manage, ihris-qualify, ihris-plan 200
• sub-modules ihris-manage, ihris-qualify, ihris-plan 250
• a site module 400

Configuration (Magic) Data

The <configurationGroup> node is optional. If it is present it has to have the attribute name which has the same value as the attribute name in the containing <I2CEConfiguration> tag.

All magic data is relative to the path defined by the this configurationGroup. There are three options:

• The attribute path is not present. In the following example, the magic data is stored under /modules/mercury_javascript_path.

Example:
 <configurationGroup name='mercury_javascript_popup'>
   SOME STUFF GOES HERE
</configurationGroup>

• The attribute path is present. In the following example, the magic data is stored under /some/other/place.

Example:
 <configurationGroup name='mercury_javascript_popup' path='/some/other/place'>
   SOME STUFF GOES HERE
 </configurationGroup> 

• The module is 'I2CE'. The magic data is stored relative to /I2CE

This <configurationGroup> node does double duty. It provides the configuration data that is stored into magic data. It also provides, via the Admin module, a treed menu system to edit the magic data set by this system. This allows for dynamic customizations of your site.

See Technical Overview: Configuration (Magic) Data for more detailed information.