NAME
ZM::Template - Merges runtime data with static HTML or Plain Text
template file.
VERSION
Template.pm v 0.1.0
SYNOPSIS
How to merge data with a template.
The template :
parser Example 1
My name is __firstname__ __surname__ but my friends call me __nickname__.
The code :
use HTMLTMPL;
# Create a template object and load the template source.
$templ = new HTMLTMPL;
$templ->src('example1.html');
# Set values for tokens within the page
$templ->surname('Smyth');
$templ->firstname('Arthur');
$templ->nickname('Art!');
# Send the merged page and data to the web server as a standard text/html mime
# type document
$templ->output('Content-Type: text/html');
Produces this output :
parser Example 1
My name is Arthur Smyth but my friends call me Art!.
DESCRIPTION
In an ideal web system, the HTML used to build a web page would be kept
distinct from the application logic populating the web page. This module
tries to achieve this by taking over the chore of merging runtime data
with a static html template.
The ZM::Template module can address the following template scenarios :
* Single values assigned to tokens
* Multiple values assigned to tokens (as in html table rows)
* Single pages built from multiple templates (ie: header, footer, body)
* html tables with runtime determined number of columns
An template consists of 2 parts; the boilerplate and the tokens (place
holders) where the variable data will sit.
A token has the format __tokenName__ and can be placed anywhere within
the template file. If it occurs in more than one location, when the data
is merged with the template, all occurences of the token will be
replaced.
My name is __userName__ and I am aged __age__.
My friends often call me __nickName__ although my name is __userName__.
When an html table is being populated, it will be necessary to output
several values for each token. This will result in multiple rows in the
table. However, this will only work if the tokens appear within a
repeating block.
To mark a section of the template as repeating, it needs to be enclosed
within a matching pair of repeating block tokens. These have the format
__x_blockName__. They must always come in pairs.
and I have the following friends
__x_friends__
| __friendName__ | __friendNickName__ |
__x_friends__
For interleave data in loop used __z_ token
and I have the following friends
__x_friends__
| __friendName__ | __friendNickName__ |
__z_friends__
| __friendName__ | __friendNickName__ |
__x_friends__
Template engine understand inner loops like this
List of companies:
__x_companies__
Company name: __name__
Company address: __address__
Company e-mails:
__x_emails__
__email__
__x_emails__
Company web: __web__
__x_companies__
METHODS
src($)
The single parameter specifies the name of the template file to use.
srcString($)
If the template is within a string rather than a file, use this method
to populate the template object.
output(@)
Merges the data already passed to the HTMLTMPL instance with the
template file specified in src(). The optional parameter is output
first, followed by a blank line. These form the HTTP headers.
htmlString()
Returns a string of html produced by merging the data passed to the
HTMLTMPL instance with the template specified in the src() method. No
http headers are sent to the output string.
listAllTokens()
Returns an array. The array contains the names of all tokens found
within the template specifed to src() method.
tokenName($)
Assigns to the 'tokenName' token the value specified as parameter.
tokenName($$)
Assigns to the 'tokenName' token, within the repeating block specified
in 2nd parameter, the value specified as the first parameter.
EXAMPLES
Example 1.
A simple template with single values assigned to each token.
The template :
parser Example 1
My name is __firstname__ __surname__ but my friends call me __nickname__.
The code :
use HTMLTMPL;
# Create a template object and load the template source.
$templ = new HTMLTMPL;
$templ->src('example1.html');
# Set values for tokens within the page
$templ->surname('Smyth');
$templ->firstname('Arthur');
$templ->nickname('Art!');
# Send the merged page and data to the web server as a standard text/html mime
# type document
$templ->output('Content-Type: text/html');
Produces this output :
parser Example 1
My name is Arthur Smyth but my friends call me Art!.
Example 2
Produces an html table with a variable number of rows.
The template :
Example 2 - blocks
__x_details__
| __id__ |
__name__ |
__desc__ |
__x_details__
__x_customer_det__
- __customer__
__x_customer_det__
The code :
use HTMLTMPL;
# Create the template object and load it.
$templ = new HTMLTMPL;
$templ->src('example2.html');
# Simulate obtaining data from database, etc and populate 300 blocks.
for ($i=0; $i<300; $i++)
{
# Ensure that the token is qualified by the name of the block and load
# values for the tokens.
$templ->id($i, 'x_details');
$templ->name("the name is $i", 'x_details');
$templ->desc("the desc for $i", 'x_details');
}
for ($i=0; $i<4; $i++)
{
$templ->customer("And more $i", 'x_customer_det');
}
# Send the completed html document to the web server.
$templ->output('Content-Type: text/html');
Example 5.
Uses 2 seperate templates to produce a single web page :
The overall page template :
Example 5 - sub templates
Surname : __surname__
First Name : __firstname__
My friends (both of them) call me : __nickname__
Now to include a sub template...
__guts__
And this is the end of the outer template.
The subtemplate which will be slotted into the 'guts' token position :
The code :
use HTMLTMPL;
# Create a template object and load the template source.
my($templ) = new HTMLTMPL;
$templ->src('example5.html');
# Set values for tokens within the page
$templ->surname('Smyth');
$templ->firstname('Arthur');
$templ->nickname('Art!');
my $subTmpl = new HTMLTMPL;
$subTmpl->src('example5a.html');
$subTmpl->widget('this is widget');
$subTmpl->wodget('this is wodget');
$templ->guts($subTmpl->htmlString);
# Send the merged page and data to the web server as a standard text/html mime
# type document
$templ->output('Content-Type: text/html');
HISTORY
Oct 2003 Version 0.1.0 Added __z_ token type
Oct 2003 Version 0.0.3 First release
AUTHOR
Zet Maximum ltd.
Maxim Kashliak
Aleksey Ivanov
http://www.zmaximum.ru/
http://perl.zmaximum.ru