Case study 1 - How to start with Buster

Introduction.

In this document I'll try to explain how to configure and run Buster. Every step will explains important elements of Buster configuration. On last step Buster should shows you a test page. This study is very basic but it is important for future, more complicated, studies.

Notice: Buster sources must be accesed by example php files showed in steps below. So:

• you may unzip Buster to /usr/share/php directory (this is default configuration if you install Buster from debian package),
• or whatever in your file system but set correctlly include path in php.ini,
• or in DocumentRoot directory (see Step 2.).

Notice: I usually use Apache2 so this example is based on it. If you have other web-server please read documentation about Rewrite module.

Step 1. Creating virtual host.

First of all we need to configure Apache. We need to add VirtualHost for our portal. For example if portal should works on port 1000 then create file "portal" in /etc/apache2/sites-enabled with content below and restart web server service.

Listen 1000
<VirtualHost _default_:1000>
  DocumentRoot /var/www/
  RewriteEngine on
  RewriteRule !(^/css/|^/images/|^/js/) /MasterServlet.php
</VirtualHost>

In above configurtion please fill properly DocumentRoot. There are full path where files for portal will be stored. MasterSevlet.php is Dispatcher for all contexts except contents of css, images and js directories.

Step 2. Creating directory content.

In your DocumentRoot directory you have to make some important subdirectories and control files.

• logic - this directory will contains logic actions,
• templates - this directory will contains templates for ViewController,
• templates_c - this directory will contains cached generated pages,
• MasterServlet.php - is main dispatcher for every accessed contexts, this is the same file in RewriteRule in Step 1,
• controllerActions.php - contains informtion about contexts accessed by users,
• SimpleClassConfig.php - is main configuration for portal.

As writed above in /var/www should be:

-rw-r--r-- 1 root root     1113 2006-06-03 11:03 controllerActions.php
drwxr-xr-x 3 root root     4096 2006-04-26 21:48 logic
-rw-r--r-- 1 root root      495 2006-03-27 23:06 MasterServlet.php
-rw-r--r-- 1 root root      686 2006-03-27 23:06 SimpleClassConfig.php
drwxr-xr-x 3 root root     4096 2006-06-03 11:03 templates
drwxrwxr-x 3 root www-data 4096 2006-06-03 12:05 templates_c

Notice: There are important to grant write access on cache directory templates_c for user of Apache process.

Step 3. Dispatcher.

In this example Dispatcher is MasterServlet.php. In this file we must init configuration and run Buster processing. Below is minimal dispatcher content:

<?php
include_once("Buster/Buster.php");
include_once("SimpleClassConfig.php");
include_once("controllerActions.php");

$buster = new Buster(new SimpleClassConfig());
$buster->init($_ControllerActions);
$buster->execute();
?>

Step 4. Our configuration.

We must configure some minimal parameters for Buster. SimpleClassConfig may contains:

<?php
include_once("Buster/config/ClassConfig.php");

class SimpleClassConfig extends ClassConfig{

  protected $configArray = array(
    // Controller
    ctrl_logic => "logic",
    ctrl_templates => "templates",
    ctrl_compile => "templates_c"
  );

}
?>

Step 5. Configure contexts.

All accessible contexts must be defined in special array which will be given to Buster init() function. We define this contexts in separate file controllerActions.php and include it in Dispatcher. Below is content of controllerActions.php file:

<?php
$_ControllerActions = array(
  "actions" => array(

   "/" => array(
                        "logic" => "EmptyAction",
                        "secured" => "false",
                        "view" => array(
                        "SUCCESS" => "index"
                ),
   )
));
?>

Above is defined only one context. If client will connect to our web-server RewriteRule will run MaterServlet dispacher. Dispatcher will init and run Buster with definition of contexts. Buster tests if it possible to access context by client is defined in $_ControllerActions array. If context will be "/" then Buster run EmptyAction logic and if Action return "SUCCESS" string then Buster will process 'index' smarty template. It's easy, isn't?

Step 6. Actions and templates.

Every action defined in context array (see: Step 5.) has to be defined in logic subdirectory. It must be a PHP class which implemets IControllerAction interface. Below is content of EmptyAction.php file:

<?php
include_once("Buster/controller/IControllerAction.php");

class EmptyAction implements IControllerAction{

  function execute($request, $pageContext){

    return "SUCCESS";

  }

}
?>

Every template defined in context array (see: Step 5.) has to be stored in templates subdirectory. If we are usnig Smarty as ViewController then files have to be a smarty templates. Below is an example of 'index' template:

<html>
 <head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <title>Welcome to Buster exaple page</title>
 </head>
This is example.
</html>

Step 6. Summary.

This is minimal information about usage Buster framework. But it's only one percent of all Buster features. In next Studies i'll try explain next important aspects of Buster usage.