Chisimba

Chisimba is a PHP framework for building web applications and applications that need a web API. It implements a model-view-controller (MVC) design pattern, implemented on a modular architecture. There is a core framework, and numerous modules that implement functionality ranging from blogs through CMS to a eLearning system. The interface design is flexible and implemented via canvases (skins, or themes). There is an online package management system, and developers can build modules rapidly by generating a working module from which to code. In order to fully install and use the Chisimba framework to its full potential, it is necessary to install a number of PHP extensions, as well as to have a few PEAR objects on hand. The word “Chisimba” is the Chichewa (Malawi) word for the framework used to build a traditional African house.

Chisimba was created as a product of a collaboration of the 13 African universities involved in the African Virtual Open Initiatives and Resources (AVOIR) project. Its main purpose is to foster capacity building in Software Engineering among African universities through the collaborative development of Free Software. However, it is an awesome technology for running and building web applications. See http://chisimba.com for more information.

Please make sure that you have a working Apache installation, as well as a functional database hosted on one of the following database servers:

1. MySQL - 5.1.x
2. PostgreSQL - 8.1 (note that we have not done much testing on PostGreSQL, so MySQL is a safer bet).

You will also need PHP version 5.1.2 or above.

The web based installer found in /path/to/webroot/chisimba_framework/installer/index.php will help you configure and der to use the mail to blog functionality, you will need the IMAP PHP extension. On most GNU/Linux distributions, this is a simple command to the package manager. On Windows based systems, it is as simple as uncommenting the extension in php.ini and downloading the required .dll.

If you have any questions, comments or other issues, please do not hesitate to post a message to our users mailing list found at:

http://groups.google.com/group/chisimba‐dev

Have fun! Enjoy Chisimba!

Hello world

A Chisimba MVC hello world

This chapter assumes that you have:

an installed and working Chisimba installation on your computer; knowledge of PHP; read the chapter on Module Catalogue, and carried out the activities in it.

A "hello world" program is a computer program that prints out "Hello, World!" on a display device. It is used in many introductory tutorials for teaching a programming language. Such a program is typically one of the simplest programs possible in a computer language. In this case, we will use it as a very simple example to ensure that you understand the MVC approach, and the minimum structure for a Chisimba module. Once you understand this structure, you can apply your existing skills to Chisimba very easily.

The M in MVC refers to the model, which is typically the data access layer. In this case, we are not going to access any external data yet, so we will ignore the model, and concentrate on the view and the controller.

Create a directory called hellochisimba (or hellowhatever) in your chisimba_modules directory: /path/to/chisimba/chisimba_modules/hellochisimba, where /path/to/chisimba/ is the place where your chisimba files are located, for example /var/www/ on Linux or c:\Inetpub on Windows.

Create a text file in that directory and name it controller.php. Open it in your favorite text editor (or IDE) and first enter the opening PHP tag and the required description of your module as follows:

<?php
/**
 * 
 * Hello  Chisimba
 * 
 * A classic hello world type module to introduce you to Chisimba.
 * 
 * PHP version 5
 * 
 * This program is free software; you can redistribute it and/or modify 
 * it under the terms of the GNU General Public License as published by 
 * the Free Software Foundation; either version 2 of the License, or 
 * (at your option) any later version.
 * This program 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 General Public License for more details.
 * You should have received a copy of the GNU General Public License 
 * along with this program; if not, write to the 
 * Free Software Foundation, Inc., 
 * 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 * 
 * @category  Chisimba
 * @package   helloforms
 * @author    Your Name youremail@yourdomain
 * @copyright 2010 AVOIR
 * @license   http://www.gnu.org/licenses/gpl-2.0.txt The GNU General Public License
 * @version   CVS: $Id: controller.php,v 1.4 2007-11-25 09:13:27 your-user-name Exp $
 * @link      http://avoir.uwc.ac.za
 */

Please note that you should have these document blocks in all your code, as this is how the code documentation is generated. Code that is not documented like this should not be committed to subversion as it will be removed with no warning, and it should not exist on your computer for more than 3-12 minutes. In general, it is best to write the doc blocks before you write any code.  

Now start entering the controller code, beginning with the standard security check as follows:

// security check - must be included in all scripts
if (!
/**
 * The $GLOBALS is an array used to control access to certain constants.
 * Here it is used to check if the file is opening in engine, if not it
 * stops the file from running.
 * 
 * @global entry point $GLOBALS['kewl_entry_point_run']
 * @name   $kewl_entry_point_run
 *         
 */
$GLOBALS['kewl_entry_point_run'])
{
        die("You cannot view this page directly");
}
// end security check

This prevents the code from being executed if it is not being run as a Chisimba controller. The name “kewl_entry_point_run” is used for backward compatibility with previous versions. Make sure you include the comments as well.

The next set of lines in your controller is the PHPDocumentor style comments for the controller class.

/**
* 
* Hello Chisimba
* 
* Controller class for Chisimba for the module hellochisimba
*
* @author Derek Keats
* @package hellochisimba
*
*/

As noted, it is always a good practice to write these comments first, as code without well written comments will not be allowed into the Chisimba code base or any of its modules, and your code will be seen by other Chisimba programmers as being of amateur quality. You may get growled at on the mailing list as well, so to avoid this kind of embarrassment, write your comments first. We will return to the PHPDocumentor style comments later. For now, you can just enter them as above, replacing Yourname Here with your name.

Now begins the real business of the code. Create the class definition as follows:

class hellochisimba extends controller
{
}

Note that the class has the same name as the module and the directory that it is in, and must extend the framework controller class. This is always the case, otherwise the engine will not find and execute your module. Note also that the curly braces are underneath the letter “c” of the word class, and that all names are in lower case. All indents are 4 spaces (not tabs).  Violate this convention at your own peril. 

Please note that there might be a hellochisimba module already in the subversion repository, in which case you will not be able to give yours the same name. Rather then use helloyourname (where yourname is obviously your shoe size). Remember the directory and the controller class must have the same name.

All Chisimba classes that extend the framework have a constructor that is named init(), so creating that constructor is the next bit of code needed. A common use of the constructor is to set up default values for object properties, instantiate common objects, and in this case we will not be using it at all until we get to multilingual code.

    /**
    * 
    * Constructor for the hellochisimba controller
    *
    * @access public
    * @return void
    * 
    */
    public function init()
    {

    }

For the hello world example, we do not need any code in the init() method, so we can continue to the dispatch() method. A controller must have a dispatch() method that is invoked by the engine to process the logic of the controller.  The dispatch() method uses methods determined from the action  parameter of the  querystring and executes the appropriate method, returning its appropriate template. The dispatch() method of many older Chisimba modules use case statements instead or the $this->$method() approach. Either is acceptable, but this method produces cleaner code that is easier to read.  The code is as follows:

    /**
     * 
     * The standard dispatch method for the hellochisimba module.
     * The dispatch method uses methods determined from the action 
     * parameter of the  querystring and executes the appropriate method, 
     * returning its appropriate template. This template contains the code 
     * which renders the module output.
     *
     * @access public
     * @return The output of the executed method
     * 
     */
    public function dispatch()
    {
        //Get action from query string and set default to view
        $action=$this->getParam('action', 'view');
        /*
        * Convert the action into a method (alternative to 
        * using case selections)
        */
        $method = $this->__getMethod($action);
        /*
        * Return the template determined by the method resulting 
        * from action
        */
        return $this->$method();
    }
All Chisimba dispatch() methods will have exactly the same code, so once you have written this, can write a dispatcher for any module.

There is only one method needed for this module, which is the __view() method. Note the double underscore (_ and _) in front of the method name, whic