LightMVC manual

LightMVC manual

1. Getting started


1.1 What is LightMVC?


LightMVC is a platform for developing web applications in PHP5 using the MVC programming pattern. It has built in mechanisms for mySQL database connectivity and a light HTML templating system.

LightMVC's strongest point with regards to other MVC platforms in PHP (like php.MVC or phrame) is its ease of configuration.

1.2 Installation


In order be able to use LightMVC for your web application you need to have an HTTP server with PHP 5.0.x installed. LightMVC uses the PHP5 object model and cannot be used with earlier versions of PHP without modifications. If you are going to use the mySQL connectivity functions as well you need to have mySQL installed as well.

LightMVC folder structure

Unpack the package into a htdocs subfolder. Open the config.php file and set the following values:

$PROJECT_FOLDER
absolute path of the subfolder (e.g. "d:/htdocs/myLightMVCApp/")
$MYSQL_USE
true if you are going to use mySQL connectivity (requires that you have mySQL installed) false otherwise
$MYSQL_USERNAME, $MYSQL_PASSWORD, $MYSQL_DATABASE, $MYSQL_HOST
mySQL parameters
$ACCOUNTS
a list of username/password values
$TIMEOUT
Timeout in seconds for sessions logged with accounts set in $ACCOUNTS

The framework is now ready to develop your application.

2. An application example - step by step

2.1 Application scenario

Let's have a web application that has a form where the user enters a phrase and gets a histogram of the letters used.

The application will have two views: the first will display the form and the other will display the histogram. Let's call the views form (which implies the class name viewForm) and Histogram (which implies the class name viewHistogram). It is logical to have also two controllers, showForm and calculateHistogram (from this we get the classes ctrlShowForm and ctrlCalculateHistogram). We will also need a model class that will perform the histogram calculation, let's call it textObject.

2.2 GUI design

Let's create an HTML template to be used for the view viewForm. This is an HTML page with a form that has a textarea field and a submit button:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
       "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en_US" xml:lang="en_US">
 <head>
  <title> </title>
 </head>
 <body>
  <form action="index.php?do=calculateHistogram" method="post">
  <textarea name="string"></textarea>
  <input type="submit" name="name" value="value"/>
  </form>
 </body>
</html>


The other GUI component is a template that displays a table of all the characters in the string (supplied by the user through the form) its number of ocurrences and a histogram that would look like this:

Histogram

Since this page will be generated dinamically we should use the templating system integrated in LightMVC. Let's see how it works. The template we need is the following:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
       "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en_US" xml:lang="en_US">
 <head>
  <title> </title>
 </head>
 <body>
  <table>
      {loop}
      <tr>
          <td >{$char}</td>
          <td >{$count}</td>
          <td ><table><tr><td height="5" width="{$width}" bgcolor="red"></td></tr></table></td>
          <td></td>
      </tr>
      {/loop}
  </table>
  <a >Show Form</a>
 </body>
</html>

The {loop} and {/loop} tags define that there will be a loop (what else?). All the parameters within the {loop} tags should be arrays and will be looped until the end. In our case we are going to have three arrays : $count , $char and $width of the same size.

The following code shows the viewHistogram class that generates these arrays from the histogram sent by the controller, assignes its values to the template and echoes the merged data.

<?php

class viewHistogram extends baseView
{
    function run()
    {
        // fetch data passed by the controller
        if ($this->getParameter("chars")){
            $chars = $this->getParameter("chars");
        }
        else{
            $chars = array();
        }
       
        // prepare the data
        $char     = array();
        $count     = array();
        $width     = array();
        foreach($chars as $key => $value){
            $char[] = $key;
            $count[] = $value;
            $width[] = 5*$value;
        }
       
        // display the template
        $tpl = new viewTemplate();
        $tpl->assign("char" , $char);
        $tpl->assign("count" , $count);
        $tpl->assign("width" , $width);
        $tpl->display("./framework/view/histogram.html");
    }
}
?>


2.3 Action handlers implementation


When the user invokes the file index.php?do=showForm the LightMVC platform creates an instance of the ctrlShowForm class and runs the run() method.

<?php
class ctrlShowForm extends baseController
{
    function run()
    {
        $this->setView("form");
    }
}
?>

This controller does not perform any action. It only sets the view. after that the platform creates an instance of the viewForm class and runs the run() method that displays the form to the user. After the user enters a string into the form and submits it the file index.php?do=calculateHistogram is invoked. The framework creates an instance of  the class ctrlCalculateHistogram and runs the run() method:

<?php
class ctrlCalculateHistogram extends baseController
{
    function run()
    {
        if ( isset($_REQUEST["string"]) ){
            $to = new textObject();
            $to->setText($_REQUEST["string"]);
            $hist = $to->getHistogram();
        }
        else{
            $hist = array();
        }
        $this->setParameter("chars",$hist);
        $this->setView("histogram");
    }
}
?>

This controller checks whether there is a parameter from the form, creates an instance of the model textObject, passes the string sent by the user and retrieves the histogram. It then sets the histogram as a parameter to be passed to the view and sets the appropriate view.

2.4 Data objects


The last thing we need to do is the data model object, the textObject class:

<?php
class textObject extends baseModel
{
    public $text = "";
   
    function setText($text)
    {
        $this->text = $text;
    }
   
    function getHistogram()
    {
        $histogram = array();
        for ($i = 0 ; $i < strlen($this->text) ; $i++){
            $char = substr($this->text, $i, 1);
            if ( isset( $histogram[$char] ) ){
                $histogram[$char]++;
            }
            else{
                $histogram[$char] = 1;
            }
        }
        return $histogram;
    }
}
?>

The main method is getHistogram() which counts all the ocurrences of various characters and returns an array with these data.


3. Features


3.1 General LightMVC workflow

The application gets invoked by calling the index.php file. In order to perform some task there must be the "do" GET parameter which defines the controller to handle the action. The application framework creates an instance of the class named "ctrl" . $_GET["do"]. If the application was invoked with the command index.php?do=showResults the platform will create an instance of the "ctrlShowResults" class. After the instance is created the run() method is called. This method of the controller should perform the handling of the action and set the view by using the setView() method inherited by the baseController class. The controller can use the setParameter()method to pass parameters to the view. All the controller classes should extend the baseController class.

After the method run() of the controller has finished the framework creates an instance of the view set by the controller. If the controller set the view with the command

<?php
...
setView("showResultsAsHistogram");
...
?>


the framework will create an instance of the viewShowResultsAsHistogram class and call the run() method. This method should make good use of the templating system and echo the HTML code to be displayed to the user. All the view classes should extend the baseView class.

Any model classes that are used by the controllers and by the views should extend the baseModel class. This allows the model to have an open mySQL connection to use that is created at the creation of the model instance.


3.2 Templating system


... to be finished ...

3.3 Login/logout mechanism


... to be finished ...

3.4 mySQL connectivity


... to be finished ...

References

  1. Designing Enterprise Applications with the J2EETM Platform, Second Edition