Design Documentation for the VM Module



We have begun redesigning and refactoring of the entire VM module. The goals of the new design are:

  • To make the module easier to maintain
  • To make the module easier to extend

The functionality of the redesigned module will not change.

The main feature of the new design is to incorporate an object-oriented approach, in which the main entities of the module (such as volunteers, projects, organizations, etc.) will be represented by objects, and in which the database retrieval and manipulation functions of the module will be encapsulated in an object specifically for that purpose. The general architecture of the module will use a variant on the Model-View-Controller architecture.

The main advantage of this new OOD is a more compact and modular codebase with clear separation between various types of code (SQL, HTML, PHP, etc.). Also, with this design, code reuse has been enhanced as similar functions (such as adding a volunteer and editing an existing volunteer's information) have been consolidated into a single function, and we expect similar efficiencies throughout the entire module.

While it is still based on the Sahana module and act-based controller architecture, the new OOD takes advantage of PHP 5.0 features, such as interfaces and abstract methods. It also makes use of the Smarty PHP Template library. We believe that the new design interfaces quite naturally with the basic Sahana design.

In order to encourage and facilitate feedback on our new design, the following resources are available:

We look forward to receiving comments and suggestions on our design. We are currently moving ahead with implementing additional parts of the design.

Architectural Description

The new design for the VM module will use the Model-View-Controller pattern, where the system is split up into three main parts:

  • Model - contains system information
  • View - displays system information
  • Controller - the main processor of the system

The following UML diagram represents the Model-View-Controller design for the 'volunteer' entity in our system. This pattern will be repeated for each of the rest of entities (projects, organizations, and teams).

General UML

As shown in this figure, the Controller serves as an programming interface between the Model and the View. The Controller responds directly to actions taken by the user, and depending on the user's action, the Controller updates or queries the Model and also presents the appropriate View. In our design, the Model consists of the Volunteer object as well as its interface to the database itself (the DAO object). The View consists of code that generates what the user sees, (for example, a list of volunteers, an input form, etc.).

In order to enhance the extensibility of the design, we have defined superclasses and interfaces for the Model, View, and Controller. For example, all entities, such as volunteers or organizations, are represented as subclasses of the DataAccessor class to ensure correct interfacing with the database. Similarly, all of the views presented by different entities are all subclasses of the View class, which serves as a single interface to the Smarty PHP Library. Finally, all controllers implement the Controller interface, which presently consists of only a single controlHandler() function. This will ensure that all control functionality is handled by a single function.

In general, we feel that this design provides the right balance of flexibility and constraint so that the VM Module can be easily extended into new functionality in the future. It also encapsulates functionality in such a way as to simplify maintenance of the module. Below is a description of each of the various components of our MVC design.


The model of the VM module will be comprised of the following classes: Volunteer, Project, Organization, and Team, which will describe a volunteer, a project, an organization, and a team, respectively. Each of these classes will define a single object, and these objects will interact with the DAO (Database Access Object) to fill themselves with the necessary data or make any changes done to them permanent in the database.

The Database Access Object will handle all retrieval and manipulation of database information. Its methods will construct and execute queries based on parameters given to them. So, for example, the getVol() method of the DAO takes a volunteer's p_uuid (a Person's Universally Unique Identifier), constructs the multiple queries to get single volunteer's information using its p_uuid, and returns the information.

The DataAccessor class is a very simple class that stores a reference to the DAO. This way, any class that needs to use the DAO can simply be defined as a subclass of the DataAccessor so that it will then have an attribute that references the DAO.

Advantages: By encapsulating all system information about an entity into a single Model class, we will make it easier to manipulate multiple entities at one time. Additionally, a change in a model class will be reflected in every class that uses it, so updates and bug fixes will be remedied much quicker and will be much easier to manage. Also, by encapsulating all database accessing into a single DAO class, we will centralize all of the SQL code and will ease database code maintenance and modification.


There will be a view class for each Model class. Each view class will contain functions to display the different relevant pages. These functions will use the Smarty PHP Template library. Therefore, the view classes will be:

  • VolunteerView
  • ProjectView
  • OrganizationView
  • TeamView

Each of these view classes will be a subclass of the 'View' class, which will simply construct a Smarty object for later use in each of the view classes.

It is important to note that Smarty requires two writable directories to be created, namely 'cache' and 'templates_c'. However, these directories can simply be created during installation in the '/www/temp/' directory in Sahana.

Advantages: By using the PHP Templates and separating all view-related functions into these classes, this will centralize all HTML code, and therefore clean up the PHP code as well as make it easier to change the display of any page. Additionally, with some small ingenuity, certain display functions can be merged into one, such as the functions to display the form to add a new volunteer or edit an existing volunteer's information.


Just like the view classes, there will be a controller class for each model class:

  • VolunteerController
  • ProjectController
  • OrganizationController
  • TeamController

Each of these classes will be a subclass of its corresponding view class (e.g., VolunteerController will extend VolunteerView), to be able to very simply call the view functions. In addition, each of these classes will implement a 'Controller' interface, which currently has only one function: controlHandler(), which will decide which page to display based on parameters in the URL. Integrating our controller into Sahana should not be difficult.

Sahana's module system has built-in controller-like functionality: When a page is displayed, two parameters, mod and act, are passed in the URL. The mod parameter selects the module, and the act parameter selects the action to perform. Sahana's controller loads the module named mod, and calls the function named shn_[mod]_[act]().

It is important to note that in order to interface with the existing Sahana controller, we have added a third argument to the URL query string. So, instead of 'mod=vm' and 'act=some_function', we now parse the query string as follows: 'mod=vm', 'act=some_entity', and 'vm_action=some_case', where 'some_entity', for example, could be 'volunteer', and 'some_case' could be 'addVolunteer'. Once an act's function is called, that function will call the necessary controller's 'controlHandler()' method, which will take over from there.

At the present time we implement this modification in action control is handled by passing the Sahana menuitem function an action string that has embedded within it the third parameter necessary for our module as shown in bold here:

  shn_mod_menuitem('volunteer&vm_action=addVolunteer', 'Register New Volunteer', $global['module']);

Here is a sample URL that would result from clicking on this menu item:


If the MVC architecture is something that would be more broadly incorporated into Sahana, it may be useful to include a new menuitem function that will handle this third parameter.

Advantages: By separating each controller into a new class, we are centralizing the major processing operations in the system. Once again, since some operations overlap a bit, we can reuse them for more than one function. For example, acting upon a form to create a new volunteer and acting upon a form to edit an existing volunteer's information are very similar operations and can be done in one function.


The following UML diagram gives a detailed break-down of the new design, including the function names and attributes currently implemented in our Demo.

VM design

Overall Advantages

The main advantage of implementing our system in the Model-View-Controller design pattern is organization. Using this architecture, we separate our SQL (DAO) from out System Information (Model) from our HTML (View) from our PHP (Controller). This way, if we wish to change a single part of our system, we will know exactly where to go without having to look through many different files. As a result, our code will be cleaner, and we will also be able to reuse functions we write for similar purposes to cut down on code complexity.