Location: PHPKode > projects > Volunteer Management OpenSource Software > vmoss_alpha02/README.txt
11 Feb 2008

VMOSS - ReadMe
===============

VMOSS (Volunteer Management Open Source Software) is a standalone volunteer management system, providing volunteer 
and project registration, monitoring, and reporting functionality. It is powered by the Sahana Disaster Management 
System.

Sahana is a free and open source Disaster Management System.It mainly facilitates management of Missing people,
disaster victims, Managing and administrating various organisations, managing camps and managing requests and 
assistance in the proper distribution of resources.

----------------------
http://sourceforge.net/projects/vmoss
http://www.sahana.lk/

Copyright (C) 2005 Lanka Software Foundation [http://www.opensource.lk/]
Copyright (C) 2008 The Humanitarian FOSS hide@address.com [http://www.cs.trincoll.edu/hfoss]

This software is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this software; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA


        
Download and Install:

    Please see the INSTALL file.

Extension:

    VMOSS can be extended in two ways:
    
    1) Add a module to VMOSS.
        Modules are directories in the "mod" directory under the VMOSS root directory. Modules have their
        own menus and should be used to carry out functionality that deviates from the main Volunteer
        Management functionality.
        
        To create module in VMOSS is exactly the same as creating a module in Sahana. For more information,
        see http://wiki.sahana.lk/doku.php?id=dev:module_convention
        
    2) Extend the functionality in the "vm" module.
        All Volunteer Management functionality is carried out within the "vm" module, which is based on a
        Model-View-Controller design. All major entities in the "vm" module have a model, view, and controller
        associated with them. In order to add a new entity to the "vm" module, follow the steps below:
        (To display naming conventions, the directions below add a Widget entity)
        
        I. Make the VM Access Control Recognize Your New Entity.
            Each page in the VM has distinct 'act' and 'vm_action' URL parameters. The VM uses the 'act' parameter
            to decide which controller to use, and the 'vm_action' is used by a controller to decide what action
            to carry out.
            
            For each page that you add to the VM, you must insert into the 'vm_access_request' database table
            an entry describing your new page. For your first entry, the 'act' should be your controller's
            name, and the 'vm_action' should be 'default'. 
            
            So, you should execute the following query on the database:
            ----------------------------------------------------
                INSERT INTO vm_access_request (request_id, act, vm_action, description) 
                VALUES (201, 'widget', 'default', 'Display Widget - Default');
            ----------------------------------------------------
            
            You can then give groups of users access to it by inserting into the 'vm_access_request_role' table, 
            which links user roles to pages:
            ----------------------------------------------------
                INSERT INTO vm_access_request_role (fk_access_request, fk_role) VALUES
                (201, 0),
                (201, 1),
                (201, 2),
                (201, 3),
                (201, 4);
            ----------------------------------------------------
            The above query will give access to all user groups to the above default page.
            
            To make these database changes happen automatically upon installation of VMOSS, you must add them to the
            'inst/dbcreate.sql' database script under the 'vm' module.
            
        II. Create a Model.
            A model class contains the state of one entity. So, a Widget model would simply store and retrive information
            about a widget. Each model class should extend the Model class:
            
            ----------------------------------------------------
            <?php
            class Widget extends Model {
                public $createdDate;
                
                function __construct() {
                    Model::Model();
                    $this->createdDate = $this->dao->getCurrentDatetime();
                }
            }
            ?>
            ----------------------------------------------------
            
            Put this class definition in a file called 'Widget.php' in the 'model' directory under the 'vm' module directory.
            
            It is important to note that all model classes, since they extend the Model class, have a
            reference to the Data Access Object (DAO, in 'model/dao.php'), which is where all queries to the datbase 
            are stored and executed. No SQL code should leave the DAO. DAO functions typically execute a query on the 
            database and return its results in some type of data structure.
            
            In the Widget model above, a Widget stores its creation date by asking the DAO to retrieve the current date
            and time from the database. The getCurrentDatetime() function is not yet defined in the DAO, we must
            modify the 'model/dao.php' file to add this function to the DAO class:
            
            ----------------------------------------------------
            ...
            function getCurrentDatetime() {
                $result = $this->execute("SELECT NOW()");
                return $result->fields[0];
            }
            ...
            ----------------------------------------------------
            
            The DAO uses the ADODB Database Abstraction Library, so the execute() function in the DAO is actually a 
            wrapper around the ADODB execute() function on a database connection. (See http://adodb.sourceforge.net/
            for more information).
            
            Since each model class extends the Model class, it has access to the DAO via the $this->dao variable.
            
       III. Create a View.
            All views extend the general View class. Following the Widget example, we would create a file in
            the 'view' directory under the 'vm' module directory called "WidgetView.php". A skeleton WidgetView 
            would look like this:
            ----------------------------------------------------
            <?php
                class WidgetView extends View {}
            ?>
            ----------------------------------------------------
            
            The view classes should have functions that display information. The VM uses a templating engine, which
            is accessed from a view class by the $this->engine variable. You may assign information to the engine,
            and then choose to display a template. The template will be passed the information that is assigned to
            the engine.
            
            So, for example, we could add a function to our WidgetView class to display a Widget model:
            
            ----------------------------------------------------
            ...
            function displayWidget($model) {
                $this->engine->assign('createdDate', $model->createdDate);
                $this->engine->display('widget/default.tpl');
            }
            ...
            ----------------------------------------------------
            
            In order for this to work, we must create a template for our page, which is described in the step below:
            
        IV. Create a Template.
            Templates should include only presentation logic, not business logic. This includes any HTML, CSS, JavaScript,
            or other type of code that the browser will see. What should not go in templates is lots of PHP computations
            and processing. 
           
            This separation of presentation and business logic increases maintainability of the
            code and facilitates change. Following the Widget example, we need to create a directory in the 'templates'
            directory called 'widget' and create template in it called 'default.tpl', which is displayed in our 
            displayWidget() function from the WidgetView.
            
            For this file, we could simply have the following code:
            
            ----------------------------------------------------
            <h2>Welcome to the Widget Display Page</h2>
            A new widget was created on: {$createdDate}
            ----------------------------------------------------
        
            Since we assigned 'createdDate' to be $model->createdDate in our WidgetView code, when we call displayWidget() 
            passing it a valid Widget model, it will display the createdDate field of the Widget model passed to it.
            
        V. Create a Controller.
            A controller is the interface between the system and the entity's functionality. In other words, the system 
            will give control to the correct controller when necessary.
            
            All controllers must implement the Controller interface to ensure compatibility with the system. Also,
            for simplicity, all controllers in the VM extend their respective view classes to give them easier access
            to view functionality. 
            
            A skeleton controller for our Widget would be as follows:
            
            ----------------------------------------------------
            <?php
            class WidgetController extends WidgetView implements Controller {
                function controlHandler($getvars) {
                    //first authorize the user
             		$ac = new AccessController($getvars);
            		if(!$ac->isAuthorized())
            			return;

            		switch($getvars['vm_action']) {
            			default:
                            $widget = new Widget();
                            $this->displayWidget($widget);
            			break;
            		}
                }
            }
            ?>
            ----------------------------------------------------
            
            $getvars is a collection of all $_GET and $_POST variables. Put this class definition in a file called
            'WidgetController.php' in the 'controller' directory under the 'vm' directory.
            
            Note that since this is a simple example, Widgets are not stored in the database. If this was desired,
            we would need to create a database table to store widget information, and create functions in the DAO
            to store or load Widget models. Also, we might want to have pages that would collect information about
            Widgets and then store that information in the database. Such is the case with Volunteer and Project
            entities.
            
            In this simple example, however, a new Widget is created every time the page is refreshed, and is 
            destroyed once the page has finished loading.
            
        VI. Make the VM dispatch control to the WidgetController when necessary.
            In the main.inc file, in the shn_vm_default() function, before the final 'else', add a check if 
            the 'act' URL parameter is our controller and dispatch control to it if so:
            
            ----------------------------------------------------
            ...
            else if ($_GET['act'] == 'widget'){
                $controller = new WidgetController();
                $controller->controlHandler($_REQUEST);
            }
            ...
            ----------------------------------------------------
            
            Also, at the top of the main.inc file, we must include the classes we added:
            
            ----------------------------------------------------
            ...
            require_once('model/Widget.php');
            require_once('view/WidgetView.php');
            require_once('controller/WidgetController.php');
            ...
            ----------------------------------------------------
        
       VII. Create a Menu Item for the New Entity's Default Page.
            In the menu.inc file, under the shn_vm_mainmenu() function, add this line of code before the 
            shn_mod_menuclose() function is called.
            
            ----------------------------------------------------
            ...
            $ac->addMenuItem('Widget', $ac->buildURLParams('widget', 'default'));
            ...
            ----------------------------------------------------
        
        A more involved example, which creates a Calendar entity, is provided at:
        http://www.cs.trincoll.edu/hfoss/wiki/VMOSS_%28Volunteer_Management_Open_Source_Software%29_Application

Return current item: Volunteer Management OpenSource Software