                      Bilstone HTML Template Parser
                      =============================


How to use the parser.
----------------------

The parser removes the need for cgi programs to output any of the html tags
which make up an html page.

A cgi using the parser creates a template object and specifies the name of an
html source file to be used. It then assigns values to tokens within the
template and requests the populated template to be sent to the web server.


Example 1.
----------

(All of the examples can be found in the examples directory of the tar file.)


<html><head><title>parser Example 1</title></head>
<body bgcolor=beige>
My name is __firstname__ __surname__ but my friends call me __nickname__.
<hr>
</body>
</html>


The html template contains 3 tokens (firstname, surname and nickname). Each of
these can be assigned values by the cgi and will be replaced by these values
when the page is sent to the web server.

The cgi perl used to populate this template is below :


#!/usr/bin/perl -w

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');


The parser will set the values of the tokens and output the populated page.


Example 2.
----------

This uses a repeating set of data.


<html><head><title>Example 2 - blocks</title></head>
<body bgcolor=beige>
<table border=1>
__x_details__
<tr>
	<td>__id__</td>
	<td>__name__</td>
	<td>__desc__</td>
</tr>
__x_details__
</table>
<ul>
__x_customer_det__
	<li>__customer__</li>
__x_customer_det__
</ul>
<br>
<hr>
</body>
</html>


This template has a repeating 'block' of html within it. This allows for
multiple values of a token to produce lists, etc within web pages.

A block is delimited by a pair of tokens which are named as __x_<block id>__
The 'x' is a visual aid to highlight this is multi values.
In this example there are 2 repeating blocks (__x_customer_det_ and 
__x_details_).

The cgi to populate this is :


#!/usr/bin/perl -w

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');


When a token within a block is being assigned a value, you need to qualify
the name of the block to which it belongs.

This example produces a couple of tables, the first contains 300 rows and the
other 4.


Example 5.	(sub templates / inner templates)
----------

It is often useful to be able to 'nest' templates. For example, you may want to
have a header and footer to each page (but without using frames, etc).

Since version 1.10 this has been supported by using the new 'htmlString'
function. This function returns a string containing all the generated html for
the associated template. This string of html can then be inserted into any
other template(s).

An example :

To set up a header and footer for a page :

The overall page template would be :

<html>
<head><title>Example 5 - inner templates</title></head>
<body bgcolor=beige>
__header__

Welcome __username__ to the latest news. Please visit our sponsors (above) if
possible - it keeps us in business! :-)

__headlines__

<hr>
__footer__
</body>
</html>

The header template is :

<img src="/images/__sponsor_id__/ad.gif" width=400 height=80 border=0>
<h3>The Newspaper Stand</h3>


And the footer may be :

<i>Copyright The News People 2000</i>
<img src="/images/__sponsor_id__/ad.gif" width=400 height=80 border=0>


The perl to produce this is :

#!/usr/bin/perl
use strict;
use HTMLTMPL;

my $mainTmpl = new HTMLTMPL;
$mainTmpl->src('mainpage.html');

my $hdrTmpl = new HTMLTMPL;
$hdrTmpl->src('header.html');

my $footTmpl = new HTMLTMPL;
$footTmpl->src('footer.html');

$mainTmpl->username("Mr Ian Steel");
$mainTmpl->headline("Share market in plunge");

$hdrTmpl->sponsor_id("bilstone");
$footTmpl->sponsor_id("bilstone");

$mainTmpl->header($hdrTmpl->htmlString);
$mainTmpl->footer($footTmpl->htmlString);

$mainTmpl->output('Content-Type: text/html');








Ian Steel. (ian@bilstone.co.uk)
April 1999
