Basically, you have to build a template and write a PHP script, which will open the template, assign values to the template variables, and echo the output. Go to our samples page and browse the files of the first sample to grasp the basic idea.
When creating the template object, always remember to use the =& and not the = sign:
$template = new Template("test.tmpl"); // wrong!
$template =& new Template("test.tmpl");
If only one parameter is specified, it is taken as the template file name. In this case the template object is created with the default options. To specify other options, you pass one (associative) array, containing option=>value pairs:
$template =& new Template(array("option1"=>"value", "option2"=>"value"));
Available options are described later in this document.
Template syntax follows the same rules of HTML::Template except for some changes that are described below in the options section.
When the template is created, it is automatically parsed. Then you have to assign values to the template variables. To do that, you call AddParam()
. AddParam()
can be called in a number of ways:
// For simple TMPL_VARs:
$template->AddParam('PARAM', 'value');
// For TMPL_LOOPs:
$template->AddParam('LOOP_PARAM', array(
array('PARAM' => 'VALUE_FOR_FIRST_PASS', ... ),
array('PARAM' => 'VALUE_FOR_SECOND_PASS', ... )
));
$template->AddParam(array(
'PARAM' => 'value',
'PARAM2' => 'value',
'LOOP_PARAM' =>
array(array('PARAM' => 'VALUE_FOR_FIRST_PASS', ...),
array('PARAM' => 'VALUE_FOR_SECOND_PASS', ...),
...),
'ANOTHER_LOOP_PARAM' =>
array(array('PARAM' => 'VALUE_FOR_FIRST_PASS', ...),
array('PARAM' => 'VALUE_FOR_SECOND_PASS', ...),
...)
)
);
To obtain the template results, you can either:
EchoOutput()
, which will process the template and write its results on screen; orOutput()
, which will process the template and store the result in the object's output
attribute, that you can access as $template->output
.In both cases the results are kept in the $output attribute. The next time you call EchoOutput()
or Output()
, the results will be taken from $output
without processing the template again.
You can reassign and reprocess an open template by first calling the ResetParams()
and ResetOutput()
methods respectively. See sample 5 of our samples page for a demonstration.
Some of the options of HTML::Template, mainly those concerning the cache, are not implemented in PHP-HTML::Template, others produce slightly different results, and others are new.
die_on_bad_params
0
the module will let you call $template->AddParam('param_name' => 'value')
even if 'param_name'
doesn't exist in the template body. Defaults to 1
.strict
0
the module will allow things that look like
they might be TMPL_*
tags to get by without dying. Example:<TMPL_ LOOP NAME=ZUH>
'strict'=>0
, PHP-HTML::Template will ignore it. Defaults to 1
.vanguard_compatibility_mode
1
the module will expect to see <TMPL_VAR>s
that look like %NAME% in addition to the standard syntax. Also sets die_on_bad_params => 0
. If you're not at Vanguard Media trying to use an old format template don't worry about this one. Defaults to 0
.Currently there are not caching options implemented.
path
filename
' option to new()
and
for files included with the <TMPL_INCLUDE>
tag. This list
is only consulted when the filename is relative. In the case of a
<TMPL_INCLUDE> file, the path to the including file is also tried before
path is consulted.HTML_TEMPLATE_ROOT
environment variable is ignored in PHP-HTML::Template.$template =& new Template(array(
'filename' => 'file.tmpl',
'path' => array('/path/to/templates', '/alternate/path')
));
search_path_on_include
<TMPL_INCLUDE>
and use the first matching template found. The normal behavior is to look only
in the current directory for a template to include. Defaults to
0
.debug
1
, the module will output detailed debugging information. Defaults to 0
.case_sensitive
'case_sensitive'
option: $template =& new Template('filename', 'template.tmpl', case_sensitive', 1);
$template->Addparam(
'FieldA', 'foo',
'fIELDa', 'bar',
);
loop_context_vars
true
(it is false
by default) four loop context variables are made available inside a loop: __first__
, __last__
, __inner__
, __odd__
which can be used with <TMPL_IF>
, <TMPL_UNLESS>
and <TMPL_ELSE>
to control how a loop is output, and other three __counter__
, __pass__
and __passtotal__
which can be used with <TMPL_VAR>
tags. The last two are taken from htmltmpl. __counter__
and __pass__
represent the same value. Example: <TMPL_LOOP NAME="FOO">
Pass <TMPL_VAR NAME="__pass__"> of <TMPL_VAR NAME="__passtotal__"><br>
<TMPL_IF NAME="__first__">
This only outputs on the first pass.<br>
</TMPL_IF>
<TMPL_IF NAME="__odd__">
This outputs every other pass, on the odd passes.<br>
</TMPL_IF>
<TMPL_UNLESS NAME="__odd__">
This outputs every other pass, on the even passes.<br>
</TMPL_IF>
<TMPL_IF NAME="__inner__">
This outputs on passes that are neither first nor last.<br>
</TMPL_IF>
<TMPL_IF NAME="__last__">
This only outputs on the last pass.<br>
<TMPL_IF>
</TMPL_LOOP>
join()
. Example: <TMPL_LOOP FRUIT>
<TMPL_IF __last__> and </TMPL_IF>
<TMPL_VAR KIND><TMPL_UNLESS __last__>, <TMPL_ELSE>.</TMPL_UNLESS>
</TMPL_LOOP>
Apples, Oranges, Brains, Toes, and Kiwi.
AddParam()
call, of course. NOTE: A loop with only a single
pass will get both __first__
and __last__
set to true, but not __inner__
.no_includes
1
to disallow the <TMPL_INCLUDE> tag in the template file. This can be used to make opening untrusted templates slightly less dangerous. Defaults to 0
.max_includes
10
by default. Including files to a depth greater than this value causes an error message to be displayed.global_vars
This is a normal variable: <TMPL_VAR NORMAL>.<P> <TMPL_LOOP NAME=FROOT_LOOP> Here it is inside the loop: <TMPL_VAR NORMAL><P> </TMPL_LOOP>
global_vars
option also allows you to access the values of an enclosing loop within an inner loop. For example, in this loop the inner loop will have access to the value of OUTER_VAR
in the correct iteration:<TMPL_LOOP OUTER_LOOP> OUTER: <TMPL_VAR OUTER_VAR> <TMPL_LOOP INNER_LOOP> INNER: <TMPL_VAR INNER_VAR> INSIDE OUT: <TMPL_VAR OUTER_VAR> </TMPL_LOOP> </TMPL_LOOP>
GLOBAL
attribute for one variable alone, instead of setting global_vars
on. To do so, add a GLOBAL
attribute to the tag, this way:<TMPL_LOOP LOOP> <TMPL_VAR NAME="COUNTRY" GLOBAL="1"> <br> <TMPL_VAR NAME="NAME"> </TMPL_LOOP>
hash_comments
<TMPL_VAR NAME="name"> ### Three hashes and one space make a comment
1
.imark
emark
<?
require_once "template.php";
$options = array('filename'=>'template.tmpl',
'imark'=>'[[', 'emark'=>']]');
$template =& new Template(&$options);
$template->AddParam('title'=>'Hello world!');
$template->EchoOutput
?>
<html>
<head><title>[[TMPL_VAR NAME="title"]]</title></head>
<body><h1>[[TMPL_VAR NAME="title"]]</h1></body>
</html>
parse_html_comments
true
. Otherwise set it to false
, which will make parsing slightly faster. Default value is true
. Examples:$options = array('filename'=>'template.tmpl',
'imark'=>'<', 'emark'=>'>',
'parse_html_comments'=>true);
<!-- TMPL_VAR name="title" --> = <TMPL_VAR name="title">
$options = array('filename'=>'template.tmpl',
'imark'=>'[[', 'emark'=>']]',
'parse_html_comments'=>true);
<!-- [[TMPL_VAR name="title"]] --> = [[TMPL_VAR name="title"]]
$options = array('filename'=>'template.tmpl',
'imark'=>'<[', 'emark'=>']>',
'parse_html_comments'=>true);
<!-- [TMPL_VAR name="title"] --> = <[TMPL_VAR name="title"]>
To save a compiled template call the SaveCompiled($dir, $overwrite)
method. The first argument is the directory name where the compiled template file will be we stored. If it is NULL
or not specified the directory name of the original template file is used. The compiled template file name is the original template name with a "c" character appended. If a file with that name already exists the function exits with error, unless the $overwrite argument takes a true value (defaults to 0
).
Returns the path to the compiled template. Example:
<?php
require_once("template.php");
$t =& new Template("bench3.tpl");
if ($output = $t->SaveCompiled(".")) {
echo ("$output saved");
}
?>
If you assign variables before saving the compiled template the assigned values are stored as well.
To load a compiled template, use the LoadCompiledTemplate($filename)
function with the name of the compiled template file as the argument. Once loaded proceed as usual. Example:
<?php
require_once("template.php");
$template =& LoadCompiledTemplate("mytemplate.tplc");
$template->AddParam("title", "Hellow world!");
$template->EchoOutput();
?>