Module Structure

From IHRIS Wiki

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.

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 <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

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

The Module Class

The Site Module

Retrieved from "https://wiki.ihris.org/mediawiki/index.php?title=Module_Structure&oldid=2923"