QuickTemplate

Version 1.1 - Beta

Author: Stefan Bocskai
Romania, Cluj-Napoca - May 2000

ABOUT

QuickTemplate is a PHP extension for mananging templates and performing multi level variable and block interpolation.

What is a template?
A template is a text file in html format (or other). The templates are very usefull because you can define dynamic parts of a page by blocks and sub-blocks. So, for example, you could create tables with multiple rows by defining the row as a block. These blocks accept variables defined by user or predefined (as the current time or date), which are interpolated in the context of the block when the block is parsed.

Why QuickTemplate ?
QuickTemplate class can manage a multi-level template. So, you can define blocks and multi-level nested blocks. There is a real objectual structure of the blocks. You must specify the root of the template (the block that contains the others blocks), but it's not necessary to be the top level block of the template. You can choose other (lower level) block as the root of the template, and the parsing is started from this point.
Multi-level variables can be defined by the user. A variable like {MYDATA.NAME} or {MYDATA.AGE} means that with "MYDATA" is associated an array with the keys "NAME" or "AGE" etc.. But there are no limits to the number of levels.
Some defaults variables are defined: like date, time, self url, auto-increment etc.

Public functions

Constructor :

function QuickTemplate($misc, $part="main", $flag=0)

Description:
The constructor of the class. This function creates an instance of the class and initialises the incapsulated data. For external use do not use the flag flag, this flag is used in internal call of the function.

Parameters:
$misc (string)
The name of the template (text file) which need to be parsed.

$part (string)
The first block of the template, the root of the block's structure. It's not necessary to be the first level block. The template is parsed begining from this block. If not sent the default value is "main"

$flag
Not used. (For internal use only)

Returned value:
As a constructor, returns nothing :-(^)

Example:
$tpl = new QuickTemplate("./templates/main.tpl", "main");

Assignements :

function Assign($name, $val)
or
function Assign($name)

Description:
There are two ways to assign a value to the varioable that apperas in the template.First,by specifying the name and the value as arguments of the function. The value could be a simple value or an array (see ex. 1).
The second way is to specifyng as a single argument of the this function an assciative array (see ex. 2). The result is the same as making more simple assignements.

Parameters:
$name (string)
The name of the variable that appears in the template or an associative array.

$val (string / array)
This value must be specified if the first argument $name is not an associative array. If this is a simple value (string) the name $name is associated with this value. If this argument is an associative array, a complex association is made (see ex. 3).

Returned value:
Nothing to return. :-(^)

Examples:
example 1: $tpl->Assign("TITLE_OF_PAGE","First Example");
example 2: $tpl->Assign(array("TITLE_OF_PAGE" => "Second examle","MY_NAME" => "John Smith"));
example 3: $tpl->Assign("FULL_NAME", array("FIRST_NAME" => "John", "LAST_NAME" => "Smith"));

In the last example the variables that should appear in the template are: {FULL_NAME.FIRST_NAME} or {FULL_NAME.LAST_NAME}. (See variables for more information)

Null strings and blocks:

function SetNullString($nullstring)

Description:
With this function you can set the String that will appear if any variable is empty. You can set the "NullString" runtime as "Empty value", "0.00%", " " or "";

Parameters:
$nullstring (string)
Any string that you want.

Returned value:
Nothing to return. :-(^)

Examples:
$tpl->SetNullString("");
$tpl->SetNullString("0");
$tpl->SetNullString("0.00%");
$tpl->SetNullString("Empty value");
$tpl->SetNullString(" ");

function DefaultBlockValue($part, $value=" ")

Description:
You can set the text that you want to appear if a block of template is not parsed, is cleared or is empty.

Parameters:
$part (string)
This is a refernce to a block. (see Block Reference for more info.)
$value (string)
The text that will appear if the conntent of block is empty.

Returned value:
Nothing to return. :-(^)

Examples:
$tpl->DefaultBlockValue("main.table.rows", "There are no rows!");

Resetting the blocks:

function Reset($part)

Description:
This function sets to empty the text associated with a block; There's no need to Reset a unparsed block.

Parameters:
$part (string)
$part is a refference to a block (See Block Refference for more info.)

Examples:
$tpl->Reset("main.table.rows");

Auto-increment:

function SetAutoincrement($part, $start_value, $increment=1)

Description:
Sets the start value and the increment value of the auto-increment variable of the block. (see Defaults variables for more details)

Parameters:
$part (string)
$part is a refference to a block (See Block Refference for more info.)

$start_value (integer)
Value from which start the incrementation of specified block. $increment (integer)
Value with wich is incremented the auto-increment variable.

Examples:
$tpl->SetAutoincrement("main.table.rows",1);
That means that the incrementation begin with 1 (each value encreased with 1 by default)

$tpl->SetAutoincrement("main.table.rows",0,100);
That means that the incrementation begin with 0 (each value encreased with 100)

function GetAutoincrement($part)

Description:
Gets the current value of the incrementation. (see Defaults variables for more details)

Parameters:
$part (string)
$part is a refference to a block (See Block Refference for more info.)

Examples:
$increment_value = $tpl->GetAutoincrement("main.table.rows");
The function will return the current value of incrementation for specified block.

Parse:

function parse($part)

Description:
This function replaces the current values of the variables of a block, and the child blocks; the results are stored into a value associated with the block (in append mode). After parsing a block all of associated values of his child-blocks are reseted. If any child-block has an empty value associated it is replaced with the value set for this block by DefaultBlockValue function. Any other value from a block that is not a child-block is replaced with the current setting of NullString
TODO: a specific "NullString" for every variable of the template.

Parameters:
$part (string)
$part is a refference to a block (See Block Refference for more info.)

Examples:
This example creates from a template a page that contains two tables with 2 and 3 rows.
... assignements ...
$tpl->parse("main.table.rows"); //first row of first table
... assignements ...
$tpl->parse("main.table.rows"); //second row of first table
$tpl->parse("main.table"); //parsing first table
... assignements ...
$tpl->parse("main.table.rows"); //firs row of second table
... assignements ...
$tpl->parse("main.table.rows"); //second row of second table
... assignements ...
$tpl->parse("main.table.rows"); //third row of second table
$tpl->parse("main.table"); //parsing second table
$tpl->parse("main");

function Parsed($part)

Description:
Parsed returns true if the specified block was already parsed, otherwise returns false. Parse returns false if his parent was parsed before the call of this function. Returns false if the block was reseted.

Parameters:
$part (string)
$part is a refference to a block (See Block Refference for more info.)

Returns:

The function returns TRUE or FALSE.

Examples:
if ($tpl->Parsed("main.table.rows");
$tpl->Parse("main.table.error");

Printing templates / blocks:

function quickText($part)

Description:
quickText returns the content of a value associated with a specified block by $part. You can refer directly to a sub-block or to the main block of the template. The function is usually used after the block is parsed at least once. If the value is empty the result is not affected by the value set with DefaultBlockValue function.

Parameters:
$part (string)
$part is a refference to a block (See Block Refference for more info.)

Returns:

The function returns the current content of the value associated with the block.

Examples:
echo $tpl->quickText("main.table.rows");
echo $tpl->quickText("main");

function quickPrint($part)

Description:
quickPrint print the result of quickText of a specified block. See quickText.

Parameters:
$part (string)
$part is a refference to a block (See Block Refference for more info.)

Examples:
$tpl->quickPrint("main.table.rows");
$tpl->quickPrint("main");

Variables:

The variables of a template must be between brackets (ex.:"{TITLE}"). Allowed chars for the name of a variable are: a-z, A-Z, 0-9, _.
But there are some new rules for this class. If the variable is associated with a simple value (string, number) the variable appears in the template between breackets:
{TITLE_OF_THE_PAGE}
There are no limits of the lenght of a variable name.

If with a variable is associated an array then the variable cannot appear in the template. But here are the best point: you can refer directly the key of the array in the template. So, we made the next assign :
$data = array("NAME" => "John Smith", "AGE" => 23, "ADDRESS" => "Romania ...");
$tpl->Assign("MYDATA", $data);

You can use now in the template this variables:
{MYDATA.NAME}
{MYDATA.AGE}
{MYDATA.ADDRESS}

There are some default values. This values are prefixed by "DEFAULTS". For now are available the following values:
{DEFAULTS.DATE}
{DEFAULTS.TIME}
{DEFAULTS.SELFURL}
{DEFAULTS.AUTOINCREMENT} (see Auto-increment)
{DEFAULTS.VERSION} // Version of class
(I'm wainting for any other suggestions ...)

Block Reference:

Any block can be refered directly. Let's say that a block named "row" is a child of a block "table" and this block is a child of the block named "main". We can refer now the row block by the following string "main.table.row". If the reference string is not correctly formated the function that processes the refernce will verify the structure and will return an error.

Examples:
$tpl->SetAutoincrement("main.table.rows", 1,10);
$tpl->parse("main.table.rows");
$tpl->quickPrint("main.table.rows");

Short Example:

The Template :(file name: first_example.tpl)

<!-- BEGIN BLOCK: main -->

<h1>This is a test of {DEFAULTS.VERSION} writed by {MYNAME}</h1>
The location of this file is: {DEFAULTS.SELFURL}<br>
<hr>

 <!-- BEGIN BLOCK: table -->
 <table border="1">
 <tr>
  <td>Crt.no.</td><td>Name</td>
  <td>Mark</td><td>Class room</td>
 </tr>

  <!-- BEGIN BLOCK: row -->
    <tr>
     <td>{DEFAULTS.AUTOINCREMENT}</td>
     <td>{DATA.NAME}</td>
     <td align="right">{DATA.MARK}</td>
     <td>{CLASSROOM}</td>
    </tr>
  <!-- END BLOCK: row -->
  <!-- BEGIN BLOCK: error -->
   <tr><td colspan="4"><font color="red">
   No students in class {CLASSROOM}
   </font></td></tr>
  <!-- END BLOCK: error -->

 </table>
 <!-- END BLOCK: table -->

<p align="right">
Current time <b>{DEFAULTS.TIME}</b><br>
Date: <b>{DEFAULTS.DATE}</b><br>
<p>

<!-- END BLOCK: main -->

The source file :

<?

require ("QuickTemplate.php3");

$tpl = new QuickTemplate("first_example.tpl");

$MARKS["John"] = 10;
$MARKS["Michael"] = 9;
$MARKS["Bob"] = 7;
$MARKS["Robert"] = 8;
$MARKS["Jane"] = 7;
$MARKS["Alice"] = 9;
$MARKS["David"] = 10;
$MARKS["James"] = 8;
$MARKS["Toni"] = 7;
$MARKS["Bebe"] = 9;

$CLASSES["101A"] = array("John", "Robert", "Jane");
$CLASSES["101B"] = array("Bob", "Alice", "Bebe", "Toni");
$CLASSES["100C"] = array("Michael", "David", "James");
$CLASSES["100D"] = array();

$tpl->SetNullString(" <b>-</b>");
$tpl->SetAutoincrement("main.table.row", 1);
$tpl->Assign("MYNAME", "Bebe");

while (list($Class, $Members) = each($CLASSES))
 {
  $tpl->Assign("CLASSROOM",$Class);
   if (gettype($Members) == "array")
    while (list($k, $member) = each($Members))
   {
    $MEMBERDATA = array(NAME => $member,
			MARK => $MARKS[$member]);

    $tpl->Assign("DATA", $MEMBERDATA);

    $tpl->parse("main.table.row");
   }

   if (!$tpl->Parsed("main.table.row"))
            $tpl->parse("main.table.error");

   $tpl->parse("main.table");
 }

$tpl->parse("main");

$tpl->quickPrint("main");

?>

Results:

This is a test of QuickTemplate V1.1B writed by Bebe
The location of this file is: /group/testes/teste_bebe1.phtml

Crt.no. Name Mark Class room

1 John 10 101A

2 Robert 8 101A

3 Jane 7 101A

Crt.no. Name Mark Class room

1 Bob 7 101B

2 Alice 9 101B

3 Bebe 9 101B

4 Toni 7 101B

Crt.no. Name Mark Class room

1 Michael 9 100C

2 David 10 100C

3 James 8 100C

Crt.no. Name Mark Class room
No students in class 100D

Current time 13:41 PM
Date: Tuesday 09 May 2000

Crt.no.	Name	Mark	Class room
1	Bob	7	101B
2	Alice	9	101B
3	Bebe	9	101B
4	Toni	7	101B