551 lines
17 KiB
HTML
551 lines
17 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>GT::Template - Gossamer Threads template parser</title>
|
|
<link rev="made" href="mailto:root@penguin.office.gossamer-threads.com" />
|
|
|
|
<style type="text/css">
|
|
/* $MVD$:fontset("Untitled Font Set 1","ARIEL","HELVETICA","HELV","SANSERIF") */
|
|
/* $MVD$:fontset("Arial","Arial") */
|
|
/* $MVD$:fontset("Arial Black","Arial Black") */
|
|
/* $MVD$:fontset("Algerian","Algerian") */
|
|
|
|
|
|
body {
|
|
background-color: white;
|
|
font-family: Verdana, Arial, sans-serif;
|
|
font-size: small;
|
|
color: black;
|
|
}
|
|
|
|
|
|
p {
|
|
background-color : white;
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
h1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
background-color : white;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
h2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : medium;
|
|
font-weight : bold;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h3 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : maroon;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h5 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h6 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
ul {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
ol {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
li {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
th {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
td {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dd {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dt {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
code {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
pre {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-H1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : 14.0pt;
|
|
background-color : transparent;
|
|
background-image : none;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
.mvd-H2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 12.0pt;
|
|
color : blue;
|
|
}
|
|
|
|
|
|
p.indent {
|
|
font-family : "Verdana, Arial, sans-serif";
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-indent {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
pre.programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE-programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE {
|
|
font-size : 9.0pt;
|
|
}
|
|
|
|
|
|
p.note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-H4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : normal;
|
|
font-size : 9.0pt;
|
|
color : black;
|
|
margin-left : 6.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 10.0pt;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-BODY {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
p.indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
|
|
|
|
.mvd-P-indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
<p><a name="__index__"></a></p>
|
|
<!-- INDEX BEGIN -->
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#template_syntax">Template Syntax</a></li>
|
|
<li><a href="#parse">parse</a></li>
|
|
<li><a href="#parse_print">parse_print</a></li>
|
|
<li><a href="#parse_stream">parse_stream</a></li>
|
|
<li><a href="#parse_options">Parse Options</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#filename">Filename</a></li>
|
|
<li><a href="#variables">Variables</a></li>
|
|
<li><a href="#options">Options</a></li>
|
|
<li><a href="#aliases">Aliases</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#vars">vars</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#examples">EXAMPLES</a></li>
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
<li><a href="#version">VERSION</a></li>
|
|
</ul>
|
|
<!-- INDEX END -->
|
|
|
|
<hr />
|
|
<p>
|
|
</p>
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>GT::Template - Gossamer Threads template parser</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
use GT::Template;
|
|
my $var = GT::Template->parse('file.txt', { key => 'value' });
|
|
...
|
|
print $var;</pre>
|
|
<p>or</p>
|
|
<pre>
|
|
use GT::Template;
|
|
GT::Template->parse_print('file.txt', { key => 'value' });</pre>
|
|
<p>or</p>
|
|
<pre>
|
|
use GT::Template;
|
|
GT::Template->parse_stream('file.txt', { key => 'value' });</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>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.</p>
|
|
<p>It supports simple replacements, conditionals, function calls, including other
|
|
templates, and more.</p>
|
|
<p>Additionally, through using pre-compiled files, subsequent parses of a template
|
|
will be very fast.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="template_syntax">Template Syntax</a></h2>
|
|
<p>The template syntax documentation has moved - it is now documented in
|
|
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/Template/Tutorial.html">the GT::Template::Tutorial manpage</a>.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="parse">parse</a></h2>
|
|
<p>This option parses a template, and returns the value of the parsed template.
|
|
See <a href="#parse_options">Parse Options</a> for a description of the possible parse parameters.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="parse_print">parse_print</a></h2>
|
|
<p>This option parses a template, and prints it. See <a href="#parse_options">Parse Options</a> for a
|
|
description of the possible parse_print parameters.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="parse_stream">parse_stream</a></h2>
|
|
<p>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 <a href="#parse_options">Parse Options</a>
|
|
for a description of the possible parse_stream parameters.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="parse_options">Parse Options</a></h2>
|
|
<p>
|
|
</p>
|
|
<h3><a name="filename">Filename</a></h3>
|
|
<p>The first argument to <code>parse()/parse_print()/parse_stream()</code> (hereafter referred
|
|
to simply as <code>parse())</code> is the full or relative (to the current working
|
|
directory) path to the file to parse.</p>
|
|
<p>
|
|
</p>
|
|
<h3><a name="variables">Variables</a></h3>
|
|
<p>The second argument is a hash reference of template variables that will be
|
|
available in the parsed template (see <a href="glist.cgi?do=admin_gtdoc&topic=/GT/Template/Tutorial.html">the GT::Template::Tutorial manpage</a>). Arbitrary
|
|
hash/array data structure access is supported (see
|
|
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/Template/Tutorial.html#advanced_variables_using_references">Advanced variables using references in the GT::Template::Tutorial manpage</a>).</p>
|
|
<p>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.</p>
|
|
<p>
|
|
</p>
|
|
<h3><a name="options">Options</a></h3>
|
|
<p>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.</p>
|
|
<ul>
|
|
<li><strong><a name="item_string__3d_3e__24template">string => $template</a></strong><br />
|
|
</li>
|
|
Passing in <a href="#item_string__3d_3e__24template"><code>string => $template</code></a> will use $template as for the template
|
|
content instead of reading the file specified as the first <code>parse()</code> argument.
|
|
If provided, the first argument to <code>parse()</code> (the filename) is ignored.
|
|
<p></p>
|
|
<li><strong><a name="item_compress__3d_3e_1">compress => 1</a></strong><br />
|
|
</li>
|
|
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().
|
|
<p></p>
|
|
<li><strong><a name="item_strict__3d_3e_0">strict => 0</a></strong><br />
|
|
</li>
|
|
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.
|
|
<p></p>
|
|
<li><strong><a name="item_escape__3d_3e_1">escape => 1</a></strong><br />
|
|
</li>
|
|
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>').
|
|
<p>This option currently defaults to 0, but may eventually change to 1 - so
|
|
passing an explicit 1 or 0 value is strongly recommended.</p>
|
|
<p></p>
|
|
<li><strong><a name="item_disable__3d_3e__7b__2e_2e_2e__7d">disable => { ... }</a></strong><br />
|
|
</li>
|
|
This can be used to disable certain GT::Template functionality. To disable a
|
|
particular feature, the hash reference passed to disable should contain a
|
|
<code>feature_name</code> with a <code>1</code> value, unless otherwise indicated. Feature names
|
|
are as follows:
|
|
<ul>
|
|
<li><strong><a name="item_functions">functions</a></strong><br />
|
|
</li>
|
|
This can be used to disable Package::function calls, such as
|
|
<code><%Some::Package::function%></code>. Note, however, that this does _not_
|
|
disable aliased function calls (see below).
|
|
<p></p>
|
|
<li><strong><a name="item_function_args">function_args</a></strong><br />
|
|
</li>
|
|
This disables any function calls that specify arguments - for instance,
|
|
<code><%Some::Package::function(1)></code>. Note that this does _not_ disable
|
|
passing arguments to aliased function calls (see below).
|
|
<p></p>
|
|
<li><strong><a name="item_function_restrict">function_restrict</a></strong><br />
|
|
</li>
|
|
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:
|
|
<pre>
|
|
function_restrict => '^(?:Package::One|Second::Package)::\w+$'</pre>
|
|
<p>Like the above options, this does not restrict aliased function calls.</p>
|
|
<p></p>
|
|
<li><strong><a name="item_coderefs_args">coderefs_args</a></strong><br />
|
|
</li>
|
|
This can be specified to disable the calling of code reference variables with
|
|
arguments. Tags such as <code><%coderefname%></code> and
|
|
<code><%coderefname()%></code> will be allowed, but <code><%coderefname(1)%></code>
|
|
will not.
|
|
<p></p>
|
|
<li><strong><a name="item_alias_args">alias_args</a></strong><br />
|
|
</li>
|
|
This option can be used to disable the passing of arguments to aliased function
|
|
calls (see below).
|
|
<p></p></ul>
|
|
<li><strong><a name="item_pkg_chop">pkg_chop</a></strong><br />
|
|
</li>
|
|
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).
|
|
<p></p>
|
|
<li><strong><a name="item_heap">heap</a></strong><br />
|
|
</li>
|
|
If this is set, it will be added to the end of any other arguments passed to
|
|
functions called.
|
|
<p></p>
|
|
<li><strong><a name="item_func_code">func_code</a></strong><br />
|
|
</li>
|
|
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 <a href="#item_func_code"><code>func_code</code></a>. 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.
|
|
<p></p>
|
|
<li><strong><a name="item_begin">begin</a></strong><br />
|
|
</li>
|
|
<li><strong><a name="item_end">end</a></strong><br />
|
|
</li>
|
|
<a href="#item_begin"><code>begin</code></a> and <a href="#item_end"><code>end</code></a> can be used to change the characters that start and end a
|
|
template tag. These default to <code><%</code> for <a href="#item_begin"><code>begin</code></a>, and <code>%></code> for
|
|
<a href="#item_end"><code>end</code></a>. For example, if you changed <a href="#item_begin"><code>begin</code></a> to <code>[*</code> and <a href="#item_end"><code>end</code></a> to <code>*]</code>, you
|
|
would use <code>[*tagname*]</code> for a normal tag, <code>[*-- comment --*]</code> for a comment,
|
|
etc.
|
|
<p></p></ul>
|
|
<p>
|
|
</p>
|
|
<h3><a name="aliases">Aliases</a></h3>
|
|
<p>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:</p>
|
|
<pre>
|
|
print GT::Template->parse(
|
|
'file.htm',
|
|
{ key => 'value' },
|
|
{ compress => 1 },
|
|
{ myfunc => 'Long::Package::Name::To::myfunc' }
|
|
);</pre>
|
|
<p>Now in your template you can do:</p>
|
|
<pre>
|
|
<%myfunc('argument')%></pre>
|
|
<p>Which will call <code>Long::Package::Name::To::myfunc</code>.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="vars">vars</a></h2>
|
|
<p>Accessing variables from outside a template can be done by calling the
|
|
<code>GT::Template->vars</code> method. For further details, please see
|
|
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/Template/Vars.html">the GT::Template::Vars manpage</a>.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="examples">EXAMPLES</a></h1>
|
|
<p>Parse the string contained in $template, making the 'key' tag available.</p>
|
|
<pre>
|
|
my $parsed = GT::Template->parse(undef, { key => 'value' }, { string => $template });</pre>
|
|
<p>Parse file.txt, compress the result, and print it. This is equivelant to
|
|
<code>print GT::Template->parse(...)</code>, but slightly faster.</p>
|
|
<pre>
|
|
GT::Template->parse_print('file.txt', { key => 'value' }, { compress => 1 });</pre>
|
|
<p>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).</p>
|
|
<pre>
|
|
GT::Template->parse_stream('file.txt', { key => 'value' });</pre>
|
|
<p>Don't display warnings on invalid keys:</p>
|
|
<pre>
|
|
GT::Template->parse_print('file.txt', { key => 'value' }, { strict => 0 });</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><a href="glist.cgi?do=admin_gtdoc&topic=/GT/Template/Tutorial.html">the GT::Template::Tutorial manpage</a> - Documentation/tutorial for GT::Template template
|
|
tags.</p>
|
|
<p><a href="glist.cgi?do=admin_gtdoc&topic=/GT/Template/Vars.html">the GT::Template::Vars manpage</a> - Interface for accessing/manipulating template tags from
|
|
Perl code.</p>
|
|
<p><a href="glist.cgi?do=admin_gtdoc&topic=/GT/Template/Inheritance.html">the GT::Template::Inheritance manpage</a> - Documentation for GT::Template template
|
|
inheritance.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright (c) 2005 Gossamer Threads Inc. All Rights Reserved.
|
|
<a href="http://www.gossamer-threads.com/">http://www.gossamer-threads.com/</a></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="version">VERSION</a></h1>
|
|
<p>Revision: $Id: Template.pm,v 2.142 2005/07/05 00:39:40 jagerman Exp $</p>
|
|
|
|
</body>
|
|
|
|
</html>
|