HTML::Tempi - Perl extension for HTML templates

	use HTML::Tempi;
	tempi_init("template.html");
	set_var("some_var", "i was some_var");
	parse_block("MAIN");
	print tempi_out();
	tempi_free();

Tempi is a HTML template system. It's is written in C, using a flex generated scanner. That makes it (That's why it should be) faster than pure Perl template systems.

Tempi gives you access to these functions:

	int tempi_init (template_file);
	int parse_block (block_name);
	int set_var (var_name, var_value);
	scalar *tempi_out (void);
	int tempi_free (void);
	int tempi_reinit (void);	

All functions are returning 0 if there's an error. The error message is set in $main::! ($!). Otherwise, they will allways return 1, expect from tempi_out.

tempi_init will load the given template file and make it ready for using it. Calling any functions before tempi_init will result in an error. Calling tempi_init again before calling tempi_free will result in an error. You have to call tempi_free first. It is only possible to handle one template file at once.

parse_block is used to parse a block, that means the block will become visibel in the output. parse block is a primary function, that means that using one block name several times will not work. The result if you do so is undefined and very probably not what you want.

set_var will replace the given var in the template with the given value. set_var is secondary, that means, that you can use a var name as often you want, and everywhere it appaers, it will be replaced. Using set_var with the same name again, will only override the value it had before.

tempi_out returns a string, containing the parsed data.

tempi_free cleans up space used by Tempi. It's important to say, that not all memory is freed. Some data will stay. If you're using normal cgi's you even don't have to call tempi_free, because if the process is finished, the system will clean up. But if you're using mod_perl, you have to use tempi_free. The data which will stay, is used for the next request. That gives a great performance plus, since most time is spent for parsing the template, what so only has to be done when each process is starting. I suggest that you make allways use of tempi_free. It's cleaner and you're on the safer side.

tempi_reinit makes it possible to use init with a new template file. Otherwise, the old one will be used. You have to call tempi_free before you call tempi_reinit.

Tempi knows only a few differnt tags:

	<!--BLOCK:block_name-->	starts a block called block_name
	<!--END:block_name-->	the block ends here

	<!--FILE:file_name-->	will include the file file_name

	{var_name}	creates a variable called var_name

A block is a section in a template. This block can be inserted as often as you want at the place where it is. For example:

	<table>
	<!--BLOCK:row-->
	<tr><td>1. cell</td><td>2. cell</td></tr>
	<!--END:row-->
	</table>

could be used to create a table with as many

	<tr><td>1. cell</td><td>2. cell</td></tr>

lines as you wish. To produce 100 of this lines, try this:

	use Tempi;

	tempi_init("template.html");
	for (1..100)
		{
			parse_block("row");
		}
	parse_block("MAIN");
	print tempi_out();
	tempi_free();

As you sure have noticed, there is a parse_block("MAIN"); command. That is, because Tempi puts everthing that isn't in a block, into a block called MAIN (you should not use the name MAIN for a block yourself, that will crash).

To make the example from above really usefull, we will now use variables for the cells values:

	<table>
	<!--BLOCK:row-->
	<tr><td>{cell1}</td><td>{cell2}</td></tr>
	<!--END:row-->
	</table>

	use Tempi;

	tempi_init("template.html");
	for (1..100)
		{
			set_var ("cell1", "This is cell1 in row $_");
			set_var ("cell2", "This is cell2 in row $_");
			parse_block("row");
		}
	parse_block("MAIN");
	print tempi_out();
	tempi_free();

Files are include with this tag:

	<!--FILE:/usr/indian/temp/chief/coll_page.html-->

This would include the file located in /usr/indian/temp/chief/coll_page.html at the current position.

To make clear, which tags are valid, here are the regex patterns:

	Block start:	"<!--BLOCK:"[[:alnum:]]+"-->"
	Block end:	"<!--END"[[:alnum:]:]*"-->"
	Inlcude file:	"<!--FILE:"[[:alnum:]./_]+"-->
	Variable:	"{"[[:alnum:]]+"}"

	where [:alnum:] stands for a-zA-Z0-9.

(As you will surely have seen, you can close a block simply with <!--END-->, Tempi will not check that you're closing the blocks in the right order, that's up to you, but making it possible to use <!--END:name--> should make it easier.)

If you want to change the patterns, you can do it by editing the tempi.flex file and then run the whole installation again (perl Makefile.PL too).

	Tempi - A HTML Template system
Copyright (C) 2002  Roger Faust <roger_faust@bluewin.ch>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

There will be a lot, I'm quite sure. Using Tempi for serious things should not be done yet. This is the first version, I hope to get some echos about bugs (or that there aren't) so that it could be possible, to declare future versions of Tempi as stable.

Roger Faust <roger_faust@bluewin.ch>

bugs, tipps, improvments and comments are highly welcome!

HTML::Template