NAME
HTML::Tempi - Perl extension for HTML templates
SYNOPSIS
use HTML::Tempi;
tempi_init("template.html");
set_var("some_var", "i was some_var");
parse_block("MAIN");
print tempi_out();
tempi_free();
DESCRIPTION
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.
FUNCTIONS
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);
general note:
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
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
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
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
tempi_out
returns a string, containing the parsed data.
tempi_free
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
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
.
TAGS
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
BLOCKS
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).
VARIABLES
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
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.
The tags as regex
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).
LICENSE
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.
BUGS
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.
AUTHOR
Roger Faust <roger_faust@bluewin.ch>
bugs, tipps, improvments and comments are highly welcome!
SEE ALSO
HTML::Template