PHP Template Class

Introduction

This PHP class provides you with simple, yet powerful template functionality for your own PHP scripts.

License

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.

Requirements

The Template class requires a PHP 4.0 built with Perl regular expressions (should be standard).

Usage

Using the Template class is pretty straightforward. Load a template file, set variables and finally print the whole thing:

      $t = new Template("mytemplate.ihtml");
      $t->setVar("var", "variable content");
      print $t->toString();

The template file mytemplate.ihtml could look as follows:

      <p>A static paragraph.</p>
      <p>And here a paragraph with {var}</p>

This excerpt loads the template file mytemplate.ihtml. The call to the setVar function replaces the string {var} in the template file with the value Variable value. The toString call eventually converts the template to a textual representation that is then printed.

Repetitions

The Template class provides support for repeating sections of the output data. This is e.g. useful when data needs to be presented in a list. The sections that can be repeated need to be marked as blocks using HTML comments in the template file. A template showing a list of users and their age in an HTML table could look as follows:

      <table>
      <!-- startBlock(user) -->
      <tr>
      <td>{name}</td>
      <td>{age}</td>
      </tr>
      <!-- endBlock(user) -->
      </table>

The following code makes use of this repeated section:

      /* 1. Set individual variables */
      $t->gotoNext("user");
      $t->setVar("user.name", "Alice");
      $t->setVar("user.age", "25");
      $t->gotoNext("user");
      $t->setVar("user.name", "Bob");
      $t->setVar("user.age", "28");

      /* 2. Set an array */
      $a = array("name" => "Charly",
                 "age" => "30");
      $t->gotoNext("user");
      $t->setVar("user", $a);

      /* 3. Set an array of arrays */
      $a = array(array("name" => "Dan",
                       "age" => "23"),
                 array("name" => "Erica",
                       "age" => "27"),
                 array("name" => "Fred",
                       "age" => "32"));
      $t->setVar("user", $a);

If the list of users is empty, you may want to display an alternative text instead of just an empty table. This can be achieved as follows in the template:

      <table>
      <!-- startBlock(user) -->
      <tr>
      <td>{name}</td>
      <td>{age}</td>
      </tr>
      <!-- emptyBlock(user) -->
      <tr>
      <td colspan="2">No users.</td>
      </tr>
      <!-- endBlock(user) -->
      </table>

In order to sort the list of users by their name, the following template would is required:

      <table>
      <!-- startBlock(user,name) -->
      <tr>
      <td>{name}</td>
      <td>{age}</td>
      </tr>
      <!-- endBlock(user) -->
      </table>

Predefined Variables

The following variables are predefined:

{script}: contains the value of the $_SERVER["SCRIPT_NAME"] variable.
{sid}: contains the session_id().

Functions

The Template class does not only allow to simply replace variables in templates. It also offers a number of functions that can be used to control the output depending on the variable values:

{quotenl:var}: removes carriage returns and quotes newlines in {var}.
{quotejs:var}: removes carriage returns and quotes backslashes and newlines in {var}.
{quotexml:var}: replaces XML-specific characters (&, < and >) in {var}.
{csv:var}: formats {var} as CSV (quotes newlines and double quotes, removes carriage returns).
{base64:var}: inserts the base64-encoded value of {var}.
{url:var}: inserts the url-encoded value of {var}.
{format:var:fmt}: inserts sprintf(fmt, "{var}").
{date:var:fmt}: inserts date(fmt, "{var}").
{ifeq:var:a:b}: inserts b if {var} is equal to a.
{ifne:var:a:b}: inserts b if {var} is not equal to a.
{ifequal:a:b:c}: inserts c if a is equal to b.
{ifnequal:a:b:c}: inserts c if a is not equal to b.
{ifset:var:a}: inserts a if the variable {var} is set.
{ifnotset:var:a}: inserts a if the variable {var} is not set.
{iflast:a}: in a repetition, insert a if this is the last repetition.
{ifnotlast:a}: in a repetition, insert a if this is not the last repetition.
{ifnotfirst:a}: in a repetition, insert a if this is not the first repetition.
{ifoddposition:a}: in a repetition, insert a if this is an odd repetition.
{ifevenposition:a}: in a repetition, insert a if this is an even repetition.
{count0}: in a repetition, insert the current repetition number (0 based).
{count1}: in a repetition, insert the current repetition number (1 based).

Bugs

The Template class is SLOW because of the many calls to the preg_ functions. Sometime we will need to write a proper parser. Any volunteers?

$Id: README.html,v 1.3 2004/03/08 13:36:51 oli Exp $