GT::Template - Gossamer Threads template parser
use GT::Template; my $var = GT::Template->parse('file.txt', { key => 'value' }); ... print $var;
or
use GT::Template; GT::Template->parse_print('file.txt', { key => 'value' });
or
use GT::Template; GT::Template->parse_stream('file.txt', { key => 'value' });
or
use GT::Template; my $parser = GT::Template->new; $parser->parse('file.txt', { key => 'value' });
GT::Template provides a simple way (one line) to parse a template (which can be either a file or a string) and make sophisticated replacements.
It supports simple replacements, conditionals, function calls, including other templates, and more.
Additionally, through using pre-compiled files, subsequent parses of a template will be very fast.
The template syntax documentation has moved - it is now documented in the GT::Template::Tutorial manpage.
This option parses a template, and returns the value of the parsed template. See Parse Options for a description of the possible parse parameters.
This option parses a template, and prints it. See Parse Options for a description of the possible parse_print parameters.
This option parses a template, and prints each part of it as the parse occurs. It should only be used in situations where streaming content is required as it is measurably slower than the parse_print alternative. See Parse Options for a description of the possible parse_stream parameters.
The first argument to parse()/parse_print()/parse_stream()
(hereafter referred
to simply as parse())
is the full or relative (to the current working
directory) path to the file to parse.
The second argument is a hash reference of template variables that will be available in the parsed template (see the GT::Template::Tutorial manpage). Arbitrary hash/array data structure access is supported (see Advanced variables using references in the GT::Template::Tutorial manpage).
Loops are supported by providing an array reference or code reference as a value; array reference loops are generally preferred as they enable the loop to be used multiple times and support the <%loopvar.length%> syntax.
The third argument (which is not required) takes additional options that change the way a parse is performed. The available options (there are more, however their use is discouraged) are as follows.
Passing in string => $template
will use $template as for the template
content instead of reading the file specified as the first parse()
argument.
If provided, the first argument to parse()
(the filename) is ignored.
Setting compress => 1 will compress all white space generated by the program. This is usually acceptable for HTML, reducing page sizes by typically 10-20%, but should not be used for non-HTML templates. The default is 0 (no compression). This option has no effect when using parse_stream().
If set to 1, attempting to use a tag that does not exist will display an ``Unknown tag 'tagname''' error. If strict is set to 0, using an unset tag will not display anything.
If enabled, this option will cause all variables to be HTML escaped before being included on a page. Enabling this option is strongly recommended. all variables before they are printed. Tag values that should not be escaped should be passed as scalar references (\$foo or \'<html>').
This option currently defaults to 0, but may eventually change to 1 - so passing an explicit 1 or 0 value is strongly recommended.
This can be used to disable certain GT::Template functionality. To disable a
particular feature, the hash reference passed to disable should contain a
feature_name
with a 1
value, unless otherwise indicated. Feature names
are as follows:
This can be used to disable Package::function calls, such as
<%Some::Package::function%>
. Note, however, that this does _not_
disable aliased function calls (see below).
This disables any function calls that specify arguments - for instance,
<%Some::Package::function(1)>
. Note that this does _not_ disable
passing arguments to aliased function calls (see below).
This can be used to restrict function calls by limiting the available functions. It takes a regular expression as an argument, which will be tested against the fully qualified function name - any function that does not match the regular expression will not be called. For example, to only allow functions in 'Package::One' and 'Second::Package' to be called, you could use:
function_restrict => '^(?:Package::One|Second::Package)::\w+$'
Like the above options, this does not restrict aliased function calls.
This can be specified to disable the calling of code reference variables with
arguments. Tags such as <%coderefname%>
and
<%coderefname()%>
will be allowed, but <%coderefname(1)%>
will not.
This option can be used to disable the passing of arguments to aliased function calls (see below).
Disables the use of core perl function wrappers such as substr and sprintf.
When calling a function such as <%Package::A::B::function%>, GT::Template will first attempt to load Package/A/B.pm, then, if it fails, Package/A.pm, and so on down to Package.pm, looking for Package::A::B::function in each file. This behaviour is slow and often undesirable - it is recommended to properly split up packages (that is, putting Package::A::B inside Package/A/B.pm instead of Package/A.pm or Package.pm). The ``package chopping'' occurs if pkg_chop is set to 1 (currently the default, but may change), and does not occur if pkg_chop is set to 0 (recommended, but not the default for historic reasons).
If this is set, it will be added to the end of any other arguments passed to functions called.
When calling a function such as <%Package::function%>, you can override the
default behaviour of simply calling the function by providing a code reference
to func_code
. Instead of calling Package::function(), your code reference
will be called with the string of the package to call (e.g.
'Package::function') and the arguments that would have been passed to the
function. The return value of your code will be used as if it was the return
value from the real function.
begin
and end
can be used to change the characters that start and end a
template tag. These default to <%
for begin
, and %>
for
end
. For example, if you changed begin
to [*
and end
to *]
, you
would use [*tagname*]
for a normal tag, [*-- comment --*]
for a comment,
etc.
If enabled, this option will allow paths to be used in variable based includes.
The forth option to parse is an optional hash of aliases to set up for functions. The key should be the alias name and the value should be the function to call when the alias is invoked. For example:
print GT::Template->parse( 'file.htm', { key => 'value' }, { compress => 1 }, { myfunc => 'Long::Package::Name::To::myfunc' } );
Now in your template you can do:
<%myfunc('argument')%>
Which will call Long::Package::Name::To::myfunc
.
Accessing variables from outside a template can be done by calling the
GT::Template->vars
method. For further details, please see
the GT::Template::Vars manpage.
It is sometimes desirable to know the last modification date of a parsed
template (including includes). For this, the last_modified()
method can be
used, subject to some caveats:
parse_print()
nor parse_stream()
can be used.
Parse the string contained in $template, making the 'key' tag available.
my $parsed = GT::Template->parse(undef, { key => 'value' }, { string => $template });
Parse file.txt, compress the result, and print it. This is equivelant to
print GT::Template->parse(...)
, but slightly faster.
GT::Template->parse_print('file.txt', { key => 'value' }, { compress => 1 });
Print the output of the template it as it is parsed, not after entirely parsed. This will output the same as the above command would without the ``compress'' option, but is slower (unless, of course, streaming is needed).
GT::Template->parse_stream('file.txt', { key => 'value' });
Don't display warnings on invalid keys:
GT::Template->parse_print('file.txt', { key => 'value' }, { strict => 0 });
the GT::Template::Tutorial manpage - Documentation/tutorial for GT::Template template tags.
the GT::Template::Vars manpage - Interface for accessing/manipulating template tags from Perl code.
the GT::Template::Inheritance manpage - Documentation for GT::Template template inheritance.
Copyright (c) 2005 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/
Revision: $Id: Template.pm,v 2.170 2008/08/22 18:42:17 scottm Exp $