Introduction to OrangeHRM code

This presentation gives an overview of

OrangeHRM to programmers
 OrangeHRM
 Open Source
 Written in PHP 5
 Uses a MVC architecture
 Uses Javascript and Ajax
 HTML is XHTML 1.0 transitional compliant
 Presentation
 This presentation will cover OrangeHRM's code
base by
 Looking at a typical OrangeHRM Request URI
 Following that request through OrangeHRM code
 Identifying the tasks done by different parts of
OrangeHRM code

 This presentation is based on the current trunk

code (30 December, 2008)
 Typical OrangeHRM URI
http://localhost/lib/controllers/CentralController.php?
leavecode=Leave&action=Leave_Type_Edit

 Request goes to CentralController.php

 leavecode=Leave
 Identifies that URL belongs to leave module

 action=Leave_Type_Edit
 Identifies section within leave module
 Alternative OrangeHRM URI
http://localhost/dev/orangehrm/index.php?
uniqcode=LAN&menu_no_top=eim

 Request goes to index.php

 uniqcode=LAN
 Parameter name can be used to identify module
(uniqcode = admin module)
 Parameter value can be used to identify section
within module (LAN=Languages)
 menu_no_top=eim
 Used by index.php to identify current menu
 Index.php
 Displays Banner and copyright message at
bottom.
 Identifies logged in user's rights and roles
(supervisor, admin etc.)
 Displays menu according to the user's rights
 Passes request to CentralController and
displays CentralController's response in an
<iframe>
 CentralController
 Identifies which module (sub) controller to route
the request to
 Handles authorization
 Passes control to select block for module
 Selects Extractor class for action and Parses
request parameters using Extractor class
 Calls method on module controller, passing
extracted data
 CentralController
 Identifying which module controller to route the
requests to
 CentralController
 Handles authorization based on user rights
and roles
 CentralController
 Passes control to select block for
corresponding to module
 Creates module (sub) controller object
 CentralController
 Selects Extractor class for action and Parses
request parameters using Extractor class
 Calls method on module controller, passing
extracted data
 Extractor classes
 Located under lib/extractors
 Extracts request parameters from POST data
 Populates a model class with the extracted
parameters
 Has different methods that correspond to
different actions in the UI
 Extractor classes
 Located under lib/extractors
 Extractor classes
 Extracts request parameters from POST data
 Populates model class with the extracted parameters
 Extractor classes
 Has different methods that correspond to
different actions in the UI
 Module (Sub) Controllers
 Located under lib/controllers
 Acts on data received in the request
 Add/Update/Delete database objects
 Uses model classes to achieve this
 Redirects user to Original page or displays
HTML UI using template files
 Module (Sub) Controllers
 Located under lib/controllers
 Module (Sub) Controllers

 Acts on data received in

the request
 Redirects user to
Original page
 Module (Sub) Controllers
 Displaying HTML UI using template files
 Uses TemplateMerger class
 Use model classes to act on the data received
 TemplateMerger
 Displays PHP template files
 Provides the following to templates
 Language constants
 Includes header and footer templates (if available)
 Makes variables passed from the controller
available to template
 Makes special variables available to template (eg
$stylesheet)
 Some controllers use the older FormCreator
class which is deprecated.
 TemplateMerger
 Language constants
 Makes special variables available to template (eg $stylesheet)
 Includes header and footer templates (if available)
 Templates
 Located under templates/
 Has the following PHP variables available
 Variables passed by the controller
 Language constants defined in language files
 $stylesheet variable pointing to stylesheet directory
 Can optionally use any other class in OrangeHRM
 header.php and footer.php are included before
and after the template file (by the
TemplateMerger class)
 Template code should be xhtml 1.0 compatible
 Templates
 Located under templates/
 Templates
 Templates have access to
 Variables passed by the
controller

 Language constants defined

in language files

 $stylesheet variable pointing

to stylesheet directory

 Can optionally use any other

class in OrangeHRM
 Model classes
 Located under lib/models/
 Acts as an ORM (object relational mapping)
layer
 Stores & retrieves data from the database
 Uses SQLQBuilder class to construct SQL
queries
 Uses DMLFunctions to get access to database
connections.
 Model classes
 Located under lib/models/
 Test class is also located in the same
directory
 Model classes
Acts as an ORM (object
relational mapping) layer
Stores retrieves data from the
database
Uses SQLQBuilder class to
construct SQL queries
Uses DMLFunctions to access
database connections.
 SQLQBuilder
 Located under lib/dao/
 Contains different methods which constructs SQL Queries based on
passed parameters.
 Database script files
 Located under dbscript/ directory.
 Contains SQL to create tables and insert data
 dbscript-1.sql: Creates tables and adds constraints. Used by
installer
 dbscript-2.sql: Inserts data to tables. Used by installer
 dbscript.sql: Script used to manually create database without
using the installer
 constraints.php: All foreign key constraints should be added
here. Used to check if constraints are set in a given database.
 dbscript-u1.sql: No longer in use.
 dbscript-u2.sql: No longer in use.
 All these scripts (Except those not in use) should be updated when
database changes are done.
 Language files
 Located under language/ directory.
 Contains different subdirectories for different langages
 The lang_xxx_full.php file is the main language file
 All new constants should first be added to the
langauge/default/lang_default_full.php file
 As translations become available, the translated words can be
added to other language files.
 Benefits module has a separate language file:
lang_xxx_benefits.php
 The lang_default_*view.php files are used by the employee list and
lists in Admin, reports and recruitment modules.
 They reuse language constants defined in other files
 Language files
 Sample language file
 Configuration
 lib/confs/Conf.php
 lib/confs/sysConf.php
 lib/confs/mailConf.php
 hs_hr_config database table.
 Configuration
 lib/confs/Conf.php
 Written at install time
 Configuration
 lib/confs/sysConf.php
 Contains settings like
date/time format, items
per page in lists and
stylesheet
 Read only, not
modified by code
 Images and CSS files
 Located in subdirectories under theme/
directory.
 Theme in use available to templates in
$stylesheet variable
 Javascript
 Located under scripts/ directory
 In addition to Orangehrm javascript code,
The Yahoo User Interface Library (YUI) is
used.
 Resources
• Subversion trunk:
http://orangehrm.svn.sourceforge.net/svnroot/orangehrm
• Developer wiki:
THE END
 Introduction to OrangeHRM code

 This presentation gives an overview of

OrangeHRM to programmers

Introduction to OrangeHRM Code

This presentation gives an overview of the OrangeHRM code base to programmers new to
OrangeHRM. It gives information useful to anyone wishing to modify part of OrangeHRM, fix bugs,
add features / modules or plug-ins.

You may want to view this presentation full screen, since it contains code extracts which may not be
visible at lower sizes.
 OrangeHRM
 Open Source
 Written in PHP 5
 Uses a MVC architecture
 Uses Javascript and Ajax
 HTML is XHTML 1.0 transitional compliant

OrangeHRM is an open source program written in PHP 5. You may still see some legacy PHP 4
code in some files, but they will also be converted to PHP 5 eventually.

OrangeHRM has a Model – View – Controller (or MVC) architecture. We will go over the various
parts of this later in the presentation.

In addition to PHP, OrangeHRM uses Javascript extensively in the UI for validation and other tasks.
AJAX is used in some UI's.

HTML UI code in OrangeHRM has to be compliant with the XHTML 1.0 transitional standard.
 Presentation
 This presentation will cover OrangeHRM's code
base by
 Looking at a typical OrangeHRM Request URI
 Following that request through OrangeHRM code
 Identifying the tasks done by different parts of
OrangeHRM code

 This presentation is based on the current trunk

code (30 December, 2008)

In this presentation, we will go through the OrangeHRM code base by looking at a typical URI in
OrangeHRM and following that request as the control passes through different parts of OrangeHRM.
We will also identify the tasks done by the different parts of OrangeHRM with code examples.

This presentation is based on OrangeHRM trunk code as at 30th December, 2008. OrangeHRM has a
short release cycle and undergoes continuous changes. Therefore, some of this information can
become out of date with time.
 Typical OrangeHRM URI
http://localhost/lib/controllers/CentralController.php?
leavecode=Leave&action=Leave_Type_Edit

 Request goes to CentralController.php

 leavecode=Leave
 Identifies that URL belongs to leave module

 action=Leave_Type_Edit
 Identifies section within leave module

Let us now look at a typical OrangeHRM URI. In the URI given in this slide, you will see two
parameters:
Leavecode and action. Also you will note that the request goes to the file CentralController.php

The leavecode= (equals) Leave parameter identifies that this URI belongs to the leave module

The action = (equals) Leave_Type_Edit parameter identifies the section within the leave module, in
this case, editing of leave types.
 Alternative OrangeHRM URI
http://localhost/dev/orangehrm/index.php?
uniqcode=LAN&menu_no_top=eim

 Request goes to index.php

 uniqcode=LAN
 Parameter name can be used to identify module
(uniqcode = admin module)
 Parameter value can be used to identify section
within module (LAN=Languages)
 menu_no_top=eim
 Used by index.php to identify current menu
5

You can see an alternative form of URI in OrangeHRM, usually in the admin module. An example is
given in this slide.

You can see that here, the request goes to index.php and there are two parameters.

The uniqcode=LAN parameter is used to both identify the module and the section within the module.
The parameter name uniqcode identifies that is the admin module. Other modules use different
parameter names. For example, the leave module uses the parameter name leavecode, while the
timemodule uses the parameter timecode.
Have a look at the top of the CentralController.php file for the parameter names used by other
modules. We will see this code in another slide in this presentation.

The second parameter is menu_no_top=eim. It is used to identify the currently selection menu in the
top level drop down menu in OrangeHRM.
 Index.php
 Displays Banner and copyright message at
bottom.
 Identifies logged in user's rights and roles
(supervisor, admin etc.)
 Displays menu according to the user's rights
 Passes request to CentralController and
displays CentralController's response in an
<iframe>

In the previous slide, we saw a request URI that goes to index.php. Here we will look the index.php
file.

Index.php displays the banner at the top and the copyright message. It also identifies the currently
logged in user's rights and roles. User rights show whether the user has view/edit/add/delete rights for
different modules in OrangeHRM. User roles will be something like admin, supervisor or manager.

Then, index.php displays the top level drop down menu according to the user's rights and roles.

Once this is done, the initial request is passed to the CentralController and the response from the
CentralController is displayed in an <iframe>. In fact, all the main content (except for the banner,
copyright message and the drop down menu) is displayed by the CentralController in this <iframe>.

As we saw here, even request URI's which point to index.php are eventually passed to the
CentralController.
 CentralController
 Identifies which module (sub) controller to route
the request to
 Handles authorization
 Passes control to select block for module
 Selects Extractor class for action and Parses
request parameters using Extractor class
 Calls method on module controller, passing
extracted data

We will now go over the responsibilities of the CentralController.

The CentralController:

Identifies which module controller (or sub controller) to route the request to.
Handles Authorization
Then passes control to the select code block for the module.

It then uses an Extractor class to parse the request parameters and calls a method on the module (or
sub) controller, passing the extracted data.

We will go over each of these steps in the next slides.

 CentralController
 Identifying which module controller to route the
requests to

First, we will look at how the central controller identifies which module controller to route the
request to.

You can see in the given code extract, that the central controller looks at a request parameter name to
decide this.
 CentralController
 Handles authorization based on user rights
and roles

Here we look at a code extract which shows how the central controller handles authorization based on
the currently logged in user.
 CentralController
 Passes control to select block for
corresponding to module
 Creates module (sub) controller object

10

In this slide we see a code extract from the CentralController, which shows the select block for a
module and the creation of a module (or sub) controller object.
 CentralController
 Selects Extractor class for action and Parses
request parameters using Extractor class
 Calls method on module controller, passing
extracted data

11

Here we see another code extract, showing how the central controller uses the extractor class and
parses the request parameters and then calls a method on the module controller, passing the extracted
data to it.
 Extractor classes
 Located under lib/extractors
 Extracts request parameters from POST data
 Populates a model class with the extracted
parameters
 Has different methods that correspond to
different actions in the UI

12

We will now look at extractor classes. We will go through the points listed here in detail next.
 Extractor classes
 Located under lib/extractors

13

Extractor classes are located in subdirectories under lib/extractors directory in OrangeHRM. These
sub-directories correspond to different modules.
 Extractor classes
 Extracts request parameters from POST data
 Populates model class with the extracted parameters

14

Extractor classes extract request parameters from POST data and then populate model classes with
the extracted parameters.

In the code snippets shown here, you can see an example, where the CentralController calls the
parseEditData method in the LeaveType extractor, and the actual implementation of that method.
 Extractor classes
 Has different methods that correspond to
different actions in the UI

15

Extractor classes have different methods that

correspond to different actions in the UI.

For example, the leave type extractor has the following

methods:

parseLeaveType: Used when defining new leave types

parseEditData: Used when editing leave
parseDeleteData: Used when deleting leave types
 Module (Sub) Controllers
 Located under lib/controllers
 Acts on data received in the request
 Add/Update/Delete database objects
 Uses model classes to achieve this
 Redirects user to Original page or displays
HTML UI using template files

16

We will now look at module controllers (or sub controllers). We will go through the items listed here
in detail in the next few slides.
 Module (Sub) Controllers
 Located under lib/controllers

17

Module (sub) controllers are located under the lib/controllers directory.

 Module (Sub) Controllers

 Acts on data received in

the request
 Redirects user to
Original page

18

Module controllers act on data received in the request and then

redirect the user to the original page as shown in this code example, or
displays another page using template files and the TemplateMerger class as
we show in the next slide.
 Module (Sub) Controllers
 Displaying HTML UI using template files
 Uses TemplateMerger class
 Use model classes to act on the data received

19

In this slide we see a sub controller method that displays a UI using the TemplateMerger class.
You can see how the controller uses the LeaveType model class to access data prior to displaying the
UI.
 TemplateMerger
 Displays PHP template files
 Provides the following to templates
 Language constants
 Includes header and footer templates (if available)
 Makes variables passed from the controller
available to template
 Makes special variables available to template (eg
$stylesheet)
 Some controllers use the older FormCreator
class which is deprecated.
20

We will now look at the TemplateMerger class. The template merger class is used to display PHP
template files. It provides language contants, includes header and footer templates if they are
available and makes variables passed from the controller available to the template.

Some controllers use the alternate class FormCreator, which is similar to TemplateMerger, but the
FormCreator is deprecated and should not be used for in code.
 TemplateMerger
 Language constants
 Makes special variables available to template (eg $stylesheet)
 Includes header and footer templates (if available)

21

Here we look at a code extract from the TemplateMerger's display() method showing how language
constants are made available, the header and footer files are included and the stylesheet variable is
set.
 Templates
 Located under templates/
 Has the following PHP variables available
 Variables passed by the controller
 Language constants defined in language files
 $stylesheet variable pointing to stylesheet directory
 Can optionally use any other class in OrangeHRM
 header.php and footer.php are included before
and after the template file (by the
TemplateMerger class)
 Template code should be xhtml 1.0 compatible 22

We will now look at templates in OrangeHRM.. As mentioned before, template code should be xhtml
1.0 transitional compatible.

The special header.php and footer.php are included before and after the template file by the Template
Merger file.
 Templates
 Located under templates/

23

Template files are located under the templates directory, under subdirectories corresponding to each
module as can be seen here. You can also see the header and footer php files.
 Templates
 Templates have access to
 Variables passed by the
controller

 Language constants defined

in language files

 $stylesheet variable pointing

to stylesheet directory

 Can optionally use any other

class in OrangeHRM

24

Templates have access to PHP variables passed by the controller, language constants defined in
language files, the stylesheet variable which points to the stylesheet directory.

You can also use any other class in OrangeHRM in a template file. But it is recommended to not do
this unless necessary, since template files should be kept simple.
 Model classes
 Located under lib/models/
 Acts as an ORM (object relational mapping)
layer
 Stores & retrieves data from the database
 Uses SQLQBuilder class to construct SQL
queries
 Uses DMLFunctions to get access to database
connections.

25

We now look at the Model classes in OrangeHRM. Model classes are used by the module controllers.
 Model classes
 Located under lib/models/
 Test class is also located in the same
directory

26

Model classes are located under lib/models in sub directories corresponding to the module. Unit test
classes for the Model are also located in the same directory as the model classes.
 Model classes
Acts as an ORM (object
relational mapping) layer
Stores retrieves data from the
database
Uses SQLQBuilder class to
construct SQL queries
Uses DMLFunctions to access
database connections.

27

The code example here shows how model classes:

Act as an Object Relational Mapping (or ORM) layer.

Stores and retrieves data from the database

Uses the SQLQBuilder class to construct SQL Queries.

And

Uses DMLFunctions to access database connections.

 SQLQBuilder
 Located under lib/dao/
 Contains different methods which constructs SQL Queries based on
passed parameters.

28

The SQLQBuilder class is used by model classes to construct SQL Queries. It is located under the lib/
dao directory and contain many methods which construct SQL queries based on the passed
parameters.

Examples of the kind of methods available in SQLQBuilder are given in the code extract here.
 Database script files
 Located under dbscript/ directory.
 Contains SQL to create tables and insert data
 dbscript-1.sql: Creates tables and adds constraints. Used by
installer
 dbscript-2.sql: Inserts data to tables. Used by installer
 dbscript.sql: Script used to manually create database without
using the installer
 constraints.php: All foreign key constraints should be added
here. Used to check if constraints are set in a given database.
 dbscript-u1.sql: No longer in use.
 dbscript-u2.sql: No longer in use.
 All these scripts (Except those not in use) should be updated when
database changes are done.

29

OrangeHRM also contains database script files, containing SQL used to create database tables and
insert data used by OrangeHRM. These are located under the dbscript directory.

This directory contains 6 files, each of these are described here. All these scripts (except the ones not
in use) should be updated when database changes are done.
 Language files
 Located under language/ directory.
 Contains different subdirectories for different langages
 The lang_xxx_full.php file is the main language file
 All new constants should first be added to the
langauge/default/lang_default_full.php file
 As translations become available, the translated words can be
added to other language files.
 Benefits module has a separate language file:
lang_xxx_benefits.php
 The lang_default_*view.php files are used by the employee list and
lists in Admin, reports and recruitment modules.
 They reuse language constants defined in other files

30

Internationalization in OrangeHRM is handled by language files located under the language directory,
in sub directories corresponding to the language.

The lang full php file is the main language file.

All new constants should be first added to the lang_default_full.php file.
As translations are available, constants can be added to other language files. The benefits module has
a separate language file called lang benefits.php.

The lang view php files are used by the employee list and lists in admin, reports and recruitment
modules. They reuse language constants defined in other files.
 Language files
 Sample language file

31

This slide contains an extract from a language file. Note the convention used in naming language
constants.
 Configuration
 lib/confs/Conf.php
 lib/confs/sysConf.php
 lib/confs/mailConf.php
 hs_hr_config database table.

32

We will now look at how configuration is handled in OrangeHRM. Configuration is stored in

conf.php, sysconf.php and mailconf.php. Some configuration is stored in a database table named
hs_hr_config and accessed by a class named Config.php located in the lib/common directory.
 Configuration
 lib/confs/Conf.php
 Written at install time

33

This slide contains the usual contents of the Conf.php file which is written at install time.
 Configuration
 lib/confs/sysConf.php
 Contains settings like
date/time format, items
per page in lists and
stylesheet
 Read only, not
modified by code

34

Here we have an extract from the sysConf.php file which contains settings like date/time format,
items per page in lists. This file is read only and is not modified by code.
 Images and CSS files
 Located in subdirectories under theme/
directory.
 Theme in use available to templates in
$stylesheet variable

35

Image and CSS files are located under a subdirectory under the theme directory. The subdirectory
name is available to use in templates in the stylesheet variable. Using this, it is possible to have
multiple style directories. To change between stylesheets, the stylesheet variable in sysConf.php has
to be changed.
 Javascript
 Located under scripts/ directory
 In addition to Orangehrm javascript code,
The Yahoo User Interface Library (YUI) is
used.

36

Javascript files in OrangeHRM are located under the scripts directory. OrangeHRM uses the Yahoo
UI library.
 Resources
• Subversion trunk:
http://orangehrm.svn.sourceforge.net/svnroot/orangehrm
• Developer wiki:

37

We have covered most of the code in OrangeHRM very briefly in this presentation. More details can
be obtained by going through the OrangeHRM code and the developer wiki.
THE END

38