simple HTML Templating - API

Important: Since last (first) version, names of functions has changed a bit. They are now in lowercase, multi-word names were splited by underscore char. It means that, for example, name LoopSave has changed into loop_save. VarList stays as a one-word name, but in lower case.

Overview

This library is available in two versions written in two leading languages for dynamic web: PHP and ASP. Some other languages can be added in the future.

Requirements:

PHP version requires PHP 4 and higher. I've not tested it much yet but I've definitely used some functions available since version 4. It should work on all systems and servers that support PHP. If you want to know, it was written and tested on Windows 2000, PHP 4.3.0 on Apache 1.3.26.

ASP version is written in JScript running on IIS server coming with Windows 2000 Pro. VBScript seems to be more common for programming in ASP. I've chosen JScript because it's closer to me then VBScript. Developing VBScript version is at the top of TODO list of this project. If you are able to do it, feel free to join the development team at SourceForge.net.

How can I use the library?

Just include the file into your PHP or ASP code like this:

PHP:

require 'simpleht.php';
or
include 'simpleht.php';

(see PHP documentation on how to use require na include functions)

ASP:

<!--#include file="simpleht.asp"-->

OK, but how can I use it?

The engine provides two objects (classes) that contain functions (methods) to deal with the templating thing. One of them is aimed to handle processing of the template and the other can simplify creating of the list of variables and its values. Let's start with the more important one.

template object

This object handles processing the template. It has just important method:

process method

syntax:

string process(string tmpl_file, mixed var_list [, boolean abs_path])

This method reads content of the given template file, processes it and returns text of the final page. Processing means leaving out comments, replacing variables with their actual values and going though loops.

Parameters:
string tmpl_file - takes path to the template file. The path can be relative or absolute which is determined by the abs_path optional parameter (see description on abs_path parameter).
mixed var_list - this parameter takes list of variables. The values could be either an associative array or instance of varlist object (see varlist object description for more info on creating lists of variables).
boolean abs_path - optional parameter. It determines if the path given in tmpl_file parameter is relative or absolute. If abs_path is true the given path is considered absolute. Default value of this parameter is false, if you leave it out.

process method in fact reads the file, converts the variable list to associative array and passes it to process_text method and then return the result. The process_text method is considered private but you can use it if you need.

void process_text(input_text, variables_array)

This method takes text to process in input_text and list of variables in form of associative array. It processes the text but returns nothing. You have to read the result from processed variable, internal variable of the template object (like this: template_object_instance.processed in ASP/JScript or $template_obj_instance->processed in PHP).

varlist object

This object eases crating of variable lists. Instance of this object or associative array can be passed to the Process method of the Template object. varlist doesn't do anything specialbut helps you create the array with its methods.

set method

syntax:

void set(string var_name, mixed var_value)

This method stores any value given in var_value under variable name given in var_name. If the variable already exists, its value is changed to the given one. The passed value in var_value can be of any type. The most common will be string or number. To store data for creating loops it can also take arrays or instances of other varlist objects. To learn more about creating loops see description of loop methods.
Lists of variables are created using associative arrays. varlist actually uses such array to store values. If you don't want to use this object, you can create the lists by yourself. It's done like this:

General use of associative arrays:

list[var_name] = var_value

where list is variable of type array, var_name works as regular index that points to var_value.

The use is similar in PHP and ASP/JScript (PHP variables precede '$' character - $list)

list = new Array();
list["fruit1"] = "apple";
list["fruit2"] = "pear";

Now, if you pass list to the process method of the template object, it will replace template variables fruit1 (<== fruit1>) and fruit2 with strings apple and pear.

Loop methods

Before taking closer look at using these methods let's look at how are the loops created. Loops are stored as the normal variable name / value pair where variable name has to begin with '_' (underscore) character to identify the loop and value contain an array. It is two dimensional array that should look like this:

loop_list[pass][var_name] = var_value

The pass is numerical value that represents the Nth pass through the loop and the var_name / var_value pair stores data for that current pass. For example it can look like this in 5th cycle of the loop:

loop_list[4]["first_name"] = "John";

The loop_list variable is only temporal. You cannot pass it to the process function. To make the loop functional, you have to save the loop_list into the main list with variables. Like this:

list["_names"] = loop_list;

or using method set of varlist obj.:

listobj.set("_names", loop_list);

where _names identifies the loop and gives it unique name.

So, now the loop methods

varlist object provides three methods for creating Loops. Here they are:
loop_set - stores variable / value pair for current pass of the loop.
loop_save - saves the list of current pass with given pass number.
loop_end - finishes creating of the loop and returns an array with its data.

loop_set method

syntax:

void loop_set(string var_name, string var_value [, string loop_name])

Acts the same way as the set method. The only difference is in the optional loop_name which identifies name of the current loop. Why is it optional will be explained later on example.

loop_save method

syntax:

void loop_save([string loop_name])

This method must be called at the end of each loop after setting all variables. It stores previously set variables and prepares for new pass of the cycle.

loop_end method

syntax:

array loop_end([string loop_name])

loop_end method finishes setting data for the current loop, frees used resources and returns an array containing variable list of the current loop. This array should be passed to set method of the main varlist or to variable list of parent loop. It can look like this:

list.set("_loop1", list.loop_end("tmp_loop"))

So, why is the loop_name optional?

The loop_name parameter is needed to identify the current loop being created. This is important when you create one loop in another. But in one pass of the loop you will be setting more then one variable usually. In that case you can set the loop_name only in the first use of loop_set. The object will remember this name until you enter another one. More you can learn from the following example.
There's some default name set in the engine, so you actually don't have to use it when creating simple loops without loops within.

Example

This example will show how using varlist object differs from creating the variable list 'manually'. It will also show the basic usage of the loop methods.

First of all - the template file can look like this:

<html>
  <head>
    <title><== page_name></title>
  </head>
  <body>
    <h1><== page_name></h1>
	<h3><== description></h3>
	<== _loop_i>
	<== number_1><br>
	<== number_2>
	<blockquote>
	  <== _loop_j>
	  <p><== number_2_1><br>
	  <== number_2_2></p>
	  </== _loop_j>
	</blockquote>
	</== _loop_i>
  </body>
</html>

The first example showes how to create list of variables 'manualy' using associative array.

PHP

$list["page_name"] = "Random numbers";
$list["description"] = "loops demonstration";

for($i = 0; $i < 5; $i++)
{
  $loop_i[$i]["number_1"] = rand();
  $loop_i[$i]["number_2"] = rand();

  for($j = 0; $j < 5; $j++)
  {
    $loop_j[$j]["number_2_1"] = rand();
    $loop_j[$j]["number_2_2"] = rand();
  }
  $loop_i[$i]["_loop_j"] = $loop_j;
}
$list["_loop_i"] = $loop_i;

$t = new Template();
echo $t->Process("numbers.tmpl", $list);

ASP/JScript

list = new Array();
list["page_name"] = "Random numbers";
list["description"] = "loops demonstration";

loop_i = new Array();
for(i = 0; i < 5; i++)
{
  loop_i[i] = new Array();
  loop_i[i]["number_1"] = Math.random();
  loop_i[i]["number_2"] = Math.random();

  loop_j = new Array();
  for(j = 0; j < 5; j++)
  {
    loop_j[j] = new Array();
    loop_j[j]["number_2_1"] = Math.random();
    loop_j[j]["number_2_2"] = Math.random();
  }
  loop_i[i]["_loop_j"] = loop_j;
}
list["_loop_i"] = loop_i;

t = new Template();
Response.Write(t.Process("numbers.tmpl", list));

This example shows use of the varlist object.

PHP

$list = new varlist();

$list->set("page_name", "Random numbers");
$list->set("description", "loops demonstration");

for($i = 0; $i < 5; $i++)
{
  $list->loop_set("number_1", rand(), "loop_i");
  $list->loop_set("number_2", rand(), "loop_i");
  
  for($j = 0; $j < 5; $j++)
  {
    $list->loop_set("number_2_1", rand(), "loop_j");
    $list->loop_set("number_2_2", rand(), "loop_j");
    $list->loop_save($j, "loop_j");
  }
  $list->loop_set("_loop_j", $list->loop_end("loop_j"), "loop_i");
  $list->loop_save($i, "loop_i");
}
$list->set("_loop_i", $list->loop_end("loop_i"));

$t = new Template();
echo $t->Process("numbers.tmpl", $list);

ASP/JScript

list = new varlist();

list.set("page_name", "Random numbers");
list.set("description", "loops demonstration");

for(i = 0; i < 5; i++)
{
  list.loop_set("number_1", Math.random(), "loop_i");
  list.loop_set("number_2", Math.random(), "loop_i");
  
  for(j = 0; j < 5; j++)
  {
    list.loop_set("number_2_1", Math.random(), "loop_j");
    list.loop_set("number_2_2", Math.random(), "loop_j");
    list.loop_save(j, "loop_j");
  }
  list.loop_set("_loop_j", list.loop_end("loop_j"), "loop_i");
  list.loop_save(i, "loop_i");
}
list.set("_loop_i", list.loop_end("loop_i"));

t = new Template();
Response.Write(t.Process("numbers.tmpl", list));

The last example is the same as the previous one but the optional loop_name properites were left out where they are not necessary.

PHP

$list = new varlist();

$list->set("page_name", "Random numbers");
$list->set("description", "loops demonstration");

for($i = 0; $i < 5; $i++)
{
  $list->loop_set("number_1", rand(), "loop_i");
  $list->loop_set("number_2", rand());
  
  for($j = 0; $j < 5; $j++)
  {
    $list->loop_set("number_2_1", rand(), "loop_j");
    $list->loop_set("number_2_2", rand());
    $list->loop_save($j);
  }
  $list->loop_set("_loop_j", $list->loop_end(), "loop_i");
  $list->loop_save($i);
}
$list->set("_loop_i", $list->loop_end());

$t = new Template();
echo $t->Process("numbers.tmpl", $list);

ASP/JScript

list = new varlist();

list.set("page_name", "Random numbers");
list.set("description", "loops demonstration");

for(i = 0; i < 5; i++)
{
  list.loop_set("number_1", Math.random(), "loop_i");
  list.loop_set("number_2", Math.random());
  
  for(j = 0; j < 5; j++)
  {
    list.loop_set("number_2_1", Math.random(), "loop_j");
    list.loop_set("number_2_2", Math.random());
    list.loop_save(j);
  }
  list.loop_set("_loop_j", list.loop_end(), "loop_i");
  list.loop_save(i);
}
list.set("_loop_i", list.loop_end());

t = new Template();
Response.Write(t.Process("numbers.tmpl", list));

I know, it looks complicated but I believe it will be helpful, especially when creating loops with many variables. It surely shortens the code in ASP.

DOWNLOAD
last version: 0.2.1

» » news « «

changes.txt

2007-12-25:
Closed officially. Finally. See more

2004-03-19:
A small fix, see changelog.

2004-03-06:
Second version is comming after a while with many news.

2003-08-17:
First vesion is out!