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)
Used by index.php to identify current menu

menu_no_top=eim

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: Developer wiki:
http://orangehrm.svn.sourceforge.net/svnroot/orangehrm

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

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)
Used by index.php to identify current menu
5

menu_no_top=eim

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
7

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: Developer wiki:
http://orangehrm.svn.sourceforge.net/svnroot/orangehrm

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