php.MVC The Model View Controller (MVC) Framework for PHP Web Applications

This guide describes the php.MVC template tags system (PhpMVC_Tags). PhpMVC_Tags implements several template tags that are included with the php.MVC framework. The PhpMVC_Tags is a simple template tags implementation that may be useful in situations where the developer does not require a more complex external system such as Smarty or PhpTAL.

For an introduction to the Model-View-Controller (MVC) concept and how it relates to php.MVC please read the php.MVC Users Guide 101. It is assumed that the reader has a working knowledge of the php.MVC framework.

The examples used in this guide are based on the accompanying example application. The complete working example with source files and including this guide can be downloaded here: phpmvc-tags-v1.0.zip.

PhpMVC_Tags presently provides the following tag types:


include directives

, declarations and expressions.

An include directive lets us separate content into modules such as page headers, footers or contents. The included page can contain plain HTML, or another tag template page. For example the following include directive can be used to include a header section within a template page:

 <@ include 'pageHeader.ssp' @>

A declaration allows us to declare page-level variables for use in the template, or even other included pages. A page declaration looks something like:

 <@ salesAreaID = "Central District" @>

An expression tag allows us to evaluate an expression within our template page. The result of the expression will be included in the template page. The following expressions could be used to display a simple string (salesAreaID), and retrieve a framework configuration class attribute, respectively:

 <@ =salesAreaID @>
 <@ =viewConfig.getAreaManager @>

The php.MVC version beta 0.4.0 introduces a new configuration class called ViewResourcesConfig. This class can be used to define global parameters that can be used in View resources (templates), and also to configure the PhpMVC_Tags system, as will be shown in the sections below. The view-resources element of the application phpmvc-config.xml configuration file used in this example is shown below:

 <view-resources
       appTitle    = "Flash Jacks' Sleek Tab Site"
       copyright   = "Copyright © 2010 Flash Jack. All rights reserved."
       contactInfo = "flash.jack@jackshost.com"
       processTags = "true"
       compileAll  = "true"
       className   = "MyViewResourcesConfig">

       <!-- We can set some properties on our custom ViewResourcesConfig class        -->
       <set-property property="areaManager" value="Joe J. Blogs Esq."/> 
  </view-resources>

Template page processing using PhpMVC_Tags can be controlled declaratively by using an <view-resources ...> node in the application phpmvc-config.xml configuration file. Firstly we can specify whether all template pages are processed (compiled) by the PhpMVC_Tags system or just changed pages, for each request. Secondly we can specify whether or not the PhpMVC_Tags system is actually called to process the tag pages, which could be useful during and after application development. A section of an <view-resources ...> node is shown below with the compileAll and processTags attributes set to True (always process tag pages and process all tag pages):

 <view-resources
   ...
   processTags = "true"
   compileAll  = "true"
   ...
 </view-resources>

The Action Dispatcher

The (php.MVC version beta 0.4.0 +) framework ActionDispatcher class is responsible for making FormBean, Errors, Value (business data) and the ViewResourcesConfig objects available to our View objects (templates).

Before examining the PhpMVC_Tags system we should take a quick look at the ActionObjects and ViewResourcesConfig class when using the standard ActionDispatcher.

ActionObjects

The framework ActionDispatcher makes several objects available to the application View resources that we can use in our template pages. The three standard ActionObjects are the: FormBean, Errors, and Value (business data) objects.

The tables below show how to use FormBean, Errors, and Value objects in FormAction and Action classes.

Saving ActionObjects in ActionForm Classes

ActionErrors	$this->saveErrors($request, $actionErrors)
FormBeans	$this->saveFormBean($request, $this)
ValueObjects	$this->saveValueObject($request, $valueObject)

Saving ActionObjects in Action Classes

ActionErrors	$this->saveErrors($request, $actionErrors)
FormBeans	$this->saveFormBean($request, $form)
ValueObjects	$this->saveValueObject($request, $valueObject)

Retrieving ActionObjects in View Resources (Templates)

ActionErrors	$errors->getItemString('logon_username_reqd')
FormBeans	$form->username
ValueObjects	$data->salesNorth

An ActionObject will be initialised to NULL if the object has not been previously created and saved. For a detailed discussion of ActionObjects please read the php.MVC ActionObjects Usage Guide.

View Resources

The ActionDispatcher also exposes the ViewResourcesConfig object to our template pages. A ViewResourcesConfig object is configured by defining a <view-resources ... > element in the application phpmvc-config.xml configuration file, as shown in the Introduction section above. If the ViewResourcesConfig object has not been configured a new instance is created using the default ViewResourcesConfig class attributes.

The code sample below shows how we could access a ViewResourcesConfig property in our HTML page header template using a PhpMVC_Tags expression:

 <!-- Page Header --> 
 <span>
  <@ =viewConfig.getAppTitle @>
 </span>

More on the ViewResources Configuration class below.

Configuring the Action Dispatcher

The ActionDispatcher is the default php.MVC (beta 0.4.0 +) Dispatcher class. This Action Dispatcher is included with the framework will be used by default, unless we define an alternate Dispatcher class. In the next section we will see how to configure our application to use an alternate Dispatcher - the TagActionDispatcher class.

The Php.MVC Tag Action Dispatcher

The TagActionDispatcher is an application specific implementation of the standard ActionDispatcher class that supports access to basic template tag functionality within the php.MVC framework. The TagActionDispatcher class supports the same set of ActionObjects and the ViewResourcesConfig properties as the default ActionDispatcher. The TagActionDispatcher class can be used with or without using the php.MVC tags services, although a small performance penalty may result due to the extra processing overhead.

The PhpMVC_Tags library is a sub-system of the php.MVC framework. The PhpMVC_Tags library works in conjunction with the TagActionDispatcher to support the use of some simple template tags with php.MVC applications.

The diagram below shows an overview of the PhpMVC_Tags system. The left part of the diagram shows the PhpMVC_Tags program flow. The right side of the diagram shows the TagActionDispatcher program flow, and how the classes interact to process the application tag templates.

Figure 1: The php.MVC Tag Action Dispatcher Activity Diagram

The paragraphs below outline the main stages of the PhpMVC_Tags system when processing php.MVC template tag files.

1: Initialisation Stage. When the controller passes control to the TagActionDispatcher, some initial initialisation takes place to setup the ActionObjects and ViewResourcesConfig properties for use on our templates:

Retrieve the $form, $errors and $data objects from the request. If any of these objects have been previously created (for example in an Action class) the object will now be visible to the resource template, otherwise the object will be set to NULL.
Retrieve a reference the ViewResourcesConfig object containing the configuration parameters.
Setup the paths to the template source files and the compiled template files using the ViewResourcesConfig parameters.

2: Setup the Tag Pages Stage. The filename extension (perhaps ".ssp") of the resource template file is compared to the ViewResourcesConfig->tagFlagStr parameter to determine if this page requires processing, otherwise the page is handled as a standard (non-tags) template file. We can define the tag file extension in the view-resources element of our application XML configuration file, like this:

 <view-resources
   ...
   tagFlagStr = ".ssp"
   tagFlagCnt = "-4"
   ...
 </view-resources>

Where tagFlagStr indicates tag template source file(s) to be pre-processed, for example: myPage.ssp. This extension triggers tag processing. And the attribute tagFlagCnt defines the number of trailing filename characters to sample, including the "." (xxxYyy.ssp). For example, -4 says to sample the last four characters of the resource file name. The default values are .ssp and -4, so if we use a template file name like myPage.ssp, we do not need to explicitly set these parameters.

3: The Process Tag Files Stage. This is where the PhpMVC_Tags system determines whether to run the template tag processor, according to the ViewResourcesConfig->processTags property. If processTags evaluates to True, the template pages (and included pages) are processed by the tag processor class, otherwise the tag processor is not called. The developer would normally set the ViewResourcesConfig->processTags property to True during development, and False otherwise. Note that even when the processTags property is set to True, tag pages will only be compiled if they have been modified (depending on the compileAll attribute setting - see below). This will optimise the PhpMVC_Tags system , reducing processing overhead by eliminating unnecessary calls to the PhpMVC_Tags classes. We can define the processTags property in the view-resources element of our application XML configuration file, like this:

 <view-resources
   ...
   processTags = "True"
   ...
 </view-resources>

The default value of the processTags property is


False

4: The Compile Template Pages Stage. If the TagActionDispatcher determines that the template page is to be processed (as discussed above), it passes control to the PhpMVC_Tags system. Now the PhpMVC_Tags system must determine whether to compile only changed pages, or compile all pages. This behaviour is defined using the ViewResourcesConfig->compileAll property. We define the compileAll property in the view-resources element of our application XML configuration file, like so:

 <view-resources
   ...
   compileAll = "True"
   ...
 </view-resources>

The default value of the compileAll property is


False

. The options are discussed next.

5: The Compile Changed Pages Only. If the compileAll property is set to False (the default), only changed pages will be compiled. For example if the requested template page was modified since the last request for that page, the page will be compiled by the PhpMVC_Tags classes.

6: The Compile All Pages. If however the compileAll property is set to True, the PhpMVC_Tags system will always compile the page (and all included pages) regardless of whether the page(s) have been modified since the last request. The developer can use this option during development to ensure that all pages are being processed.

7: The Process View Resources Stage. After processing the template page, control is returned to the TagActionDispatcher. The requested View resource (template file) is then handled as any other regular php.MVC template file. The TagActionDispatcher retrieves the compiled page (and included pages) and returns the page output to the users browser. If the PhpMVC_Tags system was not called, as discussed above, the TagActionDispatcher handled the request as if the requested page was a regular View resource. For example the TagActionDispatcher can be used in place of the standard ActionDispatcher.

The php.MVC Tag Syntax

With the basic operation covered, we can now look at the PhpMVC_Tags syntax.

Before looking at the actual tag types, we should define what a PhpMVC_Tags tag is. To write a PhpMVC_Tags tag, we use the <@ .... @> tag notation. The left tag (<@) and the right tag (@>) are the default tags for the PhpMVC_Tags system. These tags can be reassigned in our application XML phpmvc-config.xml configuration file, if necessary.

As mentioned in the introduction, PhpMVC_Tags currently supports the following tag types: include directives, declarations and expressions. We will take a look at these directives next.

Include Directives

The include directive lets us separate content into modules such as page headers, footers or contents. The included page can contain plain HTML, or another tag template page. For example the following include directive can be used to include a header section within a template page:

 <@ include 'pageHeader.ssp' @>

An example of an include directive in the context of a template page is shown here:

<html>
<head>
...
</head>
<body>
<center>
<table class='pageLayoutTable'>
   <tr>
      <td class='pageHeader'>
         <@ include 'pageHeader.ssp' @>
      </td>
   </tr>
   <!-- PAGE CONTENTS -->
   ...
   <!-- PAGE FOOTER -->
   ...
</table>
...
</center>
</body>
</html>

In this example the pageHeader.ssp header file contents will be inserted into the page main page when the page is sent to the users browser. The header file used here is a simple file that includes an expression:

<!-- Page Header --> 
 <span>
    <@ =viewConfig.getAppTitle @>
 </span>

This expression will be compiled and will evaluated at run-time to something like:

<!-- Page Header --> 
 <span>
    Flash Jacks' Sleek Tab Site
 </span>

Declarations

A declaration allows us to declare page-level variables for use in the template, or even other included pages. A page declaration looks something like:

 <@ salesAreaID = "Central District" @>

We can use page declarations in a template file like this:

<@ saleMonth   = data.getValueBean('SALE_MONTH') @>
<@ saleTitle   = data.getValueBean('SALE_TITLE') @>
<@ dealHeading = data.getValueBean('DEAL_HEADING') @>
<@ salesAreaID = "Central District" @>

<html>
<head>
   <link rel='stylesheet' type='text/css' href="./style/pageStyles.css"/>
   <title>
      ...
   </title>
</head>
<body> 
...
</body>
</html>

In this example we declare some page variables. The first three variables have been assigned values from an ActionObject that we created in our Action class: data.getValueBean('SALE_MONTH'). And the fourth variable is assigned a string value: salesAreaID = "Central District" .

The declared variables can now be used on the page, or in included pages, as shown below:

<!-- start_page_contents_include -->
...
<!-- Content section heading -->
<h4><@=dealHeading @> <@=saleMonth @></h4>

<center>
Clearance deals
<table class='productsTable'>
   ...
</table>
</center>

<center>
Todays specials
<table class='productsTable'>
   ...
</table>
</center>
...
<!-- end_page_contents_include -->

This page variables will evaluate to something like:

<!-- Content section heading -->
<h4>Jack's Super Deals for : May 2010</h4>
...
...

Expressions

 <@ =salesAreaID @>
 <@ =viewConfig.contactInfo @>

To use these expressions we will have declared the string variable previously:

 <@ salesAreaID = "Central District" @>

And declared the ViewResourcesConfig object (viewConfig) property in the view-resources node of our application XML configuration file:

 <view-resources
    appTitle    = "Flash Jacks' Sleek Tab Site"
    contactInfo = "flash.jack@jackshost.com"
    ...
  </view-resources>

When using expressions involving objects, we can write the object-method declaration in standard PHP type notation or dot style notation, as shown in the table below:

The PhpMVC_Tags Object-Method Notation

PHP Style	sales = data->getSales
Dot Style	sales = data.getSales
With Method Params	staff = data.getValueBean("STAFF")
Retrieve Data Array	products = data->getValueBean("PRODUCTS_ARRAY")

In the next section we will see how all this fits together to build modular pages using PhpMVC_Tags.

The Page Layout

In this section we look at how to construct a modular template page using the PhpMVC_Tags system. The example we are using uses a simple HTML page layout as shown in figure 2 below.

Figure 2: Page layout using PhpMVC_Tags

This page consists of standard sections, as will be familiar to page designers and developers. This page is made up of a main page body containing three included sections: The page header; page contents and the page footer. We will now take a look at each of these sections and how they can be implemented using PhpMVC_Tags.

The Page Body

The code section below shows the body, or skeleton of our page layout.

The Page Body Layout

1
<@ saleMonth    = data.getValueBean('SALE_MONTH') @>
<@ saleTitle    = data.getValueBean('SALE_TITLE') @>
<@ dealHeading  = data.getValueBean('DEAL_HEADING') @>
<@ salesAreaID  = "Central District" @>

<html>
<head>
   <link rel='stylesheet' type='text/css' href="./style/pageStyles.css"/>
   <title>
2     <@ =viewConfig.getAppTitle @>
   </title>
</head>
<body>

<table class='pageLayoutTable'>

   <!-- PAGE HEADER -->
   <tr>
      <td class='pageHeader'>
         <!-- including the page header component -->
         <!-- The base template base directory is "./tpl"  -->
3        <@ include 'pageHeader.ssp' @>
      </td>
   </tr>

   <!-- PAGE CONTENTS -->
   <tr valign='top'>
      <td class='pageContent'>
         <!-- including the page contents component -->
4        <@ include 'sale/pageContent.ssp' @>
      </td>
   </tr>

   <!-- PAGE FOOTER -->
   <tr>
      <td class='pageFooter'>
         <!-- including the page footer omponent -->
5        <@ include 'pageFooter.ssp' @>
      </td>
   </tr>
</table>

</body>
</html>

1: The page declarations
The first items of interest are the page declarations (1) at the top of the page. We have covered page declarations in the php.MVC Tag Syntax section above. We are declaring these variables at the beginning of the body page, so the variables will be available in the main page body and all included sections, like the header and body.

2: The page title
Next we use an expression to initialise the page title (2). This value is taken from the ViewResourcesConfig->getAppTitle property in the view-resources element of our application XML configuration file:

<view-resources
   appTitle = "Flash Jacks' Sleek Tab Site"
   ...
</view-resources>

3: The page header
The page header is the next item of interest (3). Here we are using an include directive to insert the page header template file into the main page body. We will take a look at the page header in the next sub-section.

We have just used a page directive to load the page header, but where are the page component files stored. This is a good opportunity to introduce the PhpMVC_Tags directory definitions. By default, the template directory layout for PhpMVC_Tags applications is a follows (Note that the paths are relative to our application):

The Default PhpMVC_Tags Template Directory Layout Paths (relative)

The Template Files	'./WEB-INF/tpl'
The Compiled Template Files	'./WEB-INF/tpl_C'

These paths can be redefined in the view-resources node of our application XML configuration file if required, something like this:

<view-resources
   ...
   tplDir   = "./WEB-INF/tpl-admin"
   tplDirC  = "./WEB-INF/tpl_admin_C"
   ...
</view-resources>

4: The page content
This is another include directive used to insert the page contents template file (4) into the main page body. Note that the contents file is located in the sales subdirectory of the template directory:

 "./WEB-INF/tpl/sale/pageContent.ssp"

5: The page footer
Again just another include directive, as we used in the header section.

The Page Header Section

In this example the page header template file ('pageHeader.ssp') is just a simple section that looks like this:

<!-- Page Header -->
<span>
   <@ =viewConfig.getAppTitle @>
</span>

When the main page (and the included pages) is compiled, the expression in the header section is transformed into something like the following:

<!-- Page Header -->
<span>
   <?php print $viewConfig->getAppTitle(); ?>
</span>

The compiled pages are stored in the compiled template directory, As mentioned above, the default compile template directory is:

  './WEB-INF/tpl_C'

The Page Contents Section

The page content template file is a little more complex. The example contents file ('sale/pageContent.ssp') is shown below, abbreviated for clarity:

...
1
<@ item1=data->getValueBean("ITEM_1") @>
<@ products=data->getValueBean("PRODUCTS_ARRAY") @>

2
<h4><@=dealHeading @> <@=saleMonth @></h4>

3
<b>Clearance deals</b>
<table class='productsTable'>
   <tr>
      <td class='prodItemDesc'>
         <@ =item1.getName @>
      </td>
      <td class='prodItemValue'>
         <@ =item1.getCost @>
      </td>
   </tr>
</table>

4
<b>Todays specials</b>
<table class='productsTable'>
<?php foreach($products as $item) { ?>
  <tr> 
    <td class='prodItemDesc'>
         <@ =item.getName @>
    </td>
    <td class='prodItemValue'>
         <@ =item.getCost @>
    </td>
  </tr>
<?php } ?>
</table>

<b>Our Staff at Your Service</b>
...
5
<table class='productsTable'>
  <tr>
    <td class='prodItemDesc'>
      <b>Area Manager: </b>
    </td>
    <td class='prodItemDesc'>
      <@ =viewConfig.getAreaManager @>
    </td>
  </tr>
  ...
</table>

1: Some more page declarations
The additional declarations (1) at the top of this page show that we can declare page variables that will be visible in this included page (actually all pages included after this page). After the contents page has been processed, the declarations will looks like this in the compiled page:

<?php $item1=$data->getValueBean("ITEM_1"); ?>
...
<?php $products=$data->getValueBean("PRODUCTS_ARRAY"); ?>

2: Displaying the contents section heading using expressions
Here we use two page expressions (2) to display the contents section heading. Note that we declared these "global" variables at the top of the main page body. After processing, the expressions will be transformed into code that looks like this in the compiled template:

<?php print $dealHeading; ?> <?php print $saleMonth; ?>

When the page is displayed in the users browser, the contents section heading could look something like:
Jack's Super Deals for : May 2010.

3: Displaying some data items using expressions
Now we can get down to displaying some actual data (3). In this section of the contents page we are accessing some product item data that was defined and saved as an ActionObject in the application PhpMVCTabAction class. An abbreviated version of the PhpMVCTabAction class is shown below for convenience:

class PhpMVCTabAction extends Action { 
   ...
   function execute($mapping, $form, &$request, &$response) {
      // Our value bean container
      $valueBeans =& new ValueBeans();

      // Define some strings we need on our View template page
      // These could be defined globally in the phpmvc-config.xml file.
      // See: ExtendedController example.
      $appTitle      = "Flash Jack's Include Page";
      $saleMonth     = "May 2010";
      $saleTitle     = "Flash Jack's Super Sale";
      $dealHeading   = "Jack's Super Deals for :";
      ...

      // Save the string variables to our Value object
      $valueBeans->addValueBean('APP_TITLE'     , $appTitle);
      $valueBeans->addValueBean('SALE_MONTH'    , $saleMonth);
      $valueBeans->addValueBean('SALE_TITLE'    , $saleTitle);
      $valueBeans->addValueBean('DEAL_HEADING'  , $dealHeading);
      ...

      // Some float values we could receive from a database query
      // Note: The prices are formatted in the Products class constructor. 
      // Eg: "$ n,nnn.nn"
      $price1 =  125.00;
      ...

      // Setup some clearance deals (individual object instances):
      // Note: The Product class file was included in our local prepend.php file
      $item1 = new Product('Super Duper', $price1);
      ...
      $valueBeans->addValueBean('ITEM_1', $item1);
      ...

      // Todays specials (array of object instances)
      $products = array();
      $products[] = new Product('Gooses Bridle', $price3);
      ...
      $valueBeans->addValueBean('PRODUCTS_ARRAY', $products);

      // Our staff
      $staff1 =& new Staff('Bruce', 'Sales', 'Karate');
      ...
      $valueBeans->addValueBean('STAFF_1', $staff1);
      ...

      // Save the Value object
      $this->saveValueObject($request, $valueBeans);

In the code section above, we can see how the $item1 bean was created and saved as an ActionObject valueBeans item. (New users may like to refer to other php.MVC user guides for a detailed explanation of how Action classes work). The Bean data item can now be retrieved in our template pages like this:

<@ item1=data->getValueBean("ITEM_1") @>

And we can display the item values on the page like this:

<@ =item1.getName @>
...
<@ =item1.getCost @>

4: Displaying array data
We can also use some straight PHP code on our template pages. In keeping with the spirit of the MVC pattern we should only use code in this situation to manipulate data supplied via the ActionObject and the ViewResourcesConfig instances (and perhaps our custom beans as well). In the page contents section above ('sale/pageContent.ssp') we use a PHP foreach statement (4) to loop over the $products array. We can see in the PhpMVCTabAction class above how the $products data array was created and saved to the ActionObject in a similar manner to the $item1 bean. Within the foreach loop we can use expressions to display the products data:

<?php foreach($products as $item) { ?>
   <tr> 
      <td class='prodItemDesc'>
         <@ =item.getName @>
      </td>
      <td class='prodItemValue'>
         <@ =item.getCost @>
       </td>
   </tr>
<?php } ?>

5: Displaying ViewResourcesConfig properties
Finally we display the "Area Manager" (5) on our contents page from a ViewResourcesConfig property defined in the view-resources element of the application phpmvc-config.xml configuration file:

 <view-resources
       appTitle    = "Flash Jacks' Sleek Tab Site"
       ...
       className   = "MyViewResourcesConfig">

       <!-- We can set some properties on our custom ViewResourcesConfig class        -->
       <set-property property="areaManager" value="Joe J. Blogs Esq."/>
  </view-resources>

But note that in this case we have used an extended

ViewResourcesConfig

class (MyViewResourcesConfig) to setup some custom properties not available on the framework supplied ViewResourcesConfig class. We define our extended ViewResourcesConfig class by using the className="MyViewResourcesConfig" attribute, where the MyViewResourcesConfig class will be defined in the file "MyViewResourcesConfig.php". The MyViewResourcesConfig class (classes/MyViewResourcesConfig.php) implements the setter/getter methods necessary to handle the property ("areaManager") we defined in the view-resources node above:

class MyViewResourcesConfig extends ViewResourcesConfig {

   // ----- Properties ----------------------------------------------------- //

   var $areaManager = '';

   function getAreaManager() {
      return $this->areaManager;
   }

   function setAreaManager($areaManager) {
      $this->areaManager = $areaManager;
   }

Now we can display the "Area Manager" on our page using the expression:

   <@ =viewConfig.getAreaManager @>

Note that in a real application the data would usually be retrieved form a relational database.

The Page Footer Section

The page footer section is handled in a similar manner to the page header discussed above. The page footer template file ('tpl/pageFooter.ssp') looks like this:

<!-- Page Footer -->
<span>
  <@ =viewConfig.getCopyright @>
</span>

And again when the main page (and the included pages) is compiled, the expression in the footer section is transformed into something like the following:

<!-- Page Footer -->
<span>
   <?php print $viewConfig->getCopyright(); ?>
</span>

The compiled header page is stored in the compile template directory. The default compile template directory is:

  './WEB-INF/tpl_C'

Setting up PhpMVC_Tags Applications

Setting up for a PhpMVC_Tags application involves a few simple steps.
Note that the following instructions assume the use of the new SleeK application front end, as used in the accompanying example.

Modifying the application boot.ini file

The application boot.ini file contains the information needed to get the php.MVC framework started when the application receives a request. The boot.ini file is usually located in the application "WEB-INF" directory. To setup an application for use with the PhpMVC_Tags class, we need to define a few properties in the boot.ini file:

The TagActionDispatcher class
As mentioned in the The Tag Action Dispatcher section above, the TagActionDispatcher is an application specific implementation of the standard ActionDispatcher class. To get the framework to load the TagActionDispatcher class, we set the $appServerRootDir variable to 'TagActionDispatcher':

 // Setup the application specific ActionDispatcher (RequestDispatcher)
 $actionDispatcher = 'TagActionDispatcher';

The php.MVC library root directory
We also need to set the path to our php.MVC library location (this is an absolute file system path):

 // Set php.MVC library root directory (no trailing slash).
 $appServerRootDir = 'C:\WWW\phpmvc-base';

(if you have not yet installed the php.MVC library, see below).

Optional settings
The application timer can be turned on or off using the $timerRun property:

 // Timer reporting. 1=on, 0=off
 $timerRun = 1;

And to instruct the framework to always (force) compile the application phpmvc-config.xml XML configuration classes (say, during development - slower), we use:

  // The application XML configuration data set:
  $appXmlCfgs = array();
  $appXmlCfgs['config'] = array('name'=>'phpmvc-config.xml', 'fc'=>True);

or to only recompile the application configuration when the phpmvc-config.xml file has been modified (after development is complete - faster), we use:

  // The application XML configuration data set:
  $appXmlCfgs = array();
  $appXmlCfgs['config'] = array('name'=>'phpmvc-config.xml', 'fc'=>False);

Setting up the Application Template Directories

When setting up the template directories for a PhpMVC_Tags application, we need to create a directory (and possibly sub directories) within our application to hold our PhpMVC_Tags template files. This directory must be named as defined by the $tplDir property in the ViewResources Configuration Class, the default is './WEB-INF/tpl'. For instance, the example application has a template directory structure setup like this:

 - PhpMVC-Tags
     Index.html
     Main.php
     WEB-INF
        tpl
           pageFooter.ssp
           pageHeader.ssp
           salePageBody.ssp
           sale
              pageContent.ssp

We also need to create the directory to hold the compiled pages. This directory must be named as defined by the $tplDirC property in the ViewResources Configuration Class, the default is './WEB-INF/tpl_C'. The example application compiled template directory structure looks like this:

 PhpMVC-Tags
    Index.html
    Main.php
    WEB-INF
       tpl
          ...
          sale
             ...
          tpl_C
             pageFooter.sspC
             pageHeader.sspC
             salePageBody.sspC
             sale
                pageContent.sspC

Note that we also need to create the sale directory within the './WEB-INF/tpl_C' directory.

Setting up the php.MVC Library Paths and Includes

Check that the following path settings have been defined in the GlobalPaths.php and globalPrepend.php files in your framework installation "/WEB-INF/" directory:

GlobalPaths.php
------------------------------------------------
 $appDirs[] = 'WEB-INF/lib/phpmvc_tags';

globalPrepend.php
------------------------------------------------
 include_once 'PhpMVC_Tags.php';

Define these variables if they do not exist in the files as shown (if you have not yet installed the php.MVC library, see below).

Installing the php.MVC Library

Download the latest version of the php.MVC library here: CVS Snapshots.

Unpack the library archive to a directory, preferably off the Web root for a more secure installation. Revise the path settings and include settings as described above.

Running the Example Application

Download the example application. The complete working example with source files and including this guide can be downloaded here: phpmvc-tags-v1.0.zip.

Unpack the PhpMVC_Tags example archive to a directory within the Web root of the host server. Perhaps something like: C:/WWW/PhpMVC-Tags

Review and modify the application and framework settings as discussed above.

To test the example application, browse to the example index file, perhaps something like: http://localhost/PhpMVC-Tags/Index.html, and follow the links.

Appendix A: The ViewResources Configuration Class

The ViewResourcesConfig class represents the configuration information of a <view-resource> element in an php.MVC application configuration file.

The table below lists the ViewResourcesConfig class properties, the item description and default value:

ViewResourcesConfig Class Properties

Name	Description	Default Value
$appTitle	The application title	'My Web Application'
$appVersion	The application version	'1.0'
$copyright	The copyright notice	'Copyright © YYYY My Name. All rights reserved.'
$contactInfo	The contact information	'webmaster@myhost.com'
$processTags	Do we run the template engine processor (boolean)	False
$compileAll	Force compile pages (boolean)	False
$tagL	The left tag identifier	'<@'
$tagR	The right tag identifier	'@>'
$tplDir	The view resource templates directory	'./WEB-INF/tpl'
$tplDirC	The compiled templates directory	'./WEB-INF/tpl_C'
$extC	The compiled file notation. Eg: "pageContent.ssp[C]"	'C'
$maxFileLength	The maximum size of the template files allowed, in bytes (integer)	250000
$tagFlagStr	Indicates tag template file(s) to be pre-processed. Eg: "myPage.ssp	'.ssp'
$tagFlagCnt	The number of trailing filename characters to sample (".ssp" = -4)	-4



Copyright © 2006 John C. Wildenauer. All rights reserved.