<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<TITLE>Template Class</TITLE>
<LINK REL="STYLESHEET" MEDIA="screen" HREF="documentation.css" TYPE="text/css">
</HEAD>
<BODY>
<H1 CLASS="center background border">Template Class</H1>
<DIV CLASS="background-light border">
<H2>Contents</H2>
<TABLE BORDER="0">
<TR>
<TD>
<UL>
<LI>Installation</LI>
<LI>Main Usage</LI>
<LI>Other functions</LI>
<LI><INCLUDE> tag</LI>
<LI>Loop Code</LI>
<LI>Bugs</LI>
<LI>History</LI>
<LI>License</LI>
</UL>
</TD>
</TR>
</TABLE>
</DIV>
<DIV CLASS="nocenter padding background-light border">
<H2>Installation</H2>
<P>
Simply bung the class file somewhere where your script can include() it,
and then include() it.
</P>
</DIV>
<DIV CLASS="nocenter padding background-light border">
<H2>Main Usage</H2>
<P>
There are three main methods (functions) to the template engine, (engine hmmmm? sounds good).
There are of course other methods that can and indeed have to be accessed,
but these 3 are the real meat of the class.
</P>
<!-- parse() -->
<P>
<CODE><B><I>void</I> parse(<I>string</I> file identifier)</B></CODE>:
</P>
<P>
This inserts the values of all the variables that have been register()ed (see further down)
into the template. Obviously the variable must be in the template. To parse multiple files in one
call, the argument can be a comma seperated string of file ids.<BR>
<B>05/08/2000</B> This function also processes any <INCLUDE> tags in the specified file (see
section on includes).
</P>
<!-- parse_loop() -->
<P>
<CODE><B><I>void</I> parse_loop(<I>string</I> file identifer, <I>string</I> array name)</B></CODE>:
</P>
<P>
Note that the second argument is the array NAME! Not the array itself. The function takes an
array (which has to be in the format described below) and substitutes the "loop code" (see later)
for the data in the array. Difficult to describe, (at least, when half drunk) the format of the
array is like so:
</P>
<PRE>
+---------- This is the row number, starting at zero.
|
| +--- This is the column name.
| |
| |
$array[0]['column_1'] Contains data for row 1, column 1.
$array[0]['column_2'] Contains data for row 1, column 2.
$array[0]['column_3'] Contains data for row 1, column 3.
$array[1]['column_1'] Contains data for row 2, column 1.
$array[1]['column_2'] Contains data for row 2, column 2.
$array[1]['column_3'] Contains data for row 2, column 3.
</PRE>
<P>
See. Makes perfect sense. The column names should correspond to entries in the template file.
Check the example scripts if you're still unsure.
</P>
<!-- parse_sql() -->
<P>
<CODE><B><I>void</I> parse_sql(<I>string</I> file identifier, <I>string</I> result set name)</B></CODE>:
</P>
<P>
Very similar to the above, but instead of using an array for the data, it uses a mysql result set.
Again, pass the function the name of the result set, and not the result set itself, and as before it
replaces the "loop code" (see later) with the data from the result set. The field names must
correspond with what is in the template.
</P>
<!-- parse_pgsql() -->
<P>
<CODE><B><I>void</I> parse_pgsql(<I>string</I> file identifier, <I>string</I> result set name)</B></CODE>:
</P>
<P>
Basically the above function but parses Postgres result sets instead of MySQL. This function was contributed
by Ovidiu Eftimie.
</P>
<P>
<B>NB:</B> For the above three functions the array/result set variables should be lowercase.
</P>
</DIV>
<DIV CLASS="nocenter padding background-light border">
<H2>Other functions</H2>
<!-- load_file() -->
<P>
<CODE><B><I>void</I> load_file(<I>string</I> file identifier, <I>string</I> file name)</B></CODE>:
</P>
<P>
This, (as you may well have guessed), simply loads a template file into the object so that we may
use it. The file identifier is just that, and is what is used to refer to the file from now on, much
like in FastTemplate. The file identifier is necessary so that multiple templates are possible.
</P>
<PRE>
$tpl = new template;
$tpl->load_file('header', 'header.html');
$tpl->load_file('main', 'your.template.html');
$tpl->load_file('footer', 'footer.html');
$tpl->register('header', 'title');
$tpl->register('main', 'var1, var2, var3');
$tpl->register('footer', 'credits');
$tpl->parse('header, main, footer')
$tpl->print_file('main');
</PRE>
<!-- set_identifiers() -->
<P>
<CODE><B><I>void</I> set_identifiers(<I>string</I> beginning, <I>string</I> end)</B></CODE>:
</P>
<P>
Enables you to determine what identifies a "variable" in the template file. Defaults to "{" and "}",
so in a template file {example} would be replaced with the contents of the variable $example. An example:
</P>
<PRE>
$tpl = new template;
$tpl->load_file('main', 'your.template.html');
$tpl->register('main', 'var1, var2, var3');
$tpl->set_identifiers('{{', '}}');
$tpl->parse('main')
$tpl->print_file('main');
</PRE>
<!-- register() -->
<P>
<CODE><B><I>void</I> register(<I>string</I> file identifier, <I>mixed</I> variable names))</B></CODE>:
</P>
<P>
Registers a variable so that later, the parse() function will insert it into the template file. The second
arugment can be either a comma seperated string containing the variable <I>names</I> (not the variables themselves),
or it can be an array containing variable names. If it is an array the variable names must be the values, and
not the keys. The arrays can be associative, but it is still the values that are registered. Nested arrays will
be traversed. For example, all the below register $var1, $var2 and $var3:
</P>
<UL>
<LI>$obj->register('id', 'var1, var2, var3');</LI>
<LI>$obj->register('id', array('var1', 'var2', 'var3'));</LI>
<LI>$obj->register('id', array('var1', array('var2', 'var3')));</LI>
</UL>
<P>
An example:
</P>
<PRE>
$tpl = new template;
$tpl->load_file('main', 'your.template.html');
$tpl->register('main', 'var1');
$tpl->register('main', array('var2', 'var3'));
$tpl->parse('main')
$tpl->print_file('main');
</PRE>
<!-- print_file() -->
<P>
<CODE><B><I>void</I> print_file(<I>string</I> file identifer)</B></CODE>:
</P>
<P>
After all processing is done, use this script to print the template. Multiple templates can be printed
at once by comma seperating the identifiers. An example:
</P>
<PRE>
$tpl = new template;
$tpl->load_file('main', 'your.template.html');
$tpl->register('main', 'var1, var2, var3');
$tpl->parse('main')
$tpl->print_file('main');
</PRE>
<!-- return_file() -->
<P>
<CODE><B><I>string</I> return_file(<I>string</I> file identifier)</B></CODE>:
</P>
<P>
After all processing is done, use this script to return the html code that has been generated. Can be
useful for post-processing or (for example) inserting the template into an email. Multiple templates
can be returned at once by comma seperating the identifiers. An example:
</P>
<PRE>
$tpl = new template;
$tpl->load_file('main', 'your.template.html');
$tpl->register('main', 'var1, var2, var3');
$tpl->parse('main')
$output = $tpl->return_file('main');
</PRE>
<!-- pprint() -->
<P>
<CODE><B><I>void</I> pprint(<I>string</I> file identifer [, <I>mixed</I> variable names])</B></CODE>:
</P>
<P>
This function acts as an alternative to calling register(), parse() and then print_file() and will call
all those functions for you. The second argument can be a string or an array, as with the register()
function and is passed directly to that function. This function was contributed by Bruce Christensen. An example:
</P>
<PRE>
$tpl = new template;
$tpl->load_file('main', 'your.template.html');
$tpl->pprint('main', 'var1, var2, var3');
</PRE>
<!-- pget() -->
<P>
<CODE><B><I>void</I> pget(<I>string</I> file identifier [, <I>mixed</I> variable names])</B></CODE>:
</P>
<P>
This function acts as an alternative to calling register(), parse() and then return_file() and will call
all those functions for you. The second argument can be a string or an array, as with the register()
function and is passed directly to that function. This function was contributed by Bruce Christensen. An example:
</P>
<PRE>
$tpl = new template;
$tpl->load_file('main', 'your.template.html');
$output = $tpl->pget('main', 'var1, var2, var3');
</PRE>
<!-- pprint_file() -->
<P>
<CODE><B><I>void</I> pprint_file(<I>string</I> filename [, <I>mixed</I> variable names])</B></CODE>:
</P>
<P>
This function acts as an alternative to calling load_file(), register(), parse() and then print_file()
and will call all those functions for you. When loading the file it will find a spare file_id, use it, and
unset() it when finished. The second argument can be a string or an array, as with the register() function
and is passed directly to that function. If you have loops to process, you should not use this function.
This function was contributed by Bruce Christensen. An example:
</P>
<PRE>
$tpl = new template;
$tpl->pprint_file('your.template.html', 'var1, var2, var3');
</PRE>
<!-- pget_file() -->
<P>
<CODE><B><I>void</I> pprint_file(<I>string</I> filename [, <I>mixed</I> variable names])</B></CODE>:
</P>
<P>
This function acts as an alternative to calling load_file(), register(), parse() and then return_file()
and will call all those functions for you. When loading the file it will find a spare file_id, use it, but
will NOT unset() it when finished. The second argument can be a string or an array, as with the register()
function and is passed directly to that function. If you have loops to process, you should not use this
function. This function was contributed by Bruce Christensen. An example:
</P>
<PRE>
$tpl = new template;
$output = $tpl->pget_file('your.template.html', 'var1, var2, var3');
</PRE>
</DIV>
<DIV CLASS="nocenter padding background-light border">
<H2><INCLUDE> tag</H2>
<P>
The <INCLUDE> tag can make your life much easier by enabling you to include things like header/footer
files in your templates. An example is below:
</P>
<P>
<INCLUDE FILENAME="templates/header.html">
</P>
<P>
The case of the tag and attribute name doesn't matter, but the spacing does. There must be precisely
one space between "include" and "filename" and no spaces either side of the equals sign or between the
last double quote and greater than sign. Basically stick to the above and you'll be fine. Obviously
the string inside the quotes is the filename, and must point to a valid file. If the file is not
found an error will be printed in its' place.
</P>
<P>
<B>IMPORTANT:</B> The path of the file to be included should be relative to the php script that runs the
template script stuff, and not the template with the tag in. Multiple include ttags can be in a
template, and even multiple include tags pointing to the same file.
</P>
</DIV>
<DIV CLASS="nocenter padding background-light border">
<H2>Loop Code</H2>
<P>
What is loop code then? Loop code is the piece of code that gets repeated when parse_loop(), parse_sql() or parse_pgsql()
are run. It could be for example a table row in HTML, which gets repeated x number of times depending
on how many rows there are in the array or sql result set, (for the structure of the array, see the diagram further up).
Loop code has to be defined in a particular way:
</P>
<PRE>
<LOOP NAME="your_name">
<Code to be repeated>
</LOOP NAME="your_name">
</PRE>
<P>
The beginning tag defines the start of the loop code, and the name is the name of the array or result set
it is assigned to. The ending tag simply signifies the end of the loop code. Here is an example of loop
code in a table:
</P>
<PRE>
<TABLE BORDER="0" BGCOLOR="#000000">
<TR>
<TH BGCOLOR="#DDDDDD">Column 1</TH>
<TH BGCOLOR="#DDDDDD">Column 2</TH>
<TH BGCOLOR="#DDDDDD">Column 3</TH>
</TR>
<LOOP NAME="table_rows">
<TR>
<TD BGCOLOR="#DDDDDD">{column_1}</TD>
<TD BGCOLOR="#DDDDDD">{column_2}</TD>
<TD BGCOLOR="#DDDDDD">{column_3}</TD>
</TR>
</LOOP NAME="table_rows">
</TABLE>
</PRE>
<P>
Here, the table has the usual structure. First the header row is static. Then, the data row is loop code.
What will happen once this is parsed is that the loop code gets repeated once for every row in the array
or result set. The {column_1} etc will also be replaced with the appropriate data for that column. Also,
the loop tags will be removed. A good example of this is the complete-script.php script (which goes with
the complete-template.html template file). Compare the before and after and you should easily understand it.
</P>
</DIV>
<DIV CLASS="nocenter padding background-light border">
<H2>Performance</H2>
<P>
*** See History for updated performance info ***
</P>
<P>
Still with me? Good, as that's all the hard work done.<BR>
The performance of the engine (still sounds good...) is very good, primarily due to the fact that regular
expression functions (ereg, preg_match etc) are not used.
</P>
<P>
Compared against FastTemplate, my own
(admittedly quite basic) benchmarks came out consistently around 30% faster. This was done by taking
timestamps using microtime() just before instantiating the template object and just after printing the
results, doing a bit of jiggery-pokeryŽ with the results and inserted into a db. The average of twenty
times was taken and then compared.
</P>
<P>
It also came out as 60% faster than another template routine, which
is not an object or function, simply an include file, but it's not publicly accessible so it doesn't
mean that much.
</P>
</DIV>
<DIV CLASS="nocenter padding background-light border">
<H2>Bugs</H2>
<P>
Not bloody likely.
</P>
</DIV>
<DIV CLASS="nocenter padding background-light border">
<H2>History</H2>
<P>
<B>13/08/2000 - Version 1.3</B><BR>
Added five new functions:
</P>
<UL>
<LI>parse_pgsql()</LI>
<LI>pprint()</LI>
<LI>pget()</LI>
<LI>pprint_file()</LI>
<LI>pget_file()</LI>
</UL>
<P>
These new functions make the class very much more useful, accessible and easy to use. Also
made some minor alterations to existing functions, Eg. parse() can now accept a comma seperated
string of file_ids to parse multiple templates in one call.
</P>
<P>
<B>05/08/2000 - Version 1.23</B><BR>
Added <INCLUDE> tag. So you can include other files in your template, eg. header/footer files.
</P>
<P>
<B>11/07/2000 - Version 1.13</B><BR>
You can now have two loops with exactly the same loop code in one template file.
</P>
<P>
<B>25/06/2000 - Version 1.12</B><BR>
Altered load_file() so it reads the file using fread() instead of file(). Marginally faster.
</P>
<P>
<B>04/06/2000 - Version 1.1</B><BR>
Altered parse_loop and parse_sql so that they don't have to go through every line of the file
they're parsing. The complete example (single template) is now more than twice as fast,
(0.008 vs 0.017 on RHL 6.1, Apache 1.3.12, Php 4.0.0, P166, 32Mb).
</P>
<P>
<B>23/05/2000 - Version 1.0</B><BR>
Initial release.
</P>
</DIV>
<DIV CLASS="nocenter padding background-light border">
<H2>License</H2>
<P>
Postcard-ware. If you use this utility then I'd appreciate a postcard from ya. :)<BR>
Otherwise, it's free, be grateful, don't whinge, and don't sue me if it screws your system.
</P>
<P CLASS="center" ALIGN="CENTER">
<A HREF="http://validator.w3.org/check/referer">
<IMG SRC="http://validator.w3.org/images/vh40" BORDER="0" ALT="Valid HTML 4.0!" HEIGHT="31" WIDTH="88">
</A>
<A HREF="http://jigsaw.w3.org/css-validator/">
<IMG SRC="http://jigsaw.w3.org/css-validator/images/vcss.gif" BORDER="0" ALT="Valid CSS 1.0">
</A>
</P>
</DIV>
</BODY>
</HTML>
|
Download
