orangehrm code overview
TRANSCRIPT
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
Request goes to CentralController.php leavecode=Leave
Identifies that URL belongs to leave module
action=Leave_Type_Edit Identifies section within leave module
http://localhost/lib/controllers/CentralController.php?leavecode=Leave&action=Leave_Type_Edit
Alternative OrangeHRM URI
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
http://localhost/dev/orangehrm/index.php?uniqcode=LAN&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: http://orangehrm.svn.sourceforge.net/svnroot/orangehrm
• Developer wiki:
THE END
1
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.
2
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.
3
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.
4
Typical OrangeHRM URI
Request goes to CentralController.php leavecode=Leave
Identifies that URL belongs to leave module
action=Leave_Type_Edit Identifies section within leave module
http://localhost/lib/controllers/CentralController.php?leavecode=Leave&action=Leave_Type_Edit
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.
5
Alternative OrangeHRM URI
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
http://localhost/dev/orangehrm/index.php?uniqcode=LAN&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.
6
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.
7
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.
8
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.
9
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.
10
CentralController
Passes control to select block for corresponding to module
Creates module (sub) controller object
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.
11
CentralController
Selects Extractor class for action and Parses request parameters using Extractor class
Calls method on module controller, passing extracted data
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.
12
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
We will now look at extractor classes. We will go through the points listed here in detail next.
13
Extractor classes
Located under lib/extractors
Extractor classes are located in subdirectories under lib/extractors directory in OrangeHRM. These sub-directories correspond to different modules.
14
Extractor classes
Extracts request parameters from POST data
Populates model class with the extracted parameters
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.
15
Extractor classes
Has different methods that correspond to different actions in the UI
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 typesparseEditData: Used when editing leaveparseDeleteData: Used when deleting leave types
16
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
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.
17
Module (Sub) Controllers
Located under lib/controllers
Module (sub) controllers are located under the lib/controllers directory.
18
Module (Sub) Controllers
Acts on data received in the request
Redirects user to Original page
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.
19
Module (Sub) Controllers
Displaying HTML UI using template files Uses TemplateMerger class Use model classes to act on the data received
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.
20
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.
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.
21
TemplateMerger
Language constants
Makes special variables available to template (eg $stylesheet)
Includes header and footer templates (if available)
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.
22
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
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.
23
Templates
Located under templates/
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.
24
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
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.
25
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.
We now look at the Model classes in OrangeHRM. Model classes are used by the module controllers.
26
Model classes
Located under lib/models/
Test class is also located in the same directory
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.
27
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.
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.
28
SQLQBuilder
Located under lib/dao/
Contains different methods which constructs SQL Queries based on passed parameters.
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.
29
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.
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.
30
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
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.
31
Language files
Sample language file
This slide contains an extract from a language file. Note the convention used in naming language constants.
32
Configuration
lib/confs/Conf.php lib/confs/sysConf.php lib/confs/mailConf.php hs_hr_config database table.
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.
33
Configuration
lib/confs/Conf.php Written at install time
This slide contains the usual contents of the Conf.php file which is written at install time.
34
Configuration
lib/confs/sysConf.php
Contains settings like date/time format, items per page in lists and stylesheet
Read only, not modified by code
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.
35
Images and CSS files
Located in subdirectories under theme/ directory.
Theme in use available to templates in $stylesheet variable
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.
36
Javascript
Located under scripts/ directory In addition to Orangehrm javascript code,
The Yahoo User Interface Library (YUI) is used.
Javascript files in OrangeHRM are located under the scripts directory. OrangeHRM uses the Yahoo UI library.
37
Resources
• Subversion trunk: http://orangehrm.svn.sourceforge.net/svnroot/orangehrm
• Developer wiki:
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.
38
THE END