Файловый менеджер - Редактировать - /home/lakoyani/lakoyani.com.fj/Manual.tar
Назад
Directives.pod 0000444 00000171066 14711272042 0007362 0 ustar 00 #============================================================= -*-perl-*- # # Template::Manual::Directives # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Manual::Directives - Template directives =head1 Accessing and Updating Template Variables =head2 GET The C<GET> directive retrieves and outputs the value of the named variable. [% GET foo %] The C<GET> keyword is optional. A variable can be specified in a directive tag by itself. [% foo %] The variable can have an unlimited number of elements, each separated by a dot. Each element can have arguments specified within parentheses. [% foo %] [% bar.baz %] [% biz.baz(10) %] ...etc... See L<Template::Manual::Variables> for a full discussion on template variables. You can also specify expressions using the logical (C<and>, C<or>, C<not>, C<?>, C<:>) and mathematic operators (C<+>, C<->, C<*>, C</>, C<%>, C<mod>, C<div>). [% template.title or default.title %] [% score * 100 %] [% order.nitems ? checkout(order.total) : 'no items' %] The C<div> operator returns the integer result of division. Both C<%> and C<mod> return the modulus (i.e. remainder) of division. [% 15 / 6 %] # 2.5 [% 15 div 6 %] # 2 [% 15 mod 6 %] # 3 =head2 CALL The C<CALL> directive is similar to C<GET> in evaluating the variable named, but doesn't print the result returned. This can be useful when a variable is bound to a sub-routine or object method which you want to call but aren't interested in the value returned. [% CALL dbi.disconnect %] [% CALL inc_page_counter(page_count) %] =head2 SET The C<SET> directive allows you to assign new values to existing variables or create new temporary variables. [% SET title = 'Hello World' %] The C<SET> keyword is also optional. [% title = 'Hello World' %] Variables may be assigned the values of other variables, unquoted numbers (2.718), literal text ('single quotes') or quoted text ("double quotes"). In the latter case, any variable references within the text will be interpolated when the string is evaluated. Variables should be prefixed by C<$>, using curly braces to explicitly scope the variable name where necessary. [% foo = 'Foo' %] # literal value 'Foo' [% bar = foo %] # value of variable 'foo' [% cost = '$100' %] # literal value '$100' [% item = "$bar: ${cost}.00" %] # value "Foo: $100.00" Multiple variables may be assigned in the same directive and are evaluated in the order specified. Thus, the above could have been written: [% foo = 'Foo' bar = foo cost = '$100' item = "$bar: ${cost}.00" %] Simple expressions can also be used, as per C<GET>. [% ten = 10 twenty = 20 thirty = twenty + ten forty = 2 * twenty fifty = 100 div 2 six = twenty mod 7 %] You can concatenate strings together using the C<'_'> underscore operator. In Perl 5, the C<.> dot is used for string concatenation, but in Perl 6, as in the Template Toolkit, the C<.> dot will be used as the method calling operator and C<'_'> underscore will be used for string concatenation. Note that the operator must be specified with surrounding whitespace which, as Larry says, is construed as a feature: [% copyright = '(C) Copyright' _ year _ ' ' _ author %] You can, of course, achieve a similar effect with double quoted string interpolation. [% copyright = "(C) Copyright $year $author" %] =head2 DEFAULT The C<DEFAULT> directive is similar to C<SET> but only updates variables that are currently undefined or have no "true" value (in the Perl sense). [% DEFAULT name = 'John Doe' id = 'jdoe' %] This can be particularly useful in common template components to ensure that some sensible default are provided for otherwise undefined variables. [% DEFAULT title = 'Hello World' bgcol = '#ffffff' %] <html> <head> <title>[% title %]</title> </head> <body bgcolor="[% bgcol %]"> ...etc... =head1 Processing Template Files and Blocks =head2 INSERT The C<INSERT> directive is used to insert the contents of an external file at the current position. [% INSERT myfile %] No attempt to parse or process the file is made. The contents, possibly including any embedded template directives, are inserted intact. The filename specified should be relative to one of the C<INCLUDE_PATH> directories. Absolute (i.e. starting with C</>) and relative (i.e. starting with C<.>) filenames may be used if the C<ABSOLUTE> and C<RELATIVE> options are set, respectively. Both these options are disabled by default. my $template = Template->new({ INCLUDE_PATH => '/here:/there', }); $template->process('myfile'); F<myfile>: [% INSERT foo %] # looks for /here/foo then /there/foo [% INSERT /etc/passwd %] # file error: ABSOLUTE not set [% INSERT ../secret %] # file error: RELATIVE not set For convenience, the filename does not need to be quoted as long as it contains only alphanumeric characters, underscores, dots or forward slashes. Names containing any other characters should be quoted. [% INSERT misc/legalese.txt %] [% INSERT 'dos98/Program Files/stupid' %] To evaluate a variable to specify a filename, you should explicitly prefix it with a C<$> or use double-quoted string interpolation. [% language = 'en' legalese = 'misc/legalese.txt' %] [% INSERT $legalese %] # misc/legalese.txt [% INSERT "$language/$legalese" %] # en/misc/legalese.txt Multiple files can be specified using C<+> as a delimiter. All files should be unquoted names or quoted strings. Any variables should be interpolated into double-quoted strings. [% INSERT legalese.txt + warning.txt %] [% INSERT "$legalese" + warning.txt %] # requires quoting =head2 INCLUDE The C<INCLUDE> directive is used to process and include the output of another template file or block. [% INCLUDE header %] If a C<BLOCK> of the specified name is defined in the same file, or in a file from which the current template has been called (i.e. a parent template) then it will be used in preference to any file of the same name. [% INCLUDE table %] # uses BLOCK defined below [% BLOCK table %] <table> ... </table> [% END %] If a C<BLOCK> definition is not currently visible then the template name should be a file relative to one of the C<INCLUDE_PATH> directories, or an absolute or relative file name if the C<ABSOLUTE>/C<RELATIVE> options are appropriately enabled. The C<INCLUDE> directive automatically quotes the filename specified, as per C<INSERT> described above. When a variable contains the name of the template for the C<INCLUDE> directive, it should be explicitly prefixed by C<$> or double-quoted [% myheader = 'my/misc/header' %] [% INCLUDE myheader %] # 'myheader' [% INCLUDE $myheader %] # 'my/misc/header' [% INCLUDE "$myheader" %] # 'my/misc/header' Any template directives embedded within the file will be processed accordingly. All variables currently defined will be visible and accessible from within the included template. [% title = 'Hello World' %] [% INCLUDE header %] <body> ... F<header>: <html> <title>[% title %]</title> output: <html> <title>Hello World</title> <body> ... Local variable definitions may be specified after the template name, temporarily masking any existing variables. Insignificant whitespace is ignored within directives so you can add variable definitions on the same line, the next line or split across several line with comments interspersed, if you prefer. [% INCLUDE table %] [% INCLUDE table title="Active Projects" %] [% INCLUDE table title = "Active Projects" bgcolor = "#80ff00" # chartreuse border = 2 %] The C<INCLUDE> directive localises (i.e. copies) all variables before processing the template. Any changes made within the included template will not affect variables in the including template. [% foo = 10 %] foo is originally [% foo %] [% INCLUDE bar %] foo is still [% foo %] [% BLOCK bar %] foo was [% foo %] [% foo = 20 %] foo is now [% foo %] [% END %] output: foo is originally 10 foo was 10 foo is now 20 foo is still 10 Technical Note: the localisation of the stash (that is, the process by which variables are copied before an C<INCLUDE> to prevent being overwritten) is only skin deep. The top-level variable namespace (hash) is copied, but no attempt is made to perform a deep-copy of other structures (hashes, arrays, objects, etc.) Therefore, a C<foo> variable referencing a hash will be copied to create a new C<foo> variable but which points to the same hash array. Thus, if you update compound variables (e.g. C<foo.bar>) then you will change the original copy, regardless of any stash localisation. If you're not worried about preserving variable values, or you trust the templates you're including then you might prefer to use the C<PROCESS> directive which is faster by virtue of not performing any localisation. You can specify dotted variables as "local" variables to an C<INCLUDE> directive. However, be aware that because of the localisation issues explained above (if you skipped the previous Technical Note above then you might want to go back and read it or skip this section too), the variables might not actually be "local". If the first element of the variable name already references a hash array then the variable update will affect the original variable. [% foo = { bar = 'Baz' } %] [% INCLUDE somefile foo.bar='Boz' %] [% foo.bar %] # Boz This behaviour can be a little unpredictable (and may well be improved upon in a future version). If you know what you're doing with it and you're sure that the variables in question are defined (nor not) as you expect them to be, then you can rely on this feature to implement some powerful "global" data sharing techniques. Otherwise, you might prefer to steer well clear and always pass simple (undotted) variables as parameters to C<INCLUDE> and other similar directives. If you want to process several templates in one go then you can specify each of their names (quoted or unquoted names only, no unquoted C<$variables>) joined together by C<+>. The C<INCLUDE> directive will then process them in order. [% INCLUDE html/header + "site/$header" + site/menu title = "My Groovy Web Site" %] The variable stash is localised once and then the templates specified are processed in order, all within that same variable context. This makes it slightly faster than specifying several separate C<INCLUDE> directives (because you only clone the variable stash once instead of n times), but not quite as "safe" because any variable changes in the first file will be visible in the second, third and so on. This might be what you want, of course, but then again, it might not. =head2 PROCESS The PROCESS directive is similar to C<INCLUDE> but does not perform any localisation of variables before processing the template. Any changes made to variables within the included template will be visible in the including template. [% foo = 10 %] foo is [% foo %] [% PROCESS bar %] foo is [% foo %] [% BLOCK bar %] [% foo = 20 %] changed foo to [% foo %] [% END %] output: foo is 10 changed foo to 20 foo is 20 Parameters may be specified in the C<PROCESS> directive, but these too will become visible changes to current variable values. [% foo = 10 %] foo is [% foo %] [% PROCESS bar foo = 20 %] foo is [% foo %] [% BLOCK bar %] this is bar, foo is [% foo %] [% END %] output: foo is 10 this is bar, foo is 20 foo is 20 The C<PROCESS> directive is slightly faster than C<INCLUDE> because it avoids the need to localise (i.e. copy) the variable stash before processing the template. As with C<INSERT> and C<INCLUDE>, the first parameter does not need to be quoted as long as it contains only alphanumeric characters, underscores, periods or forward slashes. A C<$> prefix can be used to explicitly indicate a variable which should be interpolated to provide the template name: [% myheader = 'my/misc/header' %] [% PROCESS myheader %] # 'myheader' [% PROCESS $myheader %] # 'my/misc/header' As with C<INCLUDE>, multiple templates can be specified, delimited by C<+>, and are processed in order. [% PROCESS html/header + my/header %] =head2 WRAPPER It's not unusual to find yourself adding common headers and footers to pages or sub-sections within a page. Something like this: [% INCLUDE section/header title = 'Quantum Mechanics' %] Quantum mechanics is a very interesting subject wish should prove easy for the layman to fully comprehend. [% INCLUDE section/footer %] [% INCLUDE section/header title = 'Desktop Nuclear Fusion for under $50' %] This describes a simple device which generates significant sustainable electrical power from common tap water by process of nuclear fusion. [% INCLUDE section/footer %] The individual template components being included might look like these: section/header: <p> <h2>[% title %]</h2> section/footer: </p> The C<WRAPPER> directive provides a way of simplifying this a little. It encloses a block up to a matching C<END> directive, which is first processed to generate some output. This is then passed to the named template file or C<BLOCK> as the C<content> variable. [% WRAPPER section title = 'Quantum Mechanics' %] Quantum mechanics is a very interesting subject wish should prove easy for the layman to fully comprehend. [% END %] [% WRAPPER section title = 'Desktop Nuclear Fusion for under $50' %] This describes a simple device which generates significant sustainable electrical power from common tap water by process of nuclear fusion. [% END %] The single 'section' template can then be defined as: <h2>[% title %]</h2> <p> [% content %] </p> Like other block directives, it can be used in side-effect notation: [% INSERT legalese.txt WRAPPER big_bold_table %] It's also possible to specify multiple templates to a C<WRAPPER> directive. The specification order indicates outermost to innermost wrapper templates. For example, given the following template block definitions: [% BLOCK bold %]<b>[% content %]</b>[% END %] [% BLOCK italic %]<i>[% content %]</i>[% END %] the directive [% WRAPPER bold+italic %]Hello World[% END %] would generate the following output: <b><i>Hello World</i></b> =head2 BLOCK The C<BLOCK>...C<END> construct can be used to define template component blocks which can be processed with the C<INCLUDE>, C<PROCESS> and C<WRAPPER> directives. [% BLOCK tabrow %] <tr> <td>[% name %]<td> <td>[% email %]</td> </tr> [% END %] <table> [% PROCESS tabrow name='Fred' email='fred@nowhere.com' %] [% PROCESS tabrow name='Alan' email='alan@nowhere.com' %] </table> A C<BLOCK> definition can be used before it is defined, as long as the definition resides in the same file. The block definition itself does not generate any output. [% PROCESS tmpblk %] [% BLOCK tmpblk %] This is OK [% END %] You can use an anonymous C<BLOCK> to capture the output of a template fragment. [% julius = BLOCK %] And Caesar's spirit, ranging for revenge, With Ate by his side come hot from hell, Shall in these confines with a monarch's voice Cry 'Havoc', and let slip the dogs of war; That this foul deed shall smell above the earth With carrion men, groaning for burial. [% END %] Like a named block, it can contain any other template directives which are processed when the block is defined. The output generated by the block is then assigned to the variable C<julius>. Anonymous C<BLOCK>s can also be used to define block macros. The enclosing block is processed each time the macro is called. [% MACRO locate BLOCK %] The [% animal %] sat on the [% place %]. [% END %] [% locate(animal='cat', place='mat') %] # The cat sat on the mat [% locate(animal='dog', place='log') %] # The dog sat on the log =head1 Conditional Processing =head2 IF / UNLESS / ELSIF / ELSE The C<IF> and C<UNLESS> directives can be used to process or ignore a block based on some run-time condition. [% IF frames %] [% INCLUDE frameset %] [% END %] [% UNLESS text_mode %] [% INCLUDE biglogo %] [% END %] Multiple conditions may be joined with C<ELSIF> and/or C<ELSE> blocks. [% IF age < 10 %] Hello [% name %], does your mother know you're using her AOL account? [% ELSIF age < 18 %] Sorry, you're not old enough to enter (and too dumb to lie about your age) [% ELSE %] Welcome [% name %]. [% END %] The following conditional and boolean operators may be used: == != < <= > >= && || ! and or not Conditions may be arbitrarily complex and are evaluated with the same precedence as in Perl. Parenthesis may be used to explicitly determine evaluation order. # ridiculously contrived complex example [% IF (name == 'admin' || uid <= 0) && mode == 'debug' %] I'm confused. [% ELSIF more > less %] That's more or less correct. [% END %] The C<and>, C<or> and C<not> operator are provided as aliases for C<&&>, C<||> and C<!>, respectively. Unlike Perl, which treats C<and>, C<or> and C<not> as separate, lower-precedence versions of the other operators, the Template Toolkit performs a straightforward substitution of C<and> for C<&&>, and so on. That means that C<and>, C<or> and C<not> have the same operator precedence as C<&&>, C<||> and C<!>. =head2 SWITCH / CASE The C<SWITCH> / C<CASE> construct can be used to perform a multi-way conditional test. The C<SWITCH> directive expects an expression which is first evaluated and then compared against each CASE statement in turn. Each C<CASE> directive should contain a single value or a list of values which should match. C<CASE> may also be left blank or written as C<[% CASE DEFAULT %]> to specify a default match. Only one C<CASE> matches, there is no drop-through between C<CASE> statements. [% SWITCH myvar %] [% CASE 'value1' %] ... [% CASE ['value2', 'value3'] %] # multiple values ... [% CASE myhash.keys %] # ditto ... [% CASE %] # default ... [% END %] =head1 Loop Processing =head2 FOREACH The C<FOREACH> directive will iterate through the items in a list, processing the enclosed block for each one. [% foo = 'Foo' items = [ 'one', 'two', 'three' ] %] Things: [% FOREACH thing IN [ foo 'Bar' "$foo Baz" ] %] * [% thing %] [% END %] Items: [% FOREACH i IN items %] * [% i %] [% END %] Stuff: [% stuff = [ foo "$foo Bar" ] %] [% FOREACH s IN stuff %] * [% s %] [% END %] output: Things: * Foo * Bar * Foo Baz Items: * one * two * three Stuff: * Foo * Foo Bar You can use also use C<=> instead of C<IN> if you prefer. [% FOREACH i = items %] When the C<FOREACH> directive is used without specifying a target variable, any iterated values which are hash references will be automatically imported. [% userlist = [ { id => 'tom', name => 'Thomas' }, { id => 'dick', name => 'Richard' }, { id => 'larry', name => 'Lawrence' }, ] %] [% FOREACH user IN userlist %] [% user.id %] [% user.name %] [% END %] short form: [% FOREACH userlist %] [% id %] [% name %] [% END %] Note that this particular usage creates a localised variable context to prevent the imported hash keys from overwriting any existing variables. The imported definitions and any other variables defined in such a C<FOREACH> loop will be lost at the end of the loop, when the previous context and variable values are restored. However, under normal operation, the loop variable remains in scope after the C<FOREACH> loop has ended (caveat: overwriting any variable previously in scope). This is useful as the loop variable is secretly an iterator object (see below) and can be used to analyse the last entry processed by the loop. The C<FOREACH> directive can also be used to iterate through the entries in a hash array. Each entry in the hash is returned in sorted order (based on the key) as a hash array containing 'key' and 'value' items. [% users = { tom => 'Thomas', dick => 'Richard', larry => 'Lawrence', } %] [% FOREACH u IN users %] * [% u.key %] : [% u.value %] [% END %] Output: * dick : Richard * larry : Lawrence * tom : Thomas The C<NEXT> directive starts the next iteration in the C<FOREACH> loop. [% FOREACH user IN userlist %] [% NEXT IF user.isguest %] Name: [% user.name %] Email: [% user.email %] [% END %] The C<LAST> directive can be used to prematurely exit the loop. C<BREAK> is also provided as an alias for C<LAST>. [% FOREACH match IN results.nsort('score').reverse %] [% LAST IF match.score < 50 %] [% match.score %] : [% match.url %] [% END %] The C<FOREACH> directive is implemented using the L<Template::Iterator> module. A reference to the iterator object for a C<FOREACH> directive is implicitly available in the C<loop> variable. The following methods can be called on the C<loop> iterator. size() number of elements in the list max() index number of last element (size - 1) index() index of current iteration from 0 to max() count() iteration counter from 1 to size() (i.e. index() + 1) first() true if the current iteration is the first last() true if the current iteration is the last prev() return the previous item in the list next() return the next item in the list See L<Template::Iterator> for further details. Example: [% FOREACH item IN [ 'foo', 'bar', 'baz' ] -%] [%- "<ul>\n" IF loop.first %] <li>[% loop.count %]/[% loop.size %]: [% item %] [%- "</ul>\n" IF loop.last %] [% END %] Output: <ul> <li>1/3: foo <li>2/3: bar <li>3/3: baz </ul> Nested loops will work as expected, with the C<loop> variable correctly referencing the innermost loop and being restored to any previous value (i.e. an outer loop) at the end of the loop. [% FOREACH group IN grouplist; # loop => group iterator "Groups:\n" IF loop.first; FOREACH user IN group.userlist; # loop => user iterator "$loop.count: $user.name\n"; END; # loop => group iterator "End of Groups\n" IF loop.last; END %] The C<iterator> plugin can also be used to explicitly create an iterator object. This can be useful within nested loops where you need to keep a reference to the outer iterator within the inner loop. The iterator plugin effectively allows you to create an iterator by a name other than C<loop>. See L<Template::Plugin::Iterator> for further details. [% USE giter = iterator(grouplist) %] [% FOREACH group IN giter %] [% FOREACH user IN group.userlist %] user #[% loop.count %] in group [% giter.count %] is named [% user.name %] [% END %] [% END %] =head2 WHILE The C<WHILE> directive can be used to repeatedly process a template block while a conditional expression evaluates true. The expression may be arbitrarily complex as per C<IF> / C<UNLESS>. [% WHILE total < 100 %] ... [% total = calculate_new_total %] [% END %] An assignment can be enclosed in parenthesis to evaluate the assigned value. [% WHILE (user = get_next_user_record) %] [% user.name %] [% END %] The C<NEXT> directive can be used to start the next iteration of a C<WHILE> loop and C<BREAK> can be used to exit the loop, both as per C<FOREACH>. The Template Toolkit uses a failsafe counter to prevent runaway C<WHILE> loops which would otherwise never terminate. If the loop exceeds 1000 iterations then an C<undef> exception will be thrown, reporting the error: WHILE loop terminated (> 1000 iterations) The C<$Template::Directive::WHILE_MAX> variable controls this behaviour and can be set to a higher value if necessary. =head1 Filters, Plugins, Macros and Perl =head2 FILTER The C<FILTER> directive can be used to post-process the output of a block. A number of standard filters are provided with the Template Toolkit. The C<html> filter, for example, escapes the 'E<lt>', 'E<gt>' and '&' characters to prevent them from being interpreted as HTML tags or entity reference markers. [% FILTER html %] HTML text may have < and > characters embedded which you want converted to the correct HTML entities. [% END %] output: HTML text may have < and > characters embedded which you want converted to the correct HTML entities. The C<FILTER> directive can also follow various other non-block directives. For example: [% INCLUDE mytext FILTER html %] The C<|> character can also be used as an alias for C<FILTER>. [% INCLUDE mytext | html %] Multiple filters can be chained together and will be called in sequence. [% INCLUDE mytext FILTER html FILTER html_para %] or [% INCLUDE mytext | html | html_para %] Filters come in two flavours, known as 'static' or 'dynamic'. A static filter is a simple subroutine which accepts a text string as the only argument and returns the modified text. The C<html> filter is an example of a static filter, implemented as: sub html_filter { my $text = shift; for ($text) { s/&/&/g; s/</</g; s/>/>/g; } return $text; } Dynamic filters can accept arguments which are specified when the filter is called from a template. The C<repeat> filter is such an example, accepting a numerical argument which specifies the number of times that the input text should be repeated. [% FILTER repeat(3) %]blah [% END %] output: blah blah blah These are implemented as filter 'factories'. The factory subroutine is passed a reference to the current L<Template::Context> object along with any additional arguments specified. It should then return a subroutine reference (e.g. a closure) which implements the filter. The C<repeat> filter factory is implemented like this: sub repeat_filter_factory { my ($context, $iter) = @_; $iter = 1 unless defined $iter; return sub { my $text = shift; $text = '' unless defined $text; return join('\n', $text) x $iter; } } The C<FILTERS> option, described in L<Template::Manual::Config>, allows custom filters to be defined when a Template object is instantiated. The L<define_filter()|Template::Context#define_filter()> method allows further filters to be defined at any time. When using a filter, it is possible to assign an alias to it for further use. This is most useful for dynamic filters that you want to re-use with the same configuration. [% FILTER echo = repeat(2) %] Is there anybody out there? [% END %] [% FILTER echo %] Mother, should I build a wall? [% END %] Output: Is there anybody out there? Is there anybody out there? Mother, should I build a wall? Mother, should I build a wall? The C<FILTER> directive automatically quotes the name of the filter. As with C<INCLUDE> et al, you can use a variable to provide the name of the filter, prefixed by C<$>. [% myfilter = 'html' %] [% FILTER $myfilter %] # same as [% FILTER html %] ... [% END %] A template variable can also be used to define a static filter subroutine. However, the Template Toolkit will automatically call any subroutine bound to a variable and use the value returned. Thus, the above example could be implemented as: my $vars = { myfilter => sub { return 'html' }, }; template: [% FILTER $myfilter %] # same as [% FILTER html %] ... [% END %] To define a template variable that evaluates to a subroutine reference that can be used by the C<FILTER> directive, you should create a subroutine that, when called automatically by the Template Toolkit, returns another subroutine reference which can then be used to perform the filter operation. Note that only static filters can be implemented in this way. my $vars = { myfilter => sub { \&my_filter_sub }, }; sub my_filter_sub { my $text = shift; # do something return $text; } template: [% FILTER $myfilter %] ... [% END %] Alternately, you can bless a subroutine reference into a class (any class will do) to fool the Template Toolkit into thinking it's an object rather than a subroutine. This will then bypass the automatic "call-a-subroutine-to-return-a-value" magic. my $vars = { myfilter => bless(\&my_filter_sub, 'anything_you_like'), }; template: [% FILTER $myfilter %] ... [% END %] Filters bound to template variables remain local to the variable context in which they are defined. That is, if you define a filter in a C<PERL> block within a template that is loaded via C<INCLUDE>, then the filter definition will only exist until the end of that template when the stash is delocalised, restoring the previous variable state. If you want to define a filter which persists for the lifetime of the processor, or define additional dynamic filter factories, then you can call the L<define_filter()|Template::Context#define_filter()> method on the current L<Template::Context> object. See L<Template::Manual::Filters> for a complete list of available filters, their descriptions and examples of use. =head2 USE The C<USE> directive can be used to load and initialise "plugin" extension modules. [% USE myplugin %] A plugin is a regular Perl module that conforms to a particular object-oriented interface, allowing it to be loaded into and used automatically by the Template Toolkit. For details of this interface and information on writing plugins, consult L<Template::Plugin>. A number of standard plugins are included with the Template Toolkit (see below and L<Template::Manual::Plugins>). The names of these standard plugins are case insensitive. [% USE CGI %] # => Template::Plugin::CGI [% USE Cgi %] # => Template::Plugin::CGI [% USE cgi %] # => Template::Plugin::CGI You can also define further plugins using the C<PLUGINS> option. my $tt = Template->new({ PLUGINS => { foo => 'My::Plugin::Foo', bar => 'My::Plugin::Bar', }, }); The recommended convention is to specify these plugin names in lower case. The Template Toolkit first looks for an exact case-sensitive match and then tries the lower case conversion of the name specified. [% USE Foo %] # look for 'Foo' then 'foo' If you define all your C<PLUGINS> with lower case names then they will be located regardless of how the user specifies the name in the C<USE> directive. If, on the other hand, you define your C<PLUGINS> with upper or mixed case names then the name specified in the C<USE> directive must match the case exactly. If the plugin isn't defined in either the standard plugins (C<$Template::Plugins::STD_PLUGINS>) or via the C<PLUGINS> option, then the C<PLUGIN_BASE> is searched. In this case the plugin name I<is> case-sensitive. It is appended to each of the C<PLUGIN_BASE> module namespaces in turn (default: C<Template::Plugin>) to construct a full module name which it attempts to locate and load. Any periods, 'C<.>', in the name will be converted to 'C<::>'. [% USE MyPlugin %] # => Template::Plugin::MyPlugin [% USE Foo.Bar %] # => Template::Plugin::Foo::Bar The C<LOAD_PERL> option (disabled by default) provides a further way by which external Perl modules may be loaded. If a regular Perl module (i.e. not a C<Template::Plugin::*> or other module relative to some C<PLUGIN_BASE>) supports an object-oriented interface and a C<new()> constructor then it can be loaded and instantiated automatically. The following trivial example shows how the IO::File module might be used. [% USE file = IO.File('/tmp/mydata') %] [% WHILE (line = file.getline) %] <!-- [% line %] --> [% END %] Any additional parameters supplied in parenthesis after the plugin name will be also be passed to the C<new()> constructor. A reference to the current L<Template::Context> object is passed as the first parameter. [% USE MyPlugin('foo', 123) %] equivalent to: Template::Plugin::MyPlugin->new($context, 'foo', 123); The only exception to this is when a module is loaded via the C<LOAD_PERL> option. In this case the C<$context> reference is I<not> passed to the C<new()> constructor. This is based on the assumption that the module is a regular Perl module rather than a Template Toolkit plugin so isn't expecting a context reference and wouldn't know what to do with it anyway. Named parameters may also be specified. These are collated into a hash which is passed by reference as the last parameter to the constructor, as per the general code calling interface. [% USE url('/cgi-bin/foo', mode='submit', debug=1) %] equivalent to: Template::Plugin::URL->new( $context, '/cgi-bin/foo' { mode => 'submit', debug => 1 } ); The plugin may represent any data type; a simple variable, hash, list or code reference, but in the general case it will be an object reference. Methods can be called on the object (or the relevant members of the specific data type) in the usual way: [% USE table(mydata, rows=3) %] [% FOREACH row IN table.rows %] <tr> [% FOREACH item IN row %] <td>[% item %]</td> [% END %] </tr> [% END %] An alternative name may be provided for the plugin by which it can be referenced: [% USE scores = table(myscores, cols=5) %] [% FOREACH row IN scores.rows %] ... [% END %] You can use this approach to create multiple plugin objects with different configurations. This example shows how the L<format|Template::Plugin::Format> plugin is used to create sub-routines bound to variables for formatting text as per C<printf()>. [% USE bold = format('<b>%s</b>') %] [% USE ital = format('<i>%s</i>') %] [% bold('This is bold') %] [% ital('This is italic') %] Output: <b>This is bold</b> <i>This is italic</i> This next example shows how the L<URL|Template::Plugin::URL> plugin can be used to build dynamic URLs from a base part and optional query parameters. [% USE mycgi = URL('/cgi-bin/foo.pl', debug=1) %] <a href="[% mycgi %]">... <a href="[% mycgi(mode='submit') %]"... Output: <a href="/cgi-bin/foo.pl?debug=1">... <a href="/cgi-bin/foo.pl?mode=submit&debug=1">... The L<CGI|Template::Plugin::CGI> plugin is an example of one which delegates to another Perl module. In this case, to Lincoln Stein's C<CGI> module. All of the methods provided by the C<CGI> module are available via the plugin. [% USE CGI; CGI.start_form; CGI.checkbox_group( name = 'colours', values = [ 'red' 'green' 'blue' ] ); CGI.popup_menu( name = 'items', values = [ 'foo' 'bar' 'baz' ] ); CGI.end_form %] See L<Template::Manual::Plugins> for more information on the plugins distributed with the toolkit or available from CPAN. =head2 MACRO The C<MACRO> directive allows you to define a directive or directive block which is then evaluated each time the macro is called. [% MACRO header INCLUDE header %] Calling the macro as: [% header %] is then equivalent to: [% INCLUDE header %] Macros can be passed named parameters when called. These values remain local to the macro. [% header(title='Hello World') %] equivalent to: [% INCLUDE header title='Hello World' %] A C<MACRO> definition may include parameter names. Values passed to the macros are then mapped to these local variables. Other named parameters may follow these. [% MACRO header(title) INCLUDE header %] [% header('Hello World') %] [% header('Hello World', bgcol='#123456') %] equivalent to: [% INCLUDE header title='Hello World' %] [% INCLUDE header title='Hello World' bgcol='#123456' %] Here's another example, defining a macro for display numbers in comma-delimited groups of 3, using the chunk and join virtual method. [% MACRO number(n) GET n.chunk(-3).join(',') %] [% number(1234567) %] # 1,234,567 A C<MACRO> may precede any directive and must conform to the structure of the directive. [% MACRO header IF frames %] [% INCLUDE frames/header %] [% ELSE %] [% INCLUDE header %] [% END %] [% header %] A C<MACRO> may also be defined as an anonymous C<BLOCK>. The block will be evaluated each time the macro is called. [% MACRO header BLOCK %] ...content... [% END %] [% header %] If you've got the C<EVAL_PERL> option set, then you can even define a C<MACRO> as a C<PERL> block (see below): [% MACRO triple(n) PERL %] my $n = $stash->get('n'); print $n * 3; [% END -%] =head2 PERL (for the advanced reader) The C<PERL> directive is used to mark the start of a block which contains Perl code for evaluation. The C<EVAL_PERL> option must be enabled for Perl code to be evaluated or a C<perl> exception will be thrown with the message 'C<EVAL_PERL not set>'. Perl code is evaluated in the C<Template::Perl> package. The C<$context> package variable contains a reference to the current L<Template::Context> object. This can be used to access the functionality of the Template Toolkit to process other templates, load plugins, filters, etc. See L<Template::Context> for further details. [% PERL %] print $context->include('myfile'); [% END %] The L<$stash> variable contains a reference to the top-level stash object which manages template variables. Through this, variable values can be retrieved and updated. See L<Template::Stash> for further details. [% PERL %] $stash->set(foo => 'bar'); print "foo value: ", $stash->get('foo'); [% END %] Output: foo value: bar Output is generated from the C<PERL> block by calling C<print()>. Note that the C<Template::Perl::PERLOUT> handle is selected (tied to an output buffer) instead of C<STDOUT>. [% PERL %] print "foo\n"; # OK print PERLOUT "bar\n"; # OK, same as above print Template::Perl::PERLOUT "baz\n"; # OK, same as above print STDOUT "qux\n"; # WRONG! [% END %] The C<PERL> block may contain other template directives. These are processed before the Perl code is evaluated. [% name = 'Fred Smith' %] [% PERL %] print "[% name %]\n"; [% END %] Thus, the Perl code in the above example is evaluated as: print "Fred Smith\n"; Exceptions may be thrown from within C<PERL> blocks using C<die()>. They will be correctly caught by enclosing C<TRY> blocks. [% TRY %] [% PERL %] die "nothing to live for\n"; [% END %] [% CATCH %] error: [% error.info %] [% END %] output: error: nothing to live for =head2 RAWPERL (for the very advanced reader) The Template Toolkit parser reads a source template and generates the text of a Perl subroutine as output. It then uses C<eval()> to evaluate it into a subroutine reference. This subroutine is then called to process the template, passing a reference to the current L<Template::Context> object through which the functionality of the Template Toolkit can be accessed. The subroutine reference can be cached, allowing the template to be processed repeatedly without requiring any further parsing. For example, a template such as: [% PROCESS header %] The [% animal %] sat on the [% location %] [% PROCESS footer %] is converted into the following Perl subroutine definition: sub { my $context = shift; my $stash = $context->stash; my $output = ''; my $error; eval { BLOCK: { $output .= $context->process('header'); $output .= "The "; $output .= $stash->get('animal'); $output .= " sat on the "; $output .= $stash->get('location'); $output .= $context->process('footer'); $output .= "\n"; } }; if ($@) { $error = $context->catch($@, \$output); die $error unless $error->type eq 'return'; } return $output; } To examine the Perl code generated, such as in the above example, set the C<$Template::Parser::DEBUG> package variable to any true value. You can also set the C<$Template::Directive::PRETTY> variable true to have the code formatted in a readable manner for human consumption. The source code for each generated template subroutine will be printed to C<STDERR> on compilation (i.e. the first time a template is used). $Template::Parser::DEBUG = 1; $Template::Directive::PRETTY = 1; $template->process($file, $vars) || die $template->error(), "\n"; The C<PERL> ... C<END> construct allows Perl code to be embedded into a template when the C<EVAL_PERL> option is set. It is evaluated at "runtime" using C<eval()> each time the template subroutine is called. This is inherently flexible, but not as efficient as it could be, especially in a persistent server environment where a template may be processed many times. The C<RAWPERL> directive allows you to write Perl code that is integrated directly into the generated Perl subroutine text. It is evaluated once at compile time and is stored in cached form as part of the compiled template subroutine. This makes C<RAWPERL> blocks more efficient than C<PERL> blocks. The downside is that you must code much closer to the metal. For example, in a C<PERL> block you can call L<print()> to generate some output. C<RAWPERL> blocks don't afford such luxury. The code is inserted directly into the generated subroutine text and should conform to the convention of appending to the C<$output> variable. [% PROCESS header %] [% RAWPERL %] $output .= "Some output\n"; ... $output .= "Some more output\n"; [% END %] The critical section of the generated subroutine for this example would then look something like: ... eval { BLOCK: { $output .= $context->process('header'); $output .= "\n"; $output .= "Some output\n"; ... $output .= "Some more output\n"; $output .= "\n"; } }; ... As with C<PERL> blocks, the L<$context|Template::Context> and L<$stash|Template::Stash> references are pre-defined and available for use within C<RAWPERL> code. =head1 Exception Handling and Flow Control =head2 TRY / THROW / CATCH / FINAL (more advanced material) The Template Toolkit supports fully functional, nested exception handling. The C<TRY> directive introduces an exception handling scope which continues until the matching C<END> directive. Any errors that occur within that block will be caught and can be handled by one of the C<CATCH> blocks defined. [% TRY %] ...blah...blah... [% CALL somecode %] ...etc... [% INCLUDE someblock %] ...and so on... [% CATCH %] An error occurred! [% END %] Errors are raised as exceptions (objects of the L<Template::Exception> class) which contain two fields: C<type> and C<info>. The exception C<type> is used to indicate the kind of error that occurred. It is a simple text string which can contain letters, numbers, 'C<_>' or 'C<.>'. The C<info> field contains an error message indicating what actually went wrong. Within a catch block, the exception object is aliased to the C<error> variable. You can access the C<type> and C<info> fields directly. [% mydsn = 'dbi:MySQL:foobar' %] ... [% TRY %] [% USE DBI(mydsn) %] [% CATCH %] ERROR! Type: [% error.type %] Info: [% error.info %] [% END %] output (assuming a non-existent database called 'C<foobar>'): ERROR! Type: DBI Info: Unknown database "foobar" The C<error> variable can also be specified by itself and will return a string of the form "C<$type error - $info>". ... [% CATCH %] ERROR: [% error %] [% END %] Output: ERROR: DBI error - Unknown database "foobar" Each C<CATCH> block may be specified with a particular exception type denoting the kind of error that it should catch. Multiple C<CATCH> blocks can be provided to handle different types of exception that may be thrown in the C<TRY> block. A C<CATCH> block specified without any type, as in the previous example, is a default handler which will catch any otherwise uncaught exceptions. This can also be specified as C<[% CATCH DEFAULT %]>. [% TRY %] [% INCLUDE myfile %] [% USE DBI(mydsn) %] [% CALL somecode %] [% CATCH file %] File Error! [% error.info %] [% CATCH DBI %] [% INCLUDE database/error.html %] [% CATCH %] [% error %] [% END %] Remember that you can specify multiple directives within a single tag, each delimited by 'C<;>'. So the above example can be written more concisely as: [% TRY; INCLUDE myfile; USE DBI(mydsn); CALL somecode; CATCH file; "File Error! $error.info"; CATCH DBI; INCLUDE database/error.html; CATCH; error; END %] The C<DBI> plugin throws exceptions of the C<DBI> type (in case that wasn't already obvious). The other specific exception caught here is of the C<file> type. A C<file> exception is automatically thrown by the Template Toolkit when it can't find a file, or fails to load, parse or process a file that has been requested by an C<INCLUDE>, C<PROCESS>, C<INSERT> or C<WRAPPER> directive. If C<myfile> can't be found in the example above, the C<[% INCLUDE myfile %]> directive will raise a C<file> exception which is then caught by the C<[% CATCH file %]> block. The output generated would be: File Error! myfile: not found Note that the C<DEFAULT> option (disabled by default) allows you to specify a default file to be used any time a template file can't be found. This will prevent file exceptions from ever being raised when a non-existent file is requested (unless, of course, the C<DEFAULT> file your specify doesn't exist). Errors encountered once the file has been found (i.e. read error, parse error) will be raised as file exceptions as per usual. Uncaught exceptions (i.e. if the C<TRY> block doesn't have a type specific or default C<CATCH> handler) may be caught by enclosing C<TRY> blocks which can be nested indefinitely across multiple templates. If the error isn't caught at any level then processing will stop and the Template L<process()|Template#process()> method will return a false value to the caller. The relevant L<Template::Exception> object can be retrieved by calling the L<error()|Template#error()> method. [% TRY %] ... [% TRY %] [% INCLUDE $user.header %] [% CATCH file %] [% INCLUDE header %] [% END %] ... [% CATCH DBI %] [% INCLUDE database/error.html %] [% END %] In this example, the inner C<TRY> block is used to ensure that the first C<INCLUDE> directive works as expected. We're using a variable to provide the name of the template we want to include, C<user.header>, and it's possible this contains the name of a non-existent template, or perhaps one containing invalid template directives. If the C<INCLUDE> fails with a C<file> error then we C<CATCH> it in the inner block and C<INCLUDE> the default C<header> file instead. Any C<DBI> errors that occur within the scope of the outer C<TRY> block will be caught in the relevant C<CATCH> block, causing the C<database/error.html> template to be processed. Note that included templates inherit all currently defined template variable so these error files can quite happily access the <error> variable to retrieve information about the currently caught exception. For example, the C<database/error.html> template might look like this: <h2>Database Error</h2> A database error has occurred: [% error.info %] You can also specify a C<FINAL> block. This is always processed regardless of the outcome of the C<TRY> and/or C<CATCH> blocks. If an exception is uncaught then the C<FINAL> block is processed before jumping to the enclosing block or returning to the caller. [% TRY %] ... [% CATCH this %] ... [% CATCH that %] ... [% FINAL %] All done! [% END %] The output from the C<TRY> block is left intact up to the point where an exception occurs. For example, this template: [% TRY %] This gets printed [% THROW food 'carrots' %] This doesn't [% CATCH food %] culinary delights: [% error.info %] [% END %] generates the following output: This gets printed culinary delights: carrots The C<CLEAR> directive can be used in a C<CATCH> or C<FINAL> block to clear any output created in the C<TRY> block. [% TRY %] This gets printed [% THROW food 'carrots' %] This doesn't [% CATCH food %] [% CLEAR %] culinary delights: [% error.info %] [% END %] Output: culinary delights: carrots Exception types are hierarchical, with each level being separated by the familiar dot operator. A C<DBI.connect> exception is a more specific kind of C<DBI> error. Similarly, an C<example.error.barf> is a more specific kind of C<example.error> type which itself is also a C<example> error. A C<CATCH> handler that specifies a general exception type (such as C<DBI> or C<example.error>) will also catch more specific types that have the same prefix as long as a more specific handler isn't defined. Note that the order in which C<CATCH> handlers are defined is irrelevant; a more specific handler will always catch an exception in preference to a more generic or default one. [% TRY %] ... [% CATCH DBI ; INCLUDE database/error.html ; CATCH DBI.connect ; INCLUDE database/connect.html ; CATCH ; INCLUDE error.html ; END %] In this example, a C<DBI.connect> error has it's own handler, a more general C<DBI> block is used for all other C<DBI> or C<DBI.*> errors and a default handler catches everything else. Exceptions can be raised in a template using the C<THROW> directive. The first parameter is the exception type which doesn't need to be quoted (but can be, it's the same as C<INCLUDE>) followed by the relevant error message which can be any regular value such as a quoted string, variable, etc. [% THROW food "Missing ingredients: $recipe.error" %] [% THROW user.login 'no user id: please login' %] [% THROW $myerror.type "My Error: $myerror.info" %] It's also possible to specify additional positional or named parameters to the C<THROW> directive if you want to pass more than just a simple message back as the error info field. [% THROW food 'eggs' 'flour' msg='Missing Ingredients' %] In this case, the error C<info> field will be a hash array containing the named arguments and an C<args> item which contains a list of the positional arguments. type => 'food', info => { msg => 'Missing Ingredients', args => ['eggs', 'flour'], } In addition to specifying individual positional arguments as C<[% error.info.args.n %]>, the C<info> hash contains keys directly pointing to the positional arguments, as a convenient shortcut. [% error.info.0 %] # same as [% error.info.args.0 %] Exceptions can also be thrown from Perl code which you've bound to template variables, or defined as a plugin or other extension. To raise an exception, call C<die()> passing a reference to a L<Template::Exception> object as the argument. This will then be caught by any enclosing C<TRY> blocks from where the code was called. use Template::Exception; ... my $vars = { foo => sub { # ... do something ... die Template::Exception->new('myerr.naughty', 'Bad, bad error'); }, }; Template: [% TRY %] [% foo %] [% CATCH myerr ; "Error: $error" ; END %] Output: Error: myerr.naughty error - Bad, bad error The C<info> field can also be a reference to another object or data structure, if required. die Template::Exception->new('myerror', { module => 'foo.pl', errors => [ 'bad permissions', 'naughty boy' ], }); Later, in a template: [% TRY %] ... [% CATCH myerror %] [% error.info.errors.size or 'no'; error.info.errors.size == 1 ? ' error' : ' errors' %] in [% error.info.module %]: [% error.info.errors.join(', ') %]. [% END %] Generating the output: 2 errors in foo.pl: bad permissions, naughty boy. You can also call C<die()> with a single string, as is common in much existing Perl code. This will automatically be converted to an exception of the 'C<undef>' type (that's the literal string 'C<undef>', not the undefined value). If the string isn't terminated with a newline then Perl will append the familiar C<" at $file line $line"> message. sub foo { # ... do something ... die "I'm sorry, Dave, I can't do that\n"; } If you're writing a plugin, or some extension code that has the current L<Template::Context> in scope (you can safely skip this section if this means nothing to you) then you can also raise an exception by calling the context L<throw()|Template::Context#throw()> method. You can pass it an L<Template::Exception> object reference, a pair of C<($type, $info)> parameters or just an C<$info> string to create an exception of 'C<undef>' type. $context->throw($e); # exception object $context->throw('Denied'); # 'undef' type $context->throw('user.passwd', 'Bad Password'); =head2 NEXT The C<NEXT> directive can be used to start the next iteration of a C<FOREACH> or C<WHILE> loop. [% FOREACH user IN users %] [% NEXT IF user.isguest %] Name: [% user.name %] Email: [% user.email %] [% END %] =head2 LAST The C<LAST> directive can be used to prematurely exit a C<FOREACH> or C<WHILE> loop. [% FOREACH user IN users %] Name: [% user.name %] Email: [% user.email %] [% LAST IF some.condition %] [% END %] C<BREAK> can also be used as an alias for C<LAST>. =head2 RETURN The C<RETURN> directive can be used to stop processing the current template and return to the template from which it was called, resuming processing at the point immediately after the C<INCLUDE>, C<PROCESS> or C<WRAPPER> directive. If there is no enclosing template then the Template L<process()|Template#process()> method will return to the calling code with a true value. Before [% INCLUDE half_wit %] After [% BLOCK half_wit %] This is just half... [% RETURN %] ...a complete block [% END %] Output: Before This is just half... After =head2 STOP The C<STOP> directive can be used to indicate that the processor should stop gracefully without processing any more of the template document. This is a planned stop and the Template L<process()|Template#process()> method will return a B<true> value to the caller. This indicates that the template was processed successfully according to the directives within it. [% IF something.terrible.happened %] [% INCLUDE fatal/error.html %] [% STOP %] [% END %] [% TRY %] [% USE DBI(mydsn) %] ... [% CATCH DBI.connect %] <h1>Cannot connect to the database: [% error.info %]</h1> <p> We apologise for the inconvenience. </p> [% INCLUDE footer %] [% STOP %] [% END %] =head2 CLEAR The C<CLEAR> directive can be used to clear the output buffer for the current enclosing block. It is most commonly used to clear the output generated from a C<TRY> block up to the point where the error occurred. [% TRY %] blah blah blah # this is normally left intact [% THROW some 'error' %] # up to the point of error ... [% CATCH %] [% CLEAR %] # clear the TRY output [% error %] # print error string [% END %] =head1 Miscellaneous =head2 META The C<META> directive allows simple metadata items to be defined within a template. These are evaluated when the template is parsed and as such may only contain simple values (e.g. it's not possible to interpolate other variables values into C<META> variables). [% META title = 'The Cat in the Hat' author = 'Dr. Seuss' version = 1.23 %] The C<template> variable contains a reference to the main template being processed. These metadata items may be retrieved as attributes of the template. <h1>[% template.title %]</h1> <h2>[% template.author %]</h2> The C<name> and C<modtime> metadata items are automatically defined for each template to contain its name and modification time in seconds since the epoch. [% USE date %] # use Date plugin to format time ... [% template.name %] last modified at [% date.format(template.modtime) %] The C<PRE_PROCESS> and C<POST_PROCESS> options allow common headers and footers to be added to all templates. The C<template> reference is correctly defined when these templates are processed, allowing headers and footers to reference metadata items from the main template. $template = Template->new({ PRE_PROCESS => 'header', POST_PROCESS => 'footer', }); $template->process('cat_in_hat'); header: <html> <head> <title>[% template.title %]</title> </head> <body> cat_in_hat: [% META title = 'The Cat in the Hat' author = 'Dr. Seuss' version = 1.23 year = 2000 %] The cat in the hat sat on the mat. footer: <hr> © [% template.year %] [% template.author %] </body> </html> The output generated from the above example is: <html> <head> <title>The Cat in the Hat</title> </head> <body> The cat in the hat sat on the mat. <hr> © 2000 Dr. Seuss </body> </html> =head2 TAGS The C<TAGS> directive can be used to set the C<START_TAG> and C<END_TAG> values on a per-template file basis. [% TAGS <+ +> %] <+ INCLUDE header +> The TAGS directive may also be used to set a named C<TAG_STYLE> [% TAGS html %] <!-- INCLUDE header --> See the L<TAGS|Template::Manual::Config#TAGS> and L<TAG_STYLE|Template::Manual::Config#TAG_STYLE> configuration options for further details. =head2 DEBUG The C<DEBUG> directive can be used to enable or disable directive debug messages within a template. The C<DEBUG> configuration option must be set to include C<DEBUG_DIRS> for the C<DEBUG> directives to have any effect. If C<DEBUG_DIRS> is not set then the parser will automatically ignore and remove any C<DEBUG> directives. The C<DEBUG> directive can be used with an C<on> or C<off> parameter to enable or disable directive debugging messages from that point forward. When enabled, the output of each directive in the generated output will be prefixed by a comment indicate the file, line and original directive text. [% DEBUG on %] directive debugging is on (assuming DEBUG option is set true) [% DEBUG off %] directive debugging is off The C<format> parameter can be used to change the format of the debugging message. [% DEBUG format '<!-- $file line $line : [% $text %] -->' %] =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: Views.pod 0000444 00000045500 14711272044 0006351 0 ustar 00 #============================================================= -*-perl-*- # # Template::Manual::Views # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Manual::Views - Template Toolkit views (experimental) =head1 Overview A view is effectively a collection of templates and/or variable definitions which can be passed around as a self-contained unit. This then represents a particular interface or presentation style for other objects or items of data. You can use views to implement custom "skins" for an application or content set. You can use them to help simplify the presentation of common objects or data types. You can even use then to automate the presentation of complex data structures such as that generated in an C<XML::DOM> tree or similar. You let an iterator do the walking, and the view does the talking (or in this case, the presenting). Voila - you have view independent, structure shy traversal using templates. In general, views can be used in a number of different ways to achieve several different things. They elegantly solve some problems which were otherwise difficult or complicated, and make easy some things that were previously hard. At the moment, they're still very experimental. The directive syntax and underlying API are likely to change quite considerably over the next version or two. Please be very wary about building your multi-million dollar e-commerce solutions based around this feature. =head1 Views as Template Collectors/Providers The C<VIEW> directive starts a view definition and includes a name by which the view can be referenced. The view definition continues up to the matching C<END> directive. [% VIEW myview %] ... [% END %] The first role of a view is to act as a collector and provider of templates. The C<include()> method can be called on a view to effectively do the same thing as the C<INCLUDE> directive. The template name is passed as the first argument, followed by any local variable definitions for the template. [% myview.include('header', title='The Title') %] # equivalent to [% INCLUDE header title='The Title' %] Views accept a number of configuration options which can be used to control different aspects of their behaviour. The 'C<prefix>' and 'C<suffix>' options can be specified to add a fixed prefix and/or suffix to the name of each template. [% VIEW myview prefix = 'my/' suffix = '.tt2' ; END %] Now the call [% myview.include('header', title='The Title') %] is equivalent to [% INCLUDE my/header.tt2 title='The Title' %] Views provide an C<AUTOLOAD> method which maps method names to the C<include()> method. Thus, the following are all equivalent: [% myview.include('header', title='Hello World') %] [% myview.include_header(title='Hello World') %] [% myview.header(title='Hello World') %] =head1 Local BLOCK Definitions A C<VIEW> definition can include C<BLOCK> definitions which remain local to the view. A request for a particular template will return a C<BLOCK>, if defined, in preference to any other template of the same name. [% BLOCK foo %] public foo block [% END %] [% VIEW plain %] [% BLOCK foo %] plain foo block [% END %] [% END %] [% VIEW fancy %] [% BLOCK foo %] fancy foo block [% END %] [% END %] [% INCLUDE foo %] # public foo block [% plain.foo %] # plain foo block [% fancy.foo %] # fancy foo block In addition to C<BLOCK> definitions, a C<VIEW> can contain any other template directives. The entire C<VIEW> definition block is processed to initialise the view but no output is generated (this may change RSN - and get stored as 'C<output>' item, subsequently accessible as C<[% view.output %]>). However, directives that have side-effects, such as those that update a variable, will have noticeable consequences. =head1 Preserving Variable State within Views Views can also be used to save the values of any existing variables, or to create new ones at the point at which the view is defined. Unlike simple template metadata (C<META>) which can only contain static string values, the view initialisation block can contain any template directives and generate any kind of dynamic output and/or data items. [% VIEW my_web_site %] [% view.title = title or 'My Cool Web Site' %] [% view.author = "$abw.name, $abw.email" %] [% view.sidebar = INCLUDE my/sidebar.tt2 %] [% END %] Note that additional data items can be specified as arguments to the C<VIEW> directive. Anything that doesn't look like a configuration parameter is assumed to be a data item. This can be a little hazardous, of course, because you never know when a new configuration item might get added which interferes with your data. [% VIEW my_web_site # config options prefix = 'my/' # misc data title = title or 'My Cool Web Site' author = "$abw.name, $abw.email" sidebar = INCLUDE my/sidebar.tt2 %] ... [% END %] Outside of the view definition you can access the view variables as, for example: [% my_web_site.title %] One important feature is the equivalence of simple variables and templates. You can implement the view item 'C<title>' as a simple variable, a template defined in an external file, possibly with a prefix/suffix automatically appended, or as a local C<BLOCK> definition within the C<[% VIEW %] ... [% END %]> definition. If you use the syntax above then the view will Do The Right Thing to return the appropriate output. At the C<END> of the C<VIEW> definition the view is "sealed" to prevent you from accidentally updating any variable values. If you attempt to change the value of a variable after the C<END> of the C<VIEW> definition block then a C<view> error will be thrown. [% TRY; my_web_site.title = 'New Title'; CATCH; error; END %] The error above will be reported as: view error - cannot update item in sealed view: title The same is true if you pass a parameter to a view variable. This is interpreted as an attempt to update the variable and will raise the same warning. [% my_web_site.title('New Title') %] # view error! You can set the C<silent> parameter to have the view ignore these parameters and simply return the variable value. [% VIEW my_web_site silent = 1 title = title or 'My Cool Web Site' # ... ; END %] [% my_web_site.title('Blah Blah') %] # My Cool Web Site Alternately, you can specify that a view is unsealed allowing existing variables to be updated and new variables defined. [% VIEW my_web_site sealed = 0 title = title or 'My Cool Web Site' # ... ; END %] [% my_web_site.title('Blah Blah') %] # Blah Blah [% my_web_site.title %] # Blah Blah =head2 Inheritance, Delegation and Reuse Views can be inherited from previously defined views by use of the C<base> parameter. This example shows how a base class view is defined which applies a C<view/default/> prefix to all template names. [% VIEW my.view.default prefix = 'view/default/'; END %] Thus the directive: [% my.view.default.header(title='Hello World') %] is now equivalent to: [% INCLUDE view/default/header title='Hello World' %] A second view can be defined which specifies the default view as a base. [% VIEW my.view.fancy base = my.view.default prefix = 'view/fancy/'; END %] Now the directive: [% my.view.fancy.header(title='Hello World') %] will resolve to: [% INCLUDE view/fancy/header title='Hello World' %] or if that doesn't exist, it will be handled by the base view as: [% INCLUDE view/default/header title='Hello World' %] When a parent view is specified via the C<base> parameter, the delegation of a view to its parent for fetching templates and accessing user defined variables is automatic. You can also implement your own inheritance, delegation or other reuse patterns by explicitly delegating to other views. [% BLOCK foo %] public foo block [% END %] [% VIEW plain %] [% BLOCK foo %] <plain>[% PROCESS foo %]</plain> [% END %] [% END %] [% VIEW fancy %] [% BLOCK foo %] [% plain.foo | replace('plain', 'fancy') %] [% END %] [% END %] [% plain.foo %] # <plain>public foo block</plain> [% fancy.foo %] # <fancy>public foo block</fancy> Note that the regular C<INCLUDE/PROCESS/WRAPPER> directives work entirely independently of views and will always get the original, unaltered template name rather than any local per-view definition. =head2 Self-Reference A reference to the view object under definition is available with the C<VIEW ... END> block by its specified name and also by the special name 'C<view>' (similar to the C<my $self = shift;> in a Perl method or the 'C<this>' pointer in C++, etc). The view is initially unsealed allowing any data items to be defined and updated within the C<VIEW ... END> block. The view is automatically sealed at the end of the definition block, preventing any view data from being subsequently changed. (NOTE: sealing should be optional. As well as sealing a view to prevent updates (C<SEALED>), it should be possible to set an option in the view to allow external contexts to update existing variables (C<UPDATE>) or even create totally new view variables (C<CREATE>)). [% VIEW fancy %] [% fancy.title = 'My Fancy Title' %] [% fancy.author = 'Frank Open' %] [% fancy.col = { bg => '#ffffff', bar => '#a0a0ff' } %] [% END %] or [% VIEW fancy %] [% view.title = 'My Fancy Title' %] [% view.author = 'Frank Open' %] [% view.col = { bg => '#ffffff', bar => '#a0a0ff' } %] [% END %] It makes no real difference in this case if you refer to the view by its name, 'C<fancy>', or by the general name, 'C<view>'. Outside of the view block, however, you should always use the given name, 'C<fancy>': [% fancy.title %] [% fancy.author %] [% fancy.col.bg %] The choice of given name or 'C<view>' is much more important when it comes to C<BLOCK> definitions within a C<VIEW>. It is generally recommended that you use 'C<view>' inside a C<VIEW> definition because this is guaranteed to be correctly defined at any point in the future when the block gets called. The original name of the view might have long since been changed or reused but the self-reference via 'C<view>' should always be intact and valid. Take the following VIEW as an example: [% VIEW foo %] [% view.title = 'Hello World' %] [% BLOCK header %] Title: [% view.title %] [% END %] [% END %] Even if we rename the view, or create a new C<foo> variable, the header block still correctly accesses the C<title> attribute of the view to which it belongs. Whenever a view C<BLOCK> is processed, the C<view> variable is always updated to contain the correct reference to the view object to which it belongs. [% bar = foo %] [% foo = { title => "New Foo" } %] # no problem [% bar.header %] # => Title: Hello World =head2 Saving References to External Views When it comes to view inheritance, it's always a good idea to take a local copy of a parent or delegate view and store it as an attribute within the view for later use. This ensures that the correct view reference is always available, even if the external name of a view has been changed. [% VIEW plain %] ... [% END %] [% VIEW fancy %] [% view.plain = plain %] [% BLOCK foo %] [% view.plain.foo | replace('plain', 'fancy') %] [% END %] [% END %] [% plain.foo %] # => <plain>public foo block</plain> [% plain = 'blah' %] # no problem [% fancy.foo %] # => <fancy>public foo block</fancy> =head2 Views as Data Presenters Another key role of a view is to act as a dispatcher to automatically apply the correct template to present a particular object or data item. This is handled via the C<print()> method. Here's an example: [% VIEW foo %] [% BLOCK text %] Some text: [% item %] [% END %] [% BLOCK hash %] a hash: [% FOREACH key = item.keys.sort -%] [% key %] => [% item.$key %] [% END -%] [% END %] [% BLOCK list %] a list: [% item.sort.join(', ') %] [% END %] [% END %] We can now use the view to print text, hashes or lists. The C<print()> method includes the right template depending on the typing of the argument (or arguments) passed. [% some_text = 'I read the news today, oh boy.' %] [% a_hash = { house => 'Lords', hall => 'Albert' } %] [% a_list = [ 'sure', 'Nobody', 'really' ] %] [% view.print(some_text) %] # Some text: I read the news today, oh boy. [% view.print(a_hash) %] # a hash: hall => Albert house => Lords [% view.print(a_list) %] # a list: Nobody, really, sure You can also provide templates to print objects of any other class. The class name is mapped to a template name with all non-word character sequences such as 'C<::>' converted to a single 'C<_>'. [% VIEW foo %] [% BLOCK Foo_Bar %] a Foo::Bar object: thingies: [% view.print(item.thingies) %] doodahs: [% view.print(item.doodahs) %] [% END %] [% END %] [% USE fubar = Foo::Bar(...) %] [% foo.print(fubar) %] Note how we use the view object to display various items within the objects ('C<thingies>' and 'C<doodahs>'). We don't need to worry what kind of data these represent (text, list, hash, etc) because we can let the view worry about it, automatically mapping the data type to the correct template. Views may define their own type =E<gt> template map. [% VIEW foo map = { TEXT => 'plain_text', ARRAY => 'show_list', HASH => 'show_hash', My::Module => 'template_name' default => 'any_old_data' } %] [% BLOCK plain_text %] ... [% END %] ... [% END %] They can also provide a C<default> map entry, specified as part of the C<map> hash or as a parameter by itself. [% VIEW foo map = { ... }, default = 'whatever' %] ... [% END %] or [% VIEW foo %] [% view.map = { ... } view.default = 'whatever' %] ... [% END %] The C<print()> method provides one more piece of magic. If you pass it a reference to an object which provides a C<present()> method, then the method will be called passing the view as an argument. This then gives any object a chance to determine how it should be presented via the view. package Foo::Bar; ... sub present { my ($self, $view) = @_; return "a Foo::Bar object:\n" . "thingies: " . $view->print($self->{ _THINGIES }) . "\n" . "doodahs: " . $view->print($self->{ _DOODAHS }) . "\n"; } The object is free to delve deeply into its innards and mess around with its own private data, before presenting the relevant data via the view. In a more complex example, a C<present()> method might walk part of a tree making calls back against the view to present different nodes within the tree. We may not want to expose the internal structure of the tree (because that would break encapsulation and make our presentation code dependant on it) but we want to have some way of walking the tree and presenting items found in a particular manner. This is known as I<Structure Shy Traversal>. Our view object doesn't require prior knowledge about the internal structure of any data set to be able to traverse it and present the data contained therein. The data items themselves, via the C<present()> method, can implement the internal iterators to guide the view along the right path to presentation happiness. The upshot is that you can use views to greatly simplify the display of data structures like C<XML::DOM> trees. The documentation for the C<Template::Plugin::XML::DOM> module contains an example of this. In essence, it looks something like this: XML source: <user name="Andy Wardley"> <project id="iCan" title="iCan, but theyCan't"/> <project id="p45" title="iDid, but theyDidn't"/> </user> TT View: [% VIEW fancy %] [% BLOCK user %] User: [% item.name %] [% item.content(myview) %] [% END %] [% BLOCK project %] Project: [% project.id %] - [% project.name %] [% END %] [% END %] Generate view: [% USE dom = XML.DOM %] [% fancy.print(dom.parse(xml_source)) %] Output: User: Andy Wardley Project: iCan - iCan, but theyCan't Project: p45 - iDid, but theyDidn't The same approach can be applied to many other areas. Here's an example from the C<File>/C<Directory> plugins. [% VIEW myview %] [% BLOCK file %] - [% item.name %] [% END %] [% BLOCK directory %] * [% item.name %] [% item.content(myview) FILTER indent %] [% END %] [% END %] [% USE dir = Directory(dirpath) %] [% myview.print(dir) %] And here's the same approach use to convert POD documentation to any other format via template. [% # load Pod plugin and parse source file into Pod Object Model USE Pod; pom = Pod.parse_file(my_pod_file); # define view to map all Pod elements to "pod/html/xxx" templates VIEW pod2html prefix='pod/html'; END; # now print document via view (i.e. as HTML) pod2html.print(pom) %] Here we simply define a template prefix for the view which causes the view to look for C<pod/html/head1>, C<pod/html/head2>, C<pod/html/over> as templates to present the different sections of the parsed Pod document. There are some examples in the Template Toolkit test suite: F<t/pod.t> and F<t/view.t> which may shed some more light on this. See the distribution sub-directory F<examples/pod/html> for examples of Pod -E<gt> HTML templates. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: Plugins.pod 0000444 00000021626 14711272045 0006701 0 ustar 00 #============================================================= -*-perl-*- # # Template::Manual::Plugins # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Manual::Plugins - Standard plugins =head1 TEMPLATE TOOLKIT PLUGINS The following plugin modules are distributed with the Template Toolkit. Some of the plugins interface to external modules (detailed below) which should be downloaded from any CPAN site and installed before using the plugin. =head2 Assert New in 2.20! The L<Assert|Template::Plugin::Assert> plugin adds an C<assert> virtual method that you can use to catch undefined values. For example, consider this dotop: [% user.name %] If C<user.name> is an undefined value then TT will silently ignore the fact and print nothing. If you C<USE> the C<assert> plugin then you can add the C<assert> vmethod between the C<user> and C<name> elements, like so: [% user.assert.name %] Now, if C<user.name> is an undefined value, an exception will be thrown: assert error - undefined value for name =head2 CGI The L<CGI|Template::Plugin::CGI> plugin is a wrapper around Lincoln Stein's CGI.pm module. The plugin is distributed with the Template Toolkit (see L<Template::Plugin::CGI>) and the L<CGI> module itself is distributed with recent versions Perl, or is available from CPAN. [% USE CGI %] [% CGI.param('param_name') %] [% CGI.start_form %] [% CGI.popup_menu( Name => 'color', Values => [ 'Green', 'Brown' ] ) %] [% CGI.end_form %] =head2 Datafile Provides an interface to data stored in a plain text file in a simple delimited format. The first line in the file specifies field names which should be delimiter by any non-word character sequence. Subsequent lines define data using the same delimiter as in the first line. Blank lines and comments (lines starting '#') are ignored. See L<Template::Plugin::Datafile> for further details. /tmp/mydata: # define names for each field id : email : name : tel # here's the data fred : fred@here.com : Fred Smith : 555-1234 bill : bill@here.com : Bill White : 555-5678 example: [% USE userlist = datafile('/tmp/mydata') %] [% FOREACH user = userlist %] [% user.name %] ([% user.id %]) [% END %] =head2 Date The L<Date|Template::Plugin::Date> plugin provides an easy way to generate formatted time and date strings by delegating to the L<POSIX> C<strftime()> routine. See L<Template::Plugin::Date> and L<POSIX> for further details. [% USE date %] [% date.format %] # current time/date File last modified: [% date.format(template.modtime) %] =head2 Directory The L<Directory|Template::Plugin::Directory> plugin provides a simple interface to a directory and the files within it. See L<Template::Plugin::Directory> for further details. [% USE dir = Directory('/tmp') %] [% FOREACH file = dir.files %] # all the plain files in the directory [% END %] [% FOREACH file = dir.dirs %] # all the sub-directories [% END %] =head2 DBI The C<DBI> plugin is no longer distributed as part of the Template Toolkit (as of version 2.15). It is now available as a separate L<Template::DBI> distribution from CPAN. =head2 Dumper The L<Dumper|Template::Plugin::Dumper> plugin provides an interface to the Data::Dumper module. See L<Template::Plugin::Dumper> and L<Data::Dumper> for further details. [% USE dumper(indent=0, pad="<br>") %] [% dumper.dump(myvar, yourvar) %] =head2 File The L<File|Template::Plugin::File> plugin provides a general abstraction for files and can be used to fetch information about specific files within a filesystem. See L<Template::Plugin::File> for further details. [% USE File('/tmp/foo.html') %] [% File.name %] # foo.html [% File.dir %] # /tmp [% File.mtime %] # modification time =head2 Filter This module implements a base class plugin which can be subclassed to easily create your own modules that define and install new filters. package MyOrg::Template::Plugin::MyFilter; use Template::Plugin::Filter; use base qw( Template::Plugin::Filter ); sub filter { my ($self, $text) = @_; # ...mungify $text... return $text; } Example of use: # now load it... [% USE MyFilter %] # ...and use the returned object as a filter [% FILTER $MyFilter %] ... [% END %] See L<Template::Plugin::Filter> for further details. =head2 Format The L<Format|Template::Plugin::Format> plugin provides a simple way to format text according to a C<printf()>-like format. See L<Template::Plugin::Format> for further details. [% USE bold = format('<b>%s</b>') %] [% bold('Hello') %] =head2 GD The C<GD> plugins are no longer part of the core Template Toolkit distribution. They are now available from CPAN in a separate L<Template::GD> distribution. =head2 HTML The L<HTML|Template::Plugin::HTML> plugin is very basic, implementing a few useful methods for generating HTML. It is likely to be extended in the future or integrated with a larger project to generate HTML elements in a generic way. [% USE HTML %] [% HTML.escape("if (a < b && c > d) ..." %] [% HTML.attributes(border => 1, cellpadding => 2) %] [% HTML.element(table => { border => 1, cellpadding => 2 }) %] See L<Template::Plugin::HTML> for further details. =head2 Iterator The L<Iterator|Template::Plugin::Iterator> plugin provides a way to create a L<Template::Iterator> object to iterate over a data set. An iterator is created automatically by the C<FOREACH> directive and is aliased to the C<loop> variable. This plugin allows an iterator to be explicitly created with a given name, or the default plugin name, C<iterator>. See L<Template::Plugin::Iterator> for further details. [% USE iterator(list, args) %] [% FOREACH item = iterator %] [% '<ul>' IF iterator.first %] <li>[% item %] [% '</ul>' IF iterator.last %] [% END %] =head2 Pod This plugin provides an interface to the L<Pod::POM|Pod::POM> module which parses POD documents into an internal object model which can then be traversed and presented through the Template Toolkit. [% USE Pod(podfile) %] [% FOREACH head1 = Pod.head1; FOREACH head2 = head1/head2; ... END; END %] =head2 Scalar The Template Toolkit calls user-defined subroutines and object methods using Perl's array context by default. # TT2 calls object methods in array context by default [% object.method %] This plugin module provides a way for you to call subroutines and methods in scalar context. [% USE scalar %] # force it to use scalar context [% object.scalar.method %] # also works with subroutine references [% scalar.my_sub_ref %] =head2 String The L<String|Template::Plugin::String> plugin implements an object-oriented interface for manipulating strings. See L<Template::Plugin::String> for further details. [% USE String 'Hello' %] [% String.append(' World') %] [% msg = String.new('Another string') %] [% msg.replace('string', 'text') %] The string "[% msg %]" is [% msg.length %] characters long. =head2 Table The L<Table|Template::Plugin::Table> plugin allows you to format a list of data items into a virtual table by specifying a fixed number of rows or columns, with an optional overlap. See L<Template::Plugin::Table> for further details. [% USE table(list, rows=10, overlap=1) %] [% FOREACH item = table.col(3) %] [% item %] [% END %] =head2 URL The L<URL|Template::Plugin::URL> plugin provides a simple way of constructing URLs from a base part and a variable set of parameters. See L<Template::Plugin::URL> for further details. [% USE mycgi = url('/cgi-bin/bar.pl', debug=1) %] [% mycgi %] # ==> /cgi/bin/bar.pl?debug=1 [% mycgi(mode='submit') %] # ==> /cgi/bin/bar.pl?mode=submit&debug=1 =head2 Wrap The L<Wrap|Template::Plugin::Wrap> plugin uses the L<Text::Wrap> module to provide simple paragraph formatting. See L<Template::Plugin::Wrap> and L<Text::Wrap> for further details. [% USE wrap %] [% wrap(mytext, 40, '* ', ' ') %] # use wrap sub [% mytext FILTER wrap(40) -%] # or wrap FILTER The C<Text::Wrap> module is available from CPAN: http://www.cpan.org/modules/by-module/Text/ =head2 XML The C<XML::DOM>, C<XML::RSS>, C<XML::Simple> and C<XML::XPath> plugins are no longer distributed with the Template Toolkit as of version 2.15 They are now available in a separate L<Template::XML> distribution. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: Config.pod 0000444 00000175431 14711272046 0006472 0 ustar 00 #============================================================= -*-perl-*- # # Template::Manual::Config # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2020 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Manual::Config - Configuration options =head1 Template Style and Parsing Options =head2 ENCODING The C<ENCODING> option specifies the template files' character encoding: my $template = Template->new({ ENCODING => 'utf8', }); A template which starts with a Unicode byte order mark (BOM) will have its encoding detected automatically. =head2 START_TAG, END_TAG The C<START_TAG> and C<END_TAG> options are used to specify character sequences or regular expressions that mark the start and end of inline template directives. The default values for C<START_TAG> and C<END_TAG> are 'C<[%>' and 'C<%]>' respectively, giving us the familiar directive style: [% example %] Any Perl regex characters can be used and therefore should be escaped (or use the Perl C<quotemeta> function) if they are intended to represent literal characters. my $template = Template->new({ START_TAG => quotemeta('<+'), END_TAG => quotemeta('+>'), }); Example: <+ INCLUDE foobar +> The C<TAGS> directive can also be used to set the C<START_TAG> and C<END_TAG> values on a per-template file basis. [% TAGS <+ +> %] =head2 OUTLINE_TAG The C<OUTLINE_TAG> option can be used to enable single-line "outline" directives. my $template = Template->new({ OUTLINE_TAG => '%%', }); This allows you to use both inline and outline tags like so: %% IF user Hello [% user.name %] %% END The C<OUTLINE_TAG> string (or regex) must appear at the start of a line. The directive continues until the end of the line. The newline character at the end of the line is considered to be the invisible end-of-directive marker and is removed. =head2 TAG_STYLE The C<TAG_STYLE> option can be used to set both C<START_TAG> and C<END_TAG> according to pre-defined tag styles. my $template = Template->new({ TAG_STYLE => 'star', }); Available styles are: template [% ... %] (default) template1 [% ... %] or %% ... %% (TT version 1) metatext %% ... %% (Text::MetaText) star [* ... *] (TT alternate) php <? ... ?> (PHP) asp <% ... %> (ASP) mason <% ... > (HTML::Mason) html <!-- ... --> (HTML comments) The C<outline> style uses the default markers for C<START_TAG> and C<END_TAG> (C<[%> and C<%]> respectively) and additionally defines C<OUTLINE_TAG> to be C<%%>. my $template = Template->new({ TAG_STYLE => 'outline', }); This allows you to use both inline and outline tags like so: %% IF user Hello [% user.name %] %% END Any values specified for C<START_TAG>, C<END_TAG> and/or C<OUTLINE_TAG> will override those defined by a C<TAG_STYLE>. The C<TAGS> directive may also be used to set a C<TAG_STYLE> [% TAGS html %] <!-- INCLUDE header --> =head2 PRE_CHOMP, POST_CHOMP Anything outside a directive tag is considered plain text and is generally passed through unaltered (but see the L<INTERPOLATE> option). This includes all whitespace and newlines characters surrounding directive tags. Directives that don't generate any output will leave gaps in the output document. Example: Foo [% a = 10 %] Bar Output: Foo Bar The C<PRE_CHOMP> and C<POST_CHOMP> options can help to clean up some of this extraneous whitespace. Both are disabled by default. my $template = Template->new({ PRE_CHOMP => 1, POST_CHOMP => 1, }); With C<PRE_CHOMP> set to C<1>, the newline and whitespace preceding a directive at the start of a line will be deleted. This has the effect of concatenating a line that starts with a directive onto the end of the previous line. Foo <----------. | ,---(PRE_CHOMP)----' | `-- [% a = 10 %] --. | ,---(POST_CHOMP)---' | `-> Bar With C<POST_CHOMP> set to C<1>, any whitespace after a directive up to and including the newline will be deleted. This has the effect of joining a line that ends with a directive onto the start of the next line. If C<PRE_CHOMP> or C<POST_CHOMP> is set to C<2>, all whitespace including any number of newline will be removed and replaced with a single space. This is useful for HTML, where (usually) a contiguous block of whitespace is rendered the same as a single space. With C<PRE_CHOMP> or C<POST_CHOMP> set to C<3>, all adjacent whitespace (including newlines) will be removed entirely. These values are defined as C<CHOMP_NONE>, C<CHOMP_ONE>, C<CHOMP_COLLAPSE> and C<CHOMP_GREEDY> constants in the L<Template::Constants> module. C<CHOMP_ALL> is also defined as an alias for C<CHOMP_ONE> to provide backwards compatibility with earlier version of the Template Toolkit. Additionally the chomp tag modifiers listed below may also be used for the C<PRE_CHOMP> and C<POST_CHOMP> configuration. my $template = Template->new({ PRE_CHOMP => '~', POST_CHOMP => '-', }); C<PRE_CHOMP> and C<POST_CHOMP> can be activated for individual directives by placing a 'C<->' immediately at the start and/or end of the directive. [% FOREACH user IN userlist %] [%- user -%] [% END %] This has the same effect as C<CHOMP_ONE> in removing all whitespace before or after the directive up to and including the newline. The template will be processed as if written: [% FOREACH user IN userlist %][% user %][% END %] To remove all whitespace including any number of newlines, use the ('C<~>') tilde character instead. [% FOREACH user IN userlist %] [%~ user ~%] [% END %] To collapse all whitespace to a single space, use the 'C<=>' equals sign character. [% FOREACH user IN userlist %] [%= user =%] [% END %] Here the template is processed as if written: [% FOREACH user IN userlist %] [% user %] [% END %] If you have C<PRE_CHOMP> or C<POST_CHOMP> set as configuration options then you can use the 'C<+>' plus sign to disable any chomping options (i.e. leave the whitespace intact) on a per-directive basis. [% FOREACH user IN userlist %] User: [% user +%] [% END %] With C<POST_CHOMP> set to C<CHOMP_ONE>, the above example would be parsed as if written: [% FOREACH user IN userlist %]User: [% user %] [% END %] For reference, the C<PRE_CHOMP> and C<POST_CHOMP> configuration options may be set to any of the following: Constant Value Tag Modifier ---------------------------------- CHOMP_NONE 0 + CHOMP_ONE 1 - CHOMP_COLLAPSE 2 = CHOMP_GREEDY 3 ~ =head2 TRIM The C<TRIM> option can be set to have any leading and trailing whitespace automatically removed from the output of all template files and C<BLOCK>s. By example, the following C<BLOCK> definition [% BLOCK foo %] Line 1 of foo [% END %] will be processed is as "C<\nLine 1 of foo\n>". When C<INCLUDE>d, the surrounding newlines will also be introduced. before [% INCLUDE foo %] after Generated output: before Line 1 of foo after With the C<TRIM> option set to any true value, the leading and trailing newlines (which count as whitespace) will be removed from the output of the C<BLOCK>. before Line 1 of foo after The C<TRIM> option is disabled (C<0>) by default. =head2 INTERPOLATE The C<INTERPOLATE> flag, when set to any true value will cause variable references in plain text (i.e. not surrounded by C<START_TAG> and C<END_TAG>) to be recognised and interpolated accordingly. my $template = Template->new({ INTERPOLATE => 1, }); Variables should be prefixed by a 'C<$>' dollar sign to identify them. Curly braces 'C<{>' and 'C<}>' can be used in the familiar Perl/shell style to explicitly scope the variable name where required. # INTERPOLATE => 0 <a href="http://[% server %]/[% help %]"> <img src="[% images %]/help.gif"></a> [% myorg.name %] # INTERPOLATE => 1 <a href="http://$server/$help"> <img src="$images/help.gif"></a> $myorg.name # explicit scoping with { } <img src="$images/${icon.next}.gif"> Note that a limitation in Perl's regex engine restricts the maximum length of an interpolated template to around 32 kilobytes or possibly less. Files that exceed this limit in size will typically cause Perl to dump core with a segmentation fault. If you routinely process templates of this size then you should disable C<INTERPOLATE> or split the templates in several smaller files or blocks which can then be joined backed together via C<PROCESS> or C<INCLUDE>. =head2 ANYCASE By default, directive keywords should be expressed in UPPER CASE. The C<ANYCASE> option can be set to allow directive keywords to be specified in any case. # ANYCASE => 0 (default) [% INCLUDE foobar %] # OK [% include foobar %] # ERROR [% include = 10 %] # OK, 'include' is a variable # ANYCASE => 1 [% INCLUDE foobar %] # OK [% include foobar %] # OK [% include = 10 %] # ERROR, 'include' is reserved word One side-effect of enabling C<ANYCASE> is that you cannot use a variable of the same name as a reserved word, regardless of case. The reserved words are currently: GET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER IF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META TRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP CLEAR TO STEP AND OR NOT MOD DIV END The only lower case reserved words that cannot be used for variables, regardless of the C<ANYCASE> option, are the operators: and or not mod div =head1 Template Files and Blocks =head2 INCLUDE_PATH The C<INCLUDE_PATH> is used to specify one or more directories in which template files are located. When a template is requested that isn't defined locally as a C<BLOCK>, each of the C<INCLUDE_PATH> directories is searched in turn to locate the template file. Multiple directories can be specified as a reference to a list or as a single string where each directory is delimited by the 'C<:>' colon character. my $template = Template->new({ INCLUDE_PATH => '/usr/local/templates', }); my $template = Template->new({ INCLUDE_PATH => '/usr/local/templates:/tmp/my/templates', }); my $template = Template->new({ INCLUDE_PATH => [ '/usr/local/templates', '/tmp/my/templates' ], }); On Win32 systems, a little extra magic is invoked, ignoring delimiters that have 'C<:>' colon followed by a 'C</>' slash or 'C<\>' blackslash. This avoids confusion when using directory names like 'C<C:\Blah Blah>'. When specified as a list, the C<INCLUDE_PATH> path can contain elements which dynamically generate a list of C<INCLUDE_PATH> directories. These generator elements can be specified as a reference to a subroutine or an object which implements a C<paths()> method. my $template = Template->new({ INCLUDE_PATH => [ '/usr/local/templates', \&incpath_generator, My::IncPath::Generator->new( ... ) ], }); Each time a template is requested and the C<INCLUDE_PATH> examined, the subroutine or object method will be called. A reference to a list of directories should be returned. Generator subroutines should report errors using C<die()>. Generator objects should return undef and make an error available via its C<error()> method. For example: sub incpath_generator { # ...some code... if ($all_is_well) { return \@list_of_directories; } else { die "cannot generate INCLUDE_PATH...\n"; } } or: package My::IncPath::Generator; # Template::Base (or Class::Base) provides error() method use Template::Base; use base qw( Template::Base ); sub paths { my $self = shift; # ...some code... if ($all_is_well) { return \@list_of_directories; } else { return $self->error("cannot generate INCLUDE_PATH...\n"); } } 1; =head2 DELIMITER Used to provide an alternative delimiter character sequence for separating paths specified in the C<INCLUDE_PATH>. The default value for C<DELIMITER> is the 'C<:>' colon character. my $template = Template->new({ DELIMITER => '; ', INCLUDE_PATH => 'C:/HERE/NOW; D:/THERE/THEN', }); On Win32 systems, the default delimiter is a little more intelligent, splitting paths only on 'C<:>' colon characters that aren't followed by a 'C</>' slash character. This means that the following should work as planned, splitting the C<INCLUDE_PATH> into 2 separate directories, C<C:/foo> and C<C:/bar>. # on Win32 only my $template = Template->new({ INCLUDE_PATH => 'C:/Foo:C:/Bar' }); However, if you're using Win32 then it's recommended that you explicitly set the C<DELIMITER> character to something else (e.g. 'C<;>' semicolon) rather than rely on this subtle magic. =head2 ABSOLUTE The C<ABSOLUTE> flag is used to indicate if templates specified with absolute filenames (e.g. 'C</foo/bar>') should be processed. It is disabled by default and any attempt to load a template by such a name will cause a 'C<file>' exception to be raised. my $template = Template->new({ ABSOLUTE => 1, }); # this is why it's disabled by default [% INSERT /etc/passwd %] On Win32 systems, the regular expression for matching absolute pathnames is tweaked slightly to also detect filenames that start with a driver letter and colon, such as: C:/Foo/Bar =head2 RELATIVE The C<RELATIVE> flag is used to indicate if templates specified with filenames relative to the current directory (e.g. 'C<./foo/bar>' or 'C<../../some/where/else>') should be loaded. It is also disabled by default, and will raise a 'C<file>' error if such template names are encountered. my $template = Template->new({ RELATIVE => 1, }); [% INCLUDE ../logs/error.log %] =head2 DEFAULT The C<DEFAULT> option can be used to specify a default template which should be used whenever a specified template can't be found in the C<INCLUDE_PATH>. my $template = Template->new({ DEFAULT => 'notfound.html', }); If a non-existent template is requested through the Template L<process()|Template#process()> method, or by an C<INCLUDE>, C<PROCESS> or C<WRAPPER> directive, then the C<DEFAULT> template will instead be processed, if defined. Note that the C<DEFAULT> template is not used when templates are specified with absolute or relative filenames, or as a reference to a input file handle or text string. =head2 BLOCKS The C<BLOCKS> option can be used to pre-define a default set of template blocks. These should be specified as a reference to a hash array mapping template names to template text, subroutines or L<Template::Document> objects. my $template = Template->new({ BLOCKS => { header => 'The Header. [% title %]', footer => sub { return $some_output_text }, another => Template::Document->new({ ... }), }, }); =head2 VIEWS The VIEWS option can be used to define one or more L<Template::View> objects. They can be specified as a reference to a hash array or list reference. my $template = Template->new({ VIEWS => { my_view => { prefix => 'my_templates/' }, }, }); Be aware of the fact that Perl's hash array are unordered, so if you want to specify multiple views of which one or more are based on other views, then you should use a list reference to preserve the order of definition. my $template = Template->new({ VIEWS => [ bottom => { prefix => 'bottom/' }, middle => { prefix => 'middle/', base => 'bottom' }, top => { prefix => 'top/', base => 'middle' }, ], }); =head2 AUTO_RESET The C<AUTO_RESET> option is set by default and causes the local C<BLOCKS> cache for the L<Template::Context> object to be reset on each call to the Template L<process()|Template#process()> method. This ensures that any C<BLOCK>s defined within a template will only persist until that template is finished processing. This prevents C<BLOCK>s defined in one processing request from interfering with other independent requests subsequently processed by the same context object. The C<BLOCKS> item may be used to specify a default set of block definitions for the L<Template::Context> object. Subsequent C<BLOCK> definitions in templates will over-ride these but they will be reinstated on each reset if C<AUTO_RESET> is enabled (default), or if the L<Template::Context> L<reset()|Template::Context#reset()> method is called. =head2 RECURSION The template processor will raise a file exception if it detects direct or indirect recursion into a template. Setting this option to any true value will allow templates to include each other recursively. =head1 Template Variables =head2 VARIABLES The C<VARIABLES> option (or C<PRE_DEFINE> - they're equivalent) can be used to specify a hash array of template variables that should be used to pre-initialise the stash when it is created. These items are ignored if the C<STASH> item is defined. my $template = Template->new({ VARIABLES => { title => 'A Demo Page', author => 'Joe Random Hacker', version => 3.14, }, }; or my $template = Template->new({ PRE_DEFINE => { title => 'A Demo Page', author => 'Joe Random Hacker', version => 3.14, }, }; =head2 CONSTANTS The C<CONSTANTS> option can be used to specify a hash array of template variables that are compile-time constants. These variables are resolved once when the template is compiled, and thus don't require further resolution at runtime. This results in significantly faster processing of the compiled templates and can be used for variables that don't change from one request to the next. my $template = Template->new({ CONSTANTS => { title => 'A Demo Page', author => 'Joe Random Hacker', version => 3.14, }, }; =head2 CONSTANT_NAMESPACE Constant variables are accessed via the C<constants> namespace by default. [% constants.title %] The C<CONSTANTS_NAMESPACE> option can be set to specify an alternate namespace. my $template = Template->new({ CONSTANTS => { title => 'A Demo Page', # ...etc... }, CONSTANTS_NAMESPACE => 'const', }; In this case the constants would then be accessed as: [% const.title %] =head2 NAMESPACE The constant folding mechanism described above is an example of a namespace handler. Namespace handlers can be defined to provide alternate parsing mechanisms for variables in different namespaces. Under the hood, the L<Template> module converts a constructor configuration such as: my $template = Template->new({ CONSTANTS => { title => 'A Demo Page', # ...etc... }, CONSTANTS_NAMESPACE => 'const', }; into one like: my $template = Template->new({ NAMESPACE => { const => Template:::Namespace::Constants->new({ title => 'A Demo Page', # ...etc... }), }, }; You can use this mechanism to define multiple constant namespaces, or to install custom handlers of your own. my $template = Template->new({ NAMESPACE => { site => Template:::Namespace::Constants->new({ title => "Wardley's Widgets", version => 2.718, }), author => Template:::Namespace::Constants->new({ name => 'Andy Wardley', email => 'abw@andywardley.com', }), voodoo => My::Namespace::Handler->new( ... ), }, }; Now you have two constant namespaces, for example: [% site.title %] [% author.name %] as well as your own custom namespace handler installed for the 'voodoo' namespace. [% voodoo.magic %] See L<Template::Namespace::Constants> for an example of what a namespace handler looks like on the inside. =head1 Template Processing Options The following options are used to specify any additional templates that should be processed before, after, around or instead of the template passed as the first argument to the L<Template> L<process()|Template#process()> method. These options can be perform various useful tasks such as adding standard headers or footers to all pages, wrapping page output in other templates, pre-defining variables or performing initialisation or cleanup tasks, automatically generating page summary information, navigation elements, and so on. The task of processing the template is delegated internally to the L<Template::Service> module which, unsurprisingly, also has a L<process()|Template::Service#process()> method. Any templates defined by the C<PRE_PROCESS> option are processed first and any output generated is added to the output buffer. Then the main template is processed, or if one or more C<PROCESS> templates are defined then they are instead processed in turn. In this case, one of the C<PROCESS> templates is responsible for processing the main template, by a directive such as: [% PROCESS $template %] The output of processing the main template or the C<PROCESS> template(s) is then wrapped in any C<WRAPPER> templates, if defined. C<WRAPPER> templates don't need to worry about explicitly processing the template because it will have been done for them already. Instead C<WRAPPER> templates access the content they are wrapping via the C<content> variable. wrapper before [% content %] wrapper after This output generated from processing the main template, and/or any C<PROCESS> or C<WRAPPER> templates is added to the output buffer. Finally, any C<POST_PROCESS> templates are processed and their output is also added to the output buffer which is then returned. If the main template throws an exception during processing then any relevant template(s) defined via the C<ERROR> option will be processed instead. If defined and successfully processed, the output from the error template will be added to the output buffer in place of the template that generated the error and processing will continue, applying any C<WRAPPER> and C<POST_PROCESS> templates. If no relevant C<ERROR> option is defined, or if the error occurs in one of the C<PRE_PROCESS>, C<WRAPPER> or C<POST_PROCESS> templates, then the process will terminate immediately and the error will be returned. =head2 PRE_PROCESS, POST_PROCESS These values may be set to contain the name(s) of template files (relative to C<INCLUDE_PATH>) which should be processed immediately before and/or after each template. These do not get added to templates processed into a document via directives such as C<INCLUDE>, C<PROCESS>, C<WRAPPER> etc. my $template = Template->new({ PRE_PROCESS => 'header', POST_PROCESS => 'footer', }; Multiple templates may be specified as a reference to a list. Each is processed in the order defined. my $template = Template->new({ PRE_PROCESS => [ 'config', 'header' ], POST_PROCESS => 'footer', }; Alternately, multiple template may be specified as a single string, delimited by 'C<:>'. This delimiter string can be changed via the C<DELIMITER> option. my $template = Template->new({ PRE_PROCESS => 'config:header', POST_PROCESS => 'footer', }; The C<PRE_PROCESS> and C<POST_PROCESS> templates are evaluated in the same variable context as the main document and may define or update variables for subsequent use. config: [% # set some site-wide variables bgcolor = '#ffffff' version = 2.718 %] header: [% DEFAULT title = 'My Funky Web Site' %] <html> <head> <title>[% title %]</title> </head> <body bgcolor="[% bgcolor %]"> footer: <hr> Version [% version %] </body> </html> The L<Template::Document> object representing the main template being processed is available within C<PRE_PROCESS> and C<POST_PROCESS> templates as the C<template> variable. Metadata items defined via the C<META> directive may be accessed accordingly. $template->process('mydoc.html', $vars); mydoc.html: [% META title = 'My Document Title' %] blah blah blah ... header: <html> <head> <title>[% template.title %]</title> </head> <body bgcolor="[% bgcolor %]"> =head2 PROCESS The C<PROCESS> option may be set to contain the name(s) of template files (relative to C<INCLUDE_PATH>) which should be processed instead of the main template passed to the L<Template> L<process()|Template#process()> method. This can be used to apply consistent wrappers around all templates, similar to the use of C<PRE_PROCESS> and C<POST_PROCESS> templates. my $template = Template->new({ PROCESS => 'content', }; # processes 'content' instead of 'foo.html' $template->process('foo.html'); A reference to the original template is available in the C<template> variable. Metadata items can be inspected and the template can be processed by specifying it as a variable reference (i.e. prefixed by C<$>) to an C<INCLUDE>, C<PROCESS> or C<WRAPPER> directive. content: <html> <head> <title>[% template.title %]</title> </head> <body> <!-- begin content --> [% PROCESS $template %] <!-- end content --> <hr> © Copyright [% template.copyright %] </body> </html> foo.html: [% META title = 'The Foo Page' author = 'Fred Foo' copyright = '2000 Fred Foo' %] <h1>[% template.title %]</h1> Welcome to the Foo Page, blah blah blah output: <html> <head> <title>The Foo Page</title> </head> <body> <!-- begin content --> <h1>The Foo Page</h1> Welcome to the Foo Page, blah blah blah <!-- end content --> <hr> © Copyright 2000 Fred Foo </body> </html> =head2 WRAPPER The C<WRAPPER> option can be used to specify one or more templates which should be used to wrap around the output of the main page template. The main template is processed first (or any C<PROCESS> template(s)) and the output generated is then passed as the C<content> variable to the C<WRAPPER> template(s) as they are processed. my $template = Template->new({ WRAPPER => 'wrapper', }; # process 'foo' then wrap in 'wrapper' $template->process('foo', { message => 'Hello World!' }); wrapper: <wrapper> [% content %] </wrapper> foo: This is the foo file! Message: [% message %] The output generated from this example is: <wrapper> This is the foo file! Message: Hello World! </wrapper> You can specify more than one C<WRAPPER> template by setting the value to be a reference to a list of templates. The C<WRAPPER> templates will be processed in reverse order with the output of each being passed to the next (or previous, depending on how you look at it) as the 'content' variable. It sounds complicated, but the end result is that it just "Does The Right Thing" to make wrapper templates nest in the order you specify. my $template = Template->new({ WRAPPER => [ 'outer', 'inner' ], }; # process 'foo' then wrap in 'inner', then in 'outer' $template->process('foo', { message => 'Hello World!' }); outer: <outer> [% content %] </outer> inner: <inner> [% content %] </inner> The output generated is then: <outer> <inner> This is the foo file! Message: Hello World! </inner> </outer> One side-effect of the "inside-out" processing of the C<WRAPPER> configuration item (and also the C<WRAPPER> directive) is that any variables set in the template being wrapped will be visible to the template doing the wrapping, but not the other way around. You can use this to good effect in allowing page templates to set pre-defined values which are then used in the wrapper templates. For example, our main page template 'foo' might look like this: foo: [% page = { title = 'Foo Page' subtitle = 'Everything There is to Know About Foo' author = 'Frank Oliver Octagon' } %] <p> Welcome to the page that tells you everything about foo blah blah blah... </p> The C<foo> template is processed before the wrapper template meaning that the C<page> data structure will be defined for use in the wrapper template. wrapper: <html> <head> <title>[% page.title %]</title> </head> <body> <h1>[% page.title %]</h1> <h2>[% page.subtitle %]</h1> <h3>by [% page.author %]</h3> [% content %] </body> </html> It achieves the same effect as defining C<META> items which are then accessed via the C<template> variable (which you are still free to use within C<WRAPPER> templates), but gives you more flexibility in the type and complexity of data that you can define. =head2 ERROR The C<ERROR> (or C<ERRORS> if you prefer) configuration item can be used to name a single template or specify a hash array mapping exception types to templates which should be used for error handling. If an uncaught exception is raised from within a template then the appropriate error template will instead be processed. If specified as a single value then that template will be processed for all uncaught exceptions. my $template = Template->new({ ERROR => 'error.html' }); If the C<ERROR> item is a hash reference the keys are assumed to be exception types and the relevant template for a given exception will be selected. A C<default> template may be provided for the general case. Note that C<ERROR> can be pluralised to C<ERRORS> if you find it more appropriate in this case. my $template = Template->new({ ERRORS => { user => 'user/index.html', dbi => 'error/database', default => 'error/default', }, }); In this example, any C<user> exceptions thrown will cause the F<user/index.html> template to be processed, C<dbi> errors are handled by F<error/database> and all others by the F<error/default> template. Any C<PRE_PROCESS> and/or C<POST_PROCESS> templates will also be applied to these error templates. Note that exception types are hierarchical and a C<foo> handler will catch all C<foo.*> errors (e.g. C<foo.bar>, C<foo.bar.baz>) if a more specific handler isn't defined. Be sure to quote any exception types that contain periods to prevent Perl concatenating them into a single string (i.e. C<user.passwd> is parsed as C<'user'.'passwd'>). my $template = Template->new({ ERROR => { 'user.login' => 'user/login.html', 'user.passwd' => 'user/badpasswd.html', 'user' => 'user/index.html', 'default' => 'error/default', }, }); In this example, any template processed by the C<$template> object, or other templates or code called from within, can raise a C<user.login> exception and have the service redirect to the F<user/login.html> template. Similarly, a C<user.passwd> exception has a specific handling template, F<user/badpasswd.html>, while all other C<user> or C<user.*> exceptions cause a redirection to the F<user/index.html> page. All other exception types are handled by F<error/default>. Exceptions can be raised in a template using the C<THROW> directive, [% THROW user.login 'no user id: please login' %] or by calling the L<throw()|Template::Context#throw()> method on the current L<Template::Context> object, $context->throw('user.passwd', 'Incorrect Password'); $context->throw('Incorrect Password'); # type 'undef' or from Perl code by calling C<die()> with a L<Template::Exception> object, die (Template::Exception->new('user.denied', 'Invalid User ID')); or by simply calling L<die()> with an error string. This is automagically caught and converted to an exception of 'C<undef>' type which can then be handled in the usual way. die "I'm sorry Dave, I can't do that"; Note that the 'C<undef>' we're talking about here is a literal string rather than Perl's C<undef> used to represent undefined values. =head1 Template Runtime Options =head2 EVAL_PERL This flag is used to indicate if C<PERL> and/or C<RAWPERL> blocks should be evaluated. It is disabled by default and any C<PERL> or C<RAWPERL> blocks encountered will raise exceptions of type 'C<perl>' with the message 'C<EVAL_PERL not set>'. Note however that any C<RAWPERL> blocks should always contain valid Perl code, regardless of the C<EVAL_PERL> flag. The parser will fail to compile templates that contain invalid Perl code in C<RAWPERL> blocks and will throw a 'C<file>' exception. When using compiled templates (see L<Caching and Compiling Options>), the C<EVAL_PERL> has an affect when the template is compiled, and again when the templates is subsequently processed, possibly in a different context to the one that compiled it. If the C<EVAL_PERL> is set when a template is compiled, then all C<PERL> and C<RAWPERL> blocks will be included in the compiled template. If the C<EVAL_PERL> option isn't set, then Perl code will be generated which B<always> throws a 'C<perl>' exception with the message 'C<EVAL_PERL not set>' B<whenever> the compiled template code is run. Thus, you must have C<EVAL_PERL> set if you want your compiled templates to include C<PERL> and C<RAWPERL> blocks. At some point in the future, using a different invocation of the Template Toolkit, you may come to process such a pre-compiled template. Assuming the C<EVAL_PERL> option was set at the time the template was compiled, then the output of any C<RAWPERL> blocks will be included in the compiled template and will get executed when the template is processed. This will happen regardless of the runtime C<EVAL_PERL> status. Regular C<PERL> blocks are a little more cautious, however. If the C<EVAL_PERL> flag isn't set for the I<current> context, that is, the one which is trying to process it, then it will throw the familiar 'C<perl>' exception with the message, 'C<EVAL_PERL not set>'. Thus you can compile templates to include C<PERL> blocks, but optionally disable them when you process them later. Note however that it is possible for a C<PERL> block to contain a Perl "C<BEGIN { # some code }>" block which will always get run regardless of the runtime C<EVAL_PERL> status. Thus, if you set C<EVAL_PERL> when compiling templates, it is assumed that you trust the templates to Do The Right Thing. Otherwise you must accept the fact that there's no bulletproof way to prevent any included code from trampling around in the living room of the runtime environment, making a real nuisance of itself if it really wants to. If you don't like the idea of such uninvited guests causing a bother, then you can accept the default and keep C<EVAL_PERL> disabled. =head2 OUTPUT Default output location or handler. This may be specified as one of: a file name (relative to C<OUTPUT_PATH>, if defined, or the current working directory if not specified absolutely); a file handle (e.g. C<GLOB> or L<IO::Handle>) opened for writing; a reference to a text string to which the output is appended (the string isn't cleared); a reference to a subroutine which is called, passing the output text as an argument; as a reference to an array, onto which the content will be C<push()>ed; or as a reference to any object that supports the C<print()> method. This latter option includes the C<Apache::Request> object which is passed as the argument to Apache/mod_perl handlers. example 1 (file name): my $template = Template->new({ OUTPUT => "/tmp/foo", }); example 2 (text string): my $output = ''; my $template = Template->new({ OUTPUT => \$output, }); example 3 (file handle): open (TOUT, ">", $file) || die "$file: $!\n"; my $template = Template->new({ OUTPUT => \*TOUT, }); example 4 (subroutine): sub output { my $out = shift; print "OUTPUT: $out" } my $template = Template->new({ OUTPUT => \&output, }); example 5 (array reference): my $template = Template->new({ OUTPUT => \@output, }) example 6 (Apache/mod_perl handler): sub handler { my $r = shift; my $t = Template->new({ OUTPUT => $r, }); ... } The default C<OUTPUT> location be overridden by passing a third parameter to the L<Template> L<process()|Template#process()> method. This can be specified as any of the above argument types. $t->process($file, $vars, "/tmp/foo"); $t->process($file, $vars, \$output); $t->process($file, $vars, \*MYGLOB); $t->process($file, $vars, \@output); $t->process($file, $vars, $r); # Apache::Request ... =head2 OUTPUT_PATH The C<OUTPUT_PATH> allows a directory to be specified into which output files should be written. An output file can be specified by the C<OUTPUT> option, or passed by name as the third parameter to the L<Template> L<process()|Template#process()> method. my $template = Template->new({ INCLUDE_PATH => "/tmp/src", OUTPUT_PATH => "/tmp/dest", }); my $vars = { ... }; foreach my $file ('foo.html', 'bar.html') { $template->process($file, $vars, $file) || die $template->error(); } This example will read the input files F</tmp/src/foo.html> and F</tmp/src/bar.html> and write the processed output to F</tmp/dest/foo.html> and F</tmp/dest/bar.html>, respectively. =head2 STRICT By default the Template Toolkit will silently ignore the use of undefined variables (a bad design decision that I regret). When the C<STRICT> option is set, the use of any undefined variables or values will cause an exception to be throw. The exception will have a C<type> of C<var.undefined> and a message of the form "undefined variable: xxx". my $template = Template->new( STRICT => 1 ); =head2 DEBUG The C<DEBUG> option can be used to enable debugging within the various different modules that comprise the Template Toolkit. The L<Template::Constants> module defines a set of C<DEBUG_XXXX> constants which can be combined using the logical OR operator, 'C<|>'. use Template::Constants qw( :debug ); my $template = Template->new({ DEBUG => DEBUG_PARSER | DEBUG_PROVIDER, }); For convenience, you can also provide a string containing a list of lower case debug options, separated by any non-word characters. my $template = Template->new({ DEBUG => 'parser, provider', }); The following C<DEBUG_XXXX> flags can be used: =over 4 =item DEBUG_SERVICE Enables general debugging messages for the L<Template::Service> module. =item DEBUG_CONTEXT Enables general debugging messages for the L<Template::Context> module. =item DEBUG_PROVIDER Enables general debugging messages for the L<Template::Provider> module. =item DEBUG_PLUGINS Enables general debugging messages for the L<Template::Plugins> module. =item DEBUG_FILTERS Enables general debugging messages for the L<Template::Filters> module. =item DEBUG_PARSER This flag causes the L<Template::Parser> to generate debugging messages that show the Perl code generated by parsing and compiling each template. =item DEBUG_UNDEF This option causes the Template Toolkit to throw an 'C<undef>' error whenever it encounters an undefined variable value. =item DEBUG_DIRS This option causes the Template Toolkit to generate comments indicating the source file, line and original text of each directive in the template. These comments are embedded in the template output using the format defined in the C<DEBUG_FORMAT> configuration item, or a simple default format if unspecified. For example, the following template fragment: Hello World would generate this output: ## input text line 1 : ## Hello ## input text line 2 : World ## World =item DEBUG_ALL Enables all debugging messages. =item DEBUG_CALLER This option causes all debug messages that aren't newline terminated to have the file name and line number of the caller appended to them. =back =head2 DEBUG_FORMAT The C<DEBUG_FORMAT> option can be used to specify a format string for the debugging messages generated via the C<DEBUG_DIRS> option described above. Any occurrences of C<$file>, C<$line> or C<$text> will be replaced with the current file name, line or directive text, respectively. Notice how the format is single quoted to prevent Perl from interpolating those tokens as variables. my $template = Template->new({ DEBUG => 'dirs', DEBUG_FORMAT => '<!-- $file line $line : [% $text %] -->', }); The following template fragment: [% foo = 'World' %] Hello [% foo %] would then generate this output: <!-- input text line 2 : [% foo = 'World' %] --> Hello <!-- input text line 3 : [% foo %] -->World The DEBUG directive can also be used to set a debug format within a template. [% DEBUG format '<!-- $file line $line : [% $text %] -->' %] =head1 Caching and Compiling Options =head2 CACHE_SIZE The L<Template::Provider> module caches compiled templates to avoid the need to re-parse template files or blocks each time they are used. The C<CACHE_SIZE> option is used to limit the number of compiled templates that the module should cache. By default, the C<CACHE_SIZE> is undefined and all compiled templates are cached. When set to any positive value, the cache will be limited to storing no more than that number of compiled templates. When a new template is loaded and compiled and the cache is full (i.e. the number of entries == C<CACHE_SIZE>), the least recently used compiled template is discarded to make room for the new one. The C<CACHE_SIZE> can be set to C<0> to disable caching altogether. my $template = Template->new({ CACHE_SIZE => 64, # only cache 64 compiled templates }); my $template = Template->new({ CACHE_SIZE => 0, # don't cache any compiled templates }); As well as caching templates as they are found, the L<Template::Provider> also implements negative caching to keep track of templates that are I<not> found. This allows the provider to quickly decline a request for a template that it has previously failed to locate, saving the effort of going to look for it again. This is useful when an C<INCLUDE_PATH> includes multiple providers, ensuring that the request is passed down through the providers as quickly as possible. =head2 STAT_TTL This value can be set to control how long the L<Template::Provider> will keep a template cached in memory before checking to see if the source template has changed. my $provider = Template::Provider->new({ STAT_TTL => 60, # one minute }); The default value is 1 (second). You'll probably want to set this to a higher value if you're running the Template Toolkit inside a persistent web server application (e.g. mod_perl). For example, set it to 60 and the provider will only look for changes to templates once a minute at most. However, during development (or any time you're making frequent changes to templates) you'll probably want to keep it set to a low value so that you don't have to wait for the provider to notice that your templates have changed. =head2 COMPILE_EXT From version 2 onwards, the Template Toolkit has the ability to compile templates to Perl code and save them to disk for subsequent use (i.e. cache persistence). The C<COMPILE_EXT> option may be provided to specify a filename extension for compiled template files. It is undefined by default and no attempt will be made to read or write any compiled template files. my $template = Template->new({ COMPILE_EXT => '.ttc', }); If C<COMPILE_EXT> is defined (and C<COMPILE_DIR> isn't, see below) then compiled template files with the C<COMPILE_EXT> extension will be written to the same directory from which the source template files were loaded. Compiling and subsequent reuse of templates happens automatically whenever the C<COMPILE_EXT> or C<COMPILE_DIR> options are set. The Template Toolkit will automatically reload and reuse compiled files when it finds them on disk. If the corresponding source file has been modified since the compiled version as written, then it will load and re-compile the source and write a new compiled version to disk. This form of cache persistence offers significant benefits in terms of time and resources required to reload templates. Compiled templates can be reloaded by a simple call to Perl's C<require()>, leaving Perl to handle all the parsing and compilation. This is a Good Thing. =head2 COMPILE_DIR The C<COMPILE_DIR> option is used to specify an alternate directory root under which compiled template files should be saved. my $template = Template->new({ COMPILE_DIR => '/tmp/ttc', }); The C<COMPILE_EXT> option may also be specified to have a consistent file extension added to these files. my $template1 = Template->new({ COMPILE_DIR => '/tmp/ttc', COMPILE_EXT => '.ttc1', }); my $template2 = Template->new({ COMPILE_DIR => '/tmp/ttc', COMPILE_EXT => '.ttc2', }); When C<COMPILE_EXT> is undefined, the compiled template files have the same name as the original template files, but reside in a different directory tree. Each directory in the C<INCLUDE_PATH> is replicated in full beneath the C<COMPILE_DIR> directory. This example: my $template = Template->new({ COMPILE_DIR => '/tmp/ttc', INCLUDE_PATH => '/home/abw/templates:/usr/share/templates', }); would create the following directory structure: /tmp/ttc/home/abw/templates/ /tmp/ttc/usr/share/templates/ Files loaded from different C<INCLUDE_PATH> directories will have their compiled forms save in the relevant C<COMPILE_DIR> directory. On Win32 platforms a filename may by prefixed by a drive letter and colon. e.g. C:/My Templates/header The colon will be silently stripped from the filename when it is added to the C<COMPILE_DIR> value(s) to prevent illegal filename being generated. Any colon in C<COMPILE_DIR> elements will be left intact. For example: # Win32 only my $template = Template->new({ DELIMITER => ';', COMPILE_DIR => 'C:/TT2/Cache', INCLUDE_PATH => 'C:/TT2/Templates;D:/My Templates', }); This would create the following cache directories: C:/TT2/Cache/C/TT2/Templates C:/TT2/Cache/D/My Templates =head1 Plugins and Filters =head2 PLUGINS The C<PLUGINS> options can be used to provide a reference to a hash array that maps plugin names to Perl module names. A number of standard plugins are defined (e.g. C<table>, C<format>, C<cgi>, etc.) which map to their corresponding C<Template::Plugin::*> counterparts. These can be redefined by values in the C<PLUGINS> hash. my $template = Template->new({ PLUGINS => { cgi => 'MyOrg::Template::Plugin::CGI', foo => 'MyOrg::Template::Plugin::Foo', bar => 'MyOrg::Template::Plugin::Bar', }, }); The recommended convention is to specify these plugin names in lower case. The Template Toolkit first looks for an exact case-sensitive match and then tries the lower case conversion of the name specified. [% USE Foo %] # look for 'Foo' then 'foo' If you define all your C<PLUGINS> with lower case names then they will be located regardless of how the user specifies the name in the USE directive. If, on the other hand, you define your C<PLUGINS> with upper or mixed case names then the name specified in the C<USE> directive must match the case exactly. The C<USE> directive is used to create plugin objects and does so by calling the L<plugin()|Template::Context#plugin()> method on the current L<Template::Context> object. If the plugin name is defined in the C<PLUGINS> hash then the corresponding Perl module is loaded via C<require()>. The context then calls the L<load()|Template::Plugin#load()> class method which should return the class name (default and general case) or a prototype object against which the L<new()|Template::Plugin#new()> method can be called to instantiate individual plugin objects. If the plugin name is not defined in the C<PLUGINS> hash then the C<PLUGIN_BASE> and/or C<LOAD_PERL> options come into effect. =head2 PLUGIN_BASE If a plugin is not defined in the C<PLUGINS> hash then the C<PLUGIN_BASE> is used to attempt to construct a correct Perl module name which can be successfully loaded. The C<PLUGIN_BASE> can be specified as a reference to an array of module namespaces, or as a single value which is automatically converted to a list. The default C<PLUGIN_BASE> value (C<Template::Plugin>) is then added to the end of this list. example 1: my $template = Template->new({ PLUGIN_BASE => 'MyOrg::Template::Plugin', }); [% USE Foo %] # => MyOrg::Template::Plugin::Foo or Template::Plugin::Foo example 2: my $template = Template->new({ PLUGIN_BASE => [ 'MyOrg::Template::Plugin', 'YourOrg::Template::Plugin' ], }); template: [% USE Foo %] # => MyOrg::Template::Plugin::Foo or YourOrg::Template::Plugin::Foo or Template::Plugin::Foo If you don't want the default C<Template::Plugin> namespace added to the end of the C<PLUGIN_BASE>, then set the C<$Template::Plugins::PLUGIN_BASE> variable to a false value before calling the L<new()|Template> L<Template#new()> constructor method. This is shown in the example below where the C<Foo> plugin is located as C<My::Plugin::Foo> or C<Your::Plugin::Foo> but not as C<Template::Plugin::Foo>. example 3: use Template::Plugins; $Template::Plugins::PLUGIN_BASE = ''; my $template = Template->new({ PLUGIN_BASE => [ 'My::Plugin', 'Your::Plugin' ], }); template: [% USE Foo %] # => My::Plugin::Foo or Your::Plugin::Foo =head2 LOAD_PERL If a plugin cannot be loaded using the C<PLUGINS> or C<PLUGIN_BASE> approaches then the provider can make a final attempt to load the module without prepending any prefix to the module path. This allows regular Perl modules (i.e. those that don't reside in the L<Template::Plugin> or some other such namespace) to be loaded and used as plugins. By default, the C<LOAD_PERL> option is set to C<0> and no attempt will be made to load any Perl modules that aren't named explicitly in the C<PLUGINS> hash or reside in a package as named by one of the C<PLUGIN_BASE> components. Plugins loaded using the C<PLUGINS> or C<PLUGIN_BASE> receive a reference to the current context object as the first argument to the L<new()|Template::Plugin#new()> constructor. Modules loaded using C<LOAD_PERL> are assumed to not conform to the plugin interface. They must provide a C<new()> class method for instantiating objects but it will not receive a reference to the context as the first argument. Plugin modules should provide a L<load()|Template::Plugin#load()> class method (or inherit the default one from the L<Template::Plugin> base class) which is called the first time the plugin is loaded. Regular Perl modules need not. In all other respects, regular Perl objects and Template Toolkit plugins are identical. If a particular Perl module does not conform to the common, but not unilateral, C<new()> constructor convention then a simple plugin wrapper can be written to interface to it. =head2 FILTERS The C<FILTERS> option can be used to specify custom filters which can then be used with the C<FILTER> directive like any other. These are added to the standard filters which are available by default. Filters specified via this option will mask any standard filters of the same name. The C<FILTERS> option should be specified as a reference to a hash array in which each key represents the name of a filter. The corresponding value should contain a reference to an array containing a subroutine reference and a flag which indicates if the filter is static (C<0>) or dynamic (C<1>). A filter may also be specified as a solitary subroutine reference and is assumed to be static. $template = Template->new({ FILTERS => { 'sfilt1' => \&static_filter, # static 'sfilt2' => [ \&static_filter, 0 ], # same as above 'dfilt1' => [ \&dyanamic_filter_factory, 1 ], }, }); Additional filters can be specified at any time by calling the L<define_filter()|Template::Context#define_filter()> method on the current L<Template::Context> object. The method accepts a filter name, a reference to a filter subroutine and an optional flag to indicate if the filter is dynamic. my $context = $template->context(); $context->define_filter('new_html', \&new_html); $context->define_filter('new_repeat', \&new_repeat, 1); Static filters are those where a single subroutine reference is used for all invocations of a particular filter. Filters that don't accept any configuration parameters (e.g. C<html>) can be implemented statically. The subroutine reference is simply returned when that particular filter is requested. The subroutine is called to filter the output of a template block which is passed as the only argument. The subroutine should return the modified text. sub static_filter { my $text = shift; # do something to modify $text... return $text; } The following template fragment: [% FILTER sfilt1 %] Blah blah blah. [% END %] is approximately equivalent to: &static_filter("\nBlah blah blah.\n"); Filters that can accept parameters (e.g. C<truncate>) should be implemented dynamically. In this case, the subroutine is taken to be a filter 'factory' that is called to create a unique filter subroutine each time one is requested. A reference to the current L<Template::Context> object is passed as the first parameter, followed by any additional parameters specified. The subroutine should return another subroutine reference (usually a closure) which implements the filter. sub dynamic_filter_factory { my ($context, @args) = @_; return sub { my $text = shift; # do something to modify $text... return $text; } } The following template fragment: [% FILTER dfilt1(123, 456) %] Blah blah blah [% END %] is approximately equivalent to: my $filter = &dynamic_filter_factory($context, 123, 456); &$filter("\nBlah blah blah.\n"); See the C<FILTER> directive for further examples. =head1 Customisation and Extension =head2 LOAD_TEMPLATES The C<LOAD_TEMPLATES> option can be used to provide a reference to a list of L<Template::Provider> objects or sub-classes thereof which will take responsibility for loading and compiling templates. my $template = Template->new({ LOAD_TEMPLATES => [ MyOrg::Template::Provider->new({ ... }), Template::Provider->new({ ... }), ], }); When a C<PROCESS>, C<INCLUDE> or C<WRAPPER> directive is encountered, the named template may refer to a locally defined C<BLOCK> or a file relative to the C<INCLUDE_PATH> (or an absolute or relative path if the appropriate C<ABSOLUTE> or C<RELATIVE> options are set). If a C<BLOCK> definition can't be found (see the L<Template::Context> L<template()|Template::Context#template()> method for a discussion of C<BLOCK> locality) then each of the C<LOAD_TEMPLATES> provider objects is queried in turn via the L<fetch()|Template::Provider#fetch()> method to see if it can supply the required template. Each provider can return a compiled template, an error, or decline to service the request in which case the responsibility is passed to the next provider. If none of the providers can service the request then a 'not found' error is returned. The same basic provider mechanism is also used for the C<INSERT> directive but it bypasses any C<BLOCK> definitions and doesn't attempt is to parse or process the contents of the template file. If C<LOAD_TEMPLATES> is undefined, a single default provider will be instantiated using the current configuration parameters. For example, the L<Template::Provider> C<INCLUDE_PATH> option can be specified in the L<Template> configuration and will be correctly passed to the provider's constructor method. my $template = Template->new({ INCLUDE_PATH => '/here:/there', }); =head2 LOAD_PLUGINS The C<LOAD_PLUGINS> options can be used to specify a list of provider objects (i.e. they implement the L<fetch()|Template::Plugins#fetch()> method) which are responsible for loading and instantiating template plugin objects. The L<Template::Context> L<plugin()|Template::Context#plugin()> method queries each provider in turn in a "Chain of Responsibility" as per the L<template()|Template::Context#template()> and L<filter()|Template::Context#filter()> methods. my $template = Template->new({ LOAD_PLUGINS => [ MyOrg::Template::Plugins->new({ ... }), Template::Plugins->new({ ... }), ], }); By default, a single L<Template::Plugins> object is created using the current configuration hash. Configuration items destined for the L<Template::Plugins> constructor may be added to the Template constructor. my $template = Template->new({ PLUGIN_BASE => 'MyOrg::Template::Plugins', LOAD_PERL => 1, }); =head2 LOAD_FILTERS The C<LOAD_FILTERS> option can be used to specify a list of provider objects (i.e. they implement the L<fetch()|Template::Filters#fetch()> method) which are responsible for returning and/or creating filter subroutines. The L<Template::Context> L<filter()|Template::Context#filter()> method queries each provider in turn in a "Chain of Responsibility" as per the L<template()|Template::Context#template()> and L<plugin()|Template::Context#plugin()> methods. my $template = Template->new({ LOAD_FILTERS => [ MyTemplate::Filters->new(), Template::Filters->new(), ], }); By default, a single L<Template::Filters> object is created for the C<LOAD_FILTERS> list. =head2 TOLERANT The C<TOLERANT> flag is used by the various Template Toolkit provider modules (L<Template::Provider>, L<Template::Plugins>, L<Template::Filters>) to control their behaviour when errors are encountered. By default, any errors are reported as such, with the request for the particular resource (C<template>, C<plugin>, C<filter>) being denied and an exception raised. When the C<TOLERANT> flag is set to any true values, errors will be silently ignored and the provider will instead return C<STATUS_DECLINED>. This allows a subsequent provider to take responsibility for providing the resource, rather than failing the request outright. If all providers decline to service the request, either through tolerated failure or a genuine disinclination to comply, then a 'C<E<lt>resourceE<gt> not found>' exception is raised. =head2 SERVICE A reference to a L<Template::Service> object, or sub-class thereof, to which the L<Template> module should delegate. If unspecified, a L<Template::Service> object is automatically created using the current configuration hash. my $template = Template->new({ SERVICE => MyOrg::Template::Service->new({ ... }), }); =head2 CONTEXT A reference to a L<Template::Context> object which is used to define a specific environment in which template are processed. A L<Template::Context> object is passed as the only parameter to the Perl subroutines that represent "compiled" template documents. Template subroutines make callbacks into the context object to access Template Toolkit functionality, for example, to C<INCLUDE> or C<PROCESS> another template (L<include()|Template::Context#include()> and L<process()|Template::Context#process()> methods, respectively), to C<USE> a plugin (L<plugin()|Template::Context#plugin()>) or instantiate a filter (L<filter()|Template::Context#filter()>) or to access the stash (L<stash()|Template::Context#stash()>) which manages variable definitions via the L<get()|Template::Stash#get()> and L<set()|Template::Stash#set()> methods. my $template = Template->new({ CONTEXT => MyOrg::Template::Context->new({ ... }), }); =head2 STASH A reference to a L<Template::Stash> object or sub-class which will take responsibility for managing template variables. my $stash = MyOrg::Template::Stash->new({ ... }); my $template = Template->new({ STASH => $stash, }); If unspecified, a default stash object is created using the C<VARIABLES> configuration item to initialise the stash variables. my $template = Template->new({ VARIABLES => { id => 'abw', name => 'Andy Wardley', }, }; =head2 PARSER The L<Template::Parser> module implements a parser object for compiling templates into Perl code which can then be executed. A default object of this class is created automatically and then used by the L<Template::Provider> whenever a template is loaded and requires compilation. The C<PARSER> option can be used to provide a reference to an alternate parser object. my $template = Template->new({ PARSER => MyOrg::Template::Parser->new({ ... }), }); =head2 GRAMMAR The C<GRAMMAR> configuration item can be used to specify an alternate grammar for the parser. This allows a modified or entirely new template language to be constructed and used by the Template Toolkit. Source templates are compiled to Perl code by the L<Template::Parser> using the L<Template::Grammar> (by default) to define the language structure and semantics. Compiled templates are thus inherently "compatible" with each other and there is nothing to prevent any number of different template languages being compiled and used within the same Template Toolkit processing environment (other than the usual time and memory constraints). The L<Template::Grammar> file is constructed from a YACC like grammar (using C<Parse::YAPP>) and a skeleton module template. These files are provided, along with a small script to rebuild the grammar, in the F<parser> sub-directory of the distribution. You don't have to know or worry about these unless you want to hack on the template language or define your own variant. There is a F<README> file in the same directory which provides some small guidance but it is assumed that you know what you're doing if you venture herein. If you grok LALR parsers, then you should find it comfortably familiar. By default, an instance of the default L<Template::Grammar> will be created and used automatically if a C<GRAMMAR> item isn't specified. use MyOrg::Template::Grammar; my $template = Template->new({ GRAMMAR = MyOrg::Template::Grammar->new(); }); =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: Credits.pod 0000444 00000012116 14711272050 0006643 0 ustar 00 #============================================================= -*-perl-*- # # Template::Manual::Credits # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2020 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =encoding utf8 =head1 NAME Template::Manual::Credits - Author and contributor credits =head1 HISTORY The Template Toolkit began its life as the C<Text::MetaText> module, originally released to CPAN around 1996. This itself was the public manifestation of an earlier template processing system I developed while working at Peritas (now Knowledge Pool - http://www.knowledgepool.com/) C<Text::MetaText> was the prototype - the one we always planned to throw away. It did the job well, showing us what worked and what didn't, what was good and what was bad, and gave us some ideas about what could be done better, given the chance to start again from scratch. Some time late in 1998 I threw away the prototype and started work on the Template Toolkit. By then I was working at Canon Research Centre Europe Ltd. (CRE), involved in a general research programme related to web publishing and dynamic content generation. The first alpha release was in June 1999, followed by numerous more alpha and beta releases culminating in 1.00 being released on 2nd December 1999. A month or so later, work had begun on version 2.00. The plan was to get the template language relatively stable in version 1.00 and not worry too much about performance or other internal matters. Then, version 2.00 would follow to improve performance, clean up the architecture and fix anything that, with the benefit of hindsight, we thought could be improved. As it happens, me starting work on version 2.00 coincided with Doug Steinwand sending me his parser variant which compiled templates to Perl code, giving a major performance boost. As well as the speedups, there are a whole host of significant new features in version 2.00, and a greatly improved internal architecture. Apart from a few minor "fixups" the template directives and language have remained the same as in version 1.00 Version 2.00 was available in beta release form in July 2000, just in time for the 4th Perl Conference where version 1.00 was awarded "Best New Perl Module". After another extended beta release period, version 2.00 was released on 1st December 2000. Version 3 has been in development ever since. =head1 AUTHOR Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> =head1 COPYRIGHT Copyright (C) 1996-2020 Andy Wardley. All Rights Reserved. The Template Toolkit is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 CONTRIBUTORS Many people have contributed ideas, inspiration, fixes and features to the Template Toolkit. Their efforts continue to be very much appreciated. Please let me know if you think anyone is missing from this list. If you submit a patch/pull request then please make sure you add your own name to this list and include it in the changes. Adam Kennedy, ahollandECS, Alexey A. Kiritchun, Amiri Barksdale, Andreas Koenig, Andy Wardley, Autrijus Tang, Axel Gerstmair, Barrie Slaymaker, Ben Tilly, Breno G. de Oliveira, Briac PilprE<eacute>, Brian Fraser, Brian Wightman, Bryce Harrington, Chris Dean, Chris Winters, Christian, chromatic, Colin Johnson, Colin Keith, Craig Barratt, Darren Chamberlain, Dave Cash, Dave Cross, Dave Hodgkinson, Dave Howorth, Dave Jacoby, David Steinbrunner, Denis F. Latypoff, Dennis Clark, Doug, Drew Taylor, Dylan, E. Choroba, eadjei, Eric Cholet, Francois Desarmenien, François Andriot, fREW Schmidt, gordon-fish, Guido Flohr, Hans von Lengerke, Harald Joerg, Horst Dumcke, Ivan Krylov, Ivan Kurmanov, Jacques Germishuys, Jason Lewis, Jay Hannah, Jens Rehsack, Jess Robinson, Jim Vaughan, John Lightsey, John Napiorkowski, Jon Jensen, Jonas Liljegren, Jonathon Padfield, José Joaquín Atria, Jose Luis Martinez, Josh Rosenbaum, Kenny Gatdula, Kent Fredric, Kevin M. Goess, Koenig, Leon Brocard, Leslie Michael Orchard, Lubomir, Lyle Brooks, Marc Remy, Mark Fowler, Martin, Matthew Somerville, Michael Fowler, Michael Stevens, Mike Schilli, Mikhail Klyuchnikov from Positive Technologies, nataraj, Neil Bowers, Nick Hibma, Nicolas R, Nik Clayton, Norbert Buchmüller, Paul Orrock, Paul Seamons, Paul Sharpe, Perrin Harkins, Philippe Bruhat (BooK), Piers Cawley, Portman, Rafael Kitover, Randal L. Schwartz, Ricardo Signes, Richard Tietjen, Robin Berjon, Rod Taylor, Schaffner, sdeseille, Sean McAfee, Sean Zellmer, Simon, Simon Dawson, Simon Matthews, Simon Napiorkowski, Slaven Rezic, Smylers, Stas Bekman, Stathy G. Touloumis, stefano-b, Steinwand, Steve Peters, Swen, Thierry-Michel Barral, Thuemmler, Timmy Chan, Todd Rinaldo, Tom Delmas, Tony Bowden, Tosh Cooey, Ville SkyttE<auml>, Vivek Khera, Wilcox, William Hardison, Yanick Champoux, Yuri Pimenov. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: Variables.pod 0000444 00000060676 14711272050 0007174 0 ustar 00 #============================================================= -*-perl-*- # # Template::Manual::Variables # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Manual::Variables - Template variables and code bindings =head1 Template Variables A reference to a hash array may be passed as the second argument to the L<process()|Template#process()> method, containing definitions of template variables. The C<VARIABLES> (a.k.a. C<PRE_DEFINE>) option can also be used to pre-define variables for all templates processed by the object. my $tt = Template->new({ VARIABLES => { version => 3.14, release => 'Sahara', }, }); my $vars = { serial_no => 271828, }; $tt->process('myfile', $vars); F<myfile> template: This is version [% version %] ([% release %]). Serial number: [% serial_no %] Generated Output: This is version 3.14 (Sahara) Serial number: 271828 Variable names may contain any alphanumeric characters or underscores. They may be lower, upper or mixed case although the usual convention is to use lower case. The case I<is> significant however, and 'C<foo>', 'C<Foo>' and 'C<FOO>' are all different variables. Upper case variable names are permitted, but not recommended due to a possible conflict with an existing or future reserved word. As of version 2.00, these are: GET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER IF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META TRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP CLEAR TO STEP AND OR NOT MOD DIV END The variable values may be of virtually any Perl type, including simple scalars, references to lists, hash arrays, subroutines or objects. The Template Toolkit will automatically apply the correct procedure to accessing these values as they are used in the template. Example data: my $vars = { article => 'The Third Shoe', person => { id => 314, name => 'Mr. Blue', email => 'blue@nowhere.org', }, primes => [ 2, 3, 5, 7, 11, 13 ], wizard => sub { return join(' ', 'Abracadabra!', @_) }, cgi => CGI->new('mode=submit&debug=1'), }; Example template: [% article %] [% person.id %]: [% person.name %] <[% person.email %]> [% primes.first %] - [% primes.last %], including [% primes.3 %] [% primes.size %] prime numbers: [% primes.join(', ') %] [% wizard %] [% wizard('Hocus Pocus!') %] [% cgi.param('mode') %] Generated output: The Third Shoe 314: Mr. Blue <blue@nowhere.org> 2 - 13, including 7 6 prime numbers: 2, 3, 5, 7, 11, 13 Abracadabra! Abracadabra! Hocus Pocus! submit =head2 Scalar Values Regular scalar variables are accessed by simply specifying their name. As these are just entries in the top-level variable hash they can be considered special cases of hash array referencing as described below, with the main namespace hash automatically implied. [% article %] =head2 Hash Array References Members of hash arrays are accessed by specifying the hash reference and key separated by the dot 'C<.>' operator. Example data: my $vars = { 'home' => 'http://www.myserver.com/homepage.html', 'page' => { 'this' => 'mypage.html', 'next' => 'nextpage.html', 'prev' => 'prevpage.html', }, }; Example template: <a href="[% home %]">Home</a> <a href="[% page.prev %]">Previous Page</a> <a href="[% page.next %]">Next Page</a> Generated output: <a href="http://www.myserver.com/homepage.html">Home</a> <a href="prevpage.html">Previous Page</a> <a href="nextpage.html">Next Page</a> Any key in a hash which starts with a 'C<_>' or 'C<.>' character will be considered private and cannot be evaluated or updated from within a template. The undefined value will be returned for any such variable accessed which the Template Toolkit will silently ignore (unless the C<DEBUG> option is enabled). Example data: my $vars = { message => 'Hello World!', _secret => "On the Internet, no-one knows you're a dog", thing => { public => 123, _private => 456, '.hidden' => 789, }, }; Example template: [% message %] # outputs "Hello World!" [% _secret %] # no output [% thing.public %] # outputs "123" [% thing._private %] # no output [% thing..hidden %] # ERROR: unexpected token (..) You can disable this feature by setting the C<$Template::Stash::PRIVATE> package variable to a false value. $Template::Stash::PRIVATE = undef; # now you can thing._private To access a hash entry using a key stored in another variable, prefix the key variable with 'C<$>' to have it interpolated before use (see L<Variable Interpolation>). [% pagename = 'next' %] [% page.$pagename %] # same as [% page.next %] When you assign to a variable that contains multiple namespace elements (i.e. it has one or more 'C<.>' characters in the name), any hashes required to represent intermediate namespaces will be created automatically. In this following example, the C<product> variable automatically springs into life as a hash array unless otherwise defined. [% product.id = 'XYZ-2000' product.desc = 'Bogon Generator' product.price = 666 %] The [% product.id %] [% product.desc %] costs $[% product.price %].00 Generated output: The XYZ-2000 Bogon Generator costs $666.00 You can use Perl's familiar C<{> ... C<}> construct to explicitly create a hash and assign it to a variable. Note that commas are optional between key/value pairs and C<=> can be used in place of C<=E<gt>>. # minimal TT style [% product = { id = 'XYZ-2000' desc = 'Bogon Generator' price = 666 } %] # perl style [% product = { id => 'XYZ-2000', desc => 'Bogon Generator', price => 666, } %] =head2 List References Items in lists are also accessed by use of the dot operator. Example data: my $vars = { people => [ 'Tom', 'Dick', 'Larry' ], }; Example template: [% people.0 %] # Tom [% people.1 %] # Dick [% people.2 %] # Larry The C<FOREACH> directive can be used to iterate through items in a list. [% FOREACH person IN people %] Hello [% person %] [% END %] Generated output: Hello Tom Hello Dick Hello Larry Lists can be constructed in-situ using the regular anonymous list C<[> ... C<]> construct. Commas between items are optional. [% cols = [ 'red', 'green', 'blue' ] %] [% FOREACH c IN cols %] [% c %] [% END %] or: [% FOREACH c IN [ 'red', 'green', 'blue' ] %] [% c %] [% END %] You can also create simple numerical sequences using the C<..> range operator: [% n = [ 1 .. 4 ] %] # n is [ 1, 2, 3, 4 ] [% x = 4 y = 8 z = [x..y] # z is [ 4, 5, 6, 7, 8 ] %] =head2 Subroutines Template variables can contain references to Perl subroutines. When the variable is used, the Template Toolkit will automatically call the subroutine, passing any additional arguments specified. The return value from the subroutine is used as the variable value and inserted into the document output. my $vars = { wizard => sub { return join(' ', 'Abracadabra!', @_) }, }; Example template: [% wizard %] # Abracadabra! [% wizard('Hocus Pocus!') %] # Abracadabra! Hocus Pocus! =head2 Objects Template variables can also contain references to Perl objects. Methods are called using the dot operator to specify the method against the object variable. Additional arguments can be specified as with subroutines. use CGI; my $vars = { # hard coded CGI params for purpose of example cgi => CGI->new('mode=submit&debug=1'), }; Example template: [% FOREACH p IN cgi.param %] # returns list of param keys [% p %] => [% cgi.param(p) %] # fetch each param value [% END %] Generated output: mode => submit debug => 1 Object methods can also be called as lvalues. That is, they can appear on the left side of an assignment. The method will be called passing the assigning value as an argument. [% myobj.method = 10 %] equivalent to: [% myobj.method(10) %] =head2 Passing Parameters and Returning Values Subroutines and methods will be passed any arguments specified in the template. Any template variables in the argument list will first be evaluated and their resultant values passed to the code. my $vars = { mycode => sub { return 'received ' . join(', ', @_) }, }; template: [% foo = 10 %] [% mycode(foo, 20) %] # received 10, 20 Named parameters may also be specified. These are automatically collected into a single hash array which is passed by reference as the B<last> parameter to the sub-routine. Named parameters can be specified using either C<=E<gt>> or C<=> and can appear anywhere in the argument list. my $vars = { myjoin => \&myjoin, }; sub myjoin { # look for hash ref as last argument my $params = ref $_[-1] eq 'HASH' ? pop : { }; return join($params->{ joint } || ' + ', @_); } Example template: [% myjoin(10, 20, 30) %] [% myjoin(10, 20, 30, joint = ' - ' %] [% myjoin(joint => ' * ', 10, 20, 30 %] Generated output: 10 + 20 + 30 10 - 20 - 30 10 * 20 * 30 Parenthesised parameters may be added to any element of a variable, not just those that are bound to code or object methods. At present, parameters will be ignored if the variable isn't "callable" but are supported for future extensions. Think of them as "hints" to that variable, rather than just arguments passed to a function. [% r = 'Romeo' %] [% r(100, 99, s, t, v) %] # outputs "Romeo" User code should return a value for the variable it represents. This can be any of the Perl data types described above: a scalar, or reference to a list, hash, subroutine or object. Where code returns a list of multiple values the items will automatically be folded into a list reference which can be accessed as per normal. my $vars = { # either is OK, first is recommended items1 => sub { return [ 'foo', 'bar', 'baz' ] }, items2 => sub { return ( 'foo', 'bar', 'baz' ) }, }; Example template: [% FOREACH i IN items1 %] ... [% END %] [% FOREACH i IN items2 %] ... [% END %] =head2 Error Handling Errors can be reported from user code by calling C<die()>. Errors raised in this way are caught by the Template Toolkit and converted to structured exceptions which can be handled from within the template. A reference to the exception object is then available as the C<error> variable. my $vars = { barf => sub { die "a sick error has occurred\n"; }, }; Example template: [% TRY %] [% barf %] # calls sub which throws error via die() [% CATCH %] [% error.info %] # outputs "a sick error has occurred\n" [% END %] Error messages thrown via C<die()> are converted to exceptions of type C<undef> (the literal string "undef" rather than the undefined value). Exceptions of user-defined types can be thrown by calling C<die()> with a reference to a L<Template::Exception> object. use Template::Exception; my $vars = { login => sub { ...do something... die Template::Exception->new( badpwd => 'password too silly' ); }, }; Example template: [% TRY %] [% login %] [% CATCH badpwd %] Bad password: [% error.info %] [% CATCH %] Some other '[% error.type %]' error: [% error.info %] [% END %] The exception types C<stop> and C<return> are used to implement the C<STOP> and C<RETURN> directives. Throwing an exception as: die (Template::Exception->new('stop')); has the same effect as the directive: [% STOP %] =head1 Virtual Methods The Template Toolkit implements a number of "virtual methods" which can be applied to scalars, hashes or lists. For example: [% mylist = [ 'foo', 'bar', 'baz' ] %] [% newlist = mylist.sort %] Here C<mylist> is a regular reference to a list, and 'sort' is a virtual method that returns a new list of the items in sorted order. You can chain multiple virtual methods together. For example: [% mylist.sort.join(', ') %] Here the C<join> virtual method is called to join the sorted list into a single string, generating the following output: bar, baz, foo See L<Template::Manual::VMethods> for details of all the virtual methods available. =head1 Variable Interpolation The Template Toolkit uses C<$> consistently to indicate that a variable should be interpolated in position. Most frequently, you see this in double-quoted strings: [% fullname = "$honorific $firstname $surname" %] Or embedded in plain text when the C<INTERPOLATE> option is set: Dear $honorific $firstname $surname, The same rules apply within directives. If a variable is prefixed with a C<$> then it is replaced with its value before being used. The most common use is to retrieve an element from a hash where the key is stored in a variable. [% uid = 'abw' %] [% users.$uid %] # same as 'users.abw' Curly braces can be used to delimit interpolated variable names where necessary. [% users.${me.id}.name %] Directives such as C<INCLUDE>, C<PROCESS>, etc., that accept a template name as the first argument, will automatically quote it for convenience. [% INCLUDE foo/bar.txt %] The above example is equivalent to: [% INCLUDE "foo/bar.txt" %] To C<INCLUDE> a template whose name is stored in a variable, simply prefix the variable name with C<$> to have it interpolated. [% myfile = 'header' %] [% INCLUDE $myfile %] This is equivalent to: [% INCLUDE header %] Note also that a variable containing a reference to a L<Template::Document> object can also be processed in this way. my $vars = { header => Template::Document->new({ ... }), }; Example template: [% INCLUDE $header %] =head1 Local and Global Variables Any simple variables that you create, or any changes you make to existing variables, will only persist while the template is being processed. The top-level variable hash is copied before processing begins and any changes to variables are made in this copy, leaving the original intact. The same thing happens when you C<INCLUDE> another template. The current namespace hash is cloned to prevent any variable changes made in the included template from interfering with existing variables. The C<PROCESS> option bypasses the localisation step altogether making it slightly faster, but requiring greater attention to the possibility of side effects caused by creating or changing any variables within the processed template. [% BLOCK change_name %] [% name = 'bar' %] [% END %] [% name = 'foo' %] [% INCLUDE change_name %] [% name %] # foo [% PROCESS change_name %] [% name %] # bar Dotted compound variables behave slightly differently because the localisation process is only skin deep. The current variable namespace hash is copied, but no attempt is made to perform a deep-copy of other structures within it (hashes, arrays, objects, etc). A variable referencing a hash, for example, will be copied to create a new reference but which points to the same hash. Thus, the general rule is that simple variables (undotted variables) are localised, but existing complex structures (dotted variables) are not. [% BLOCK all_change %] [% x = 20 %] # changes copy [% y.z = 'zulu' %] # changes original [% END %] [% x = 10 y = { z => 'zebra' } %] [% INCLUDE all_change %] [% x %] # still '10' [% y.z %] # now 'zulu' If you create a complex structure such as a hash or list reference within a local template context then it will cease to exist when the template is finished processing. [% BLOCK new_stuff %] [% # define a new 'y' hash array in local context y = { z => 'zulu' } %] [% END %] [% x = 10 %] [% INCLUDE new_stuff %] [% x %] # outputs '10' [% y %] # nothing, y is undefined Similarly, if you update an element of a compound variable which I<doesn't> already exists then a hash will be created automatically and deleted again at the end of the block. [% BLOCK new_stuff %] [% y.z = 'zulu' %] [% END %] However, if the hash I<does> already exist then you will modify the original with permanent effect. To avoid potential confusion, it is recommended that you don't update elements of complex variables from within blocks or templates included by another. If you want to create or update truly global variables then you can use the 'global' namespace. This is a hash array automatically created in the top-level namespace which all templates, localised or otherwise see the same reference to. Changes made to variables within this hash are visible across all templates. [% global.version = 123 %] =head1 Compile Time Constant Folding In addition to variables that get resolved each time a template is processed, you can also define variables that get resolved just once when the template is compiled. This generally results in templates processing faster because there is less work to be done. To define compile-time constants, specify a C<CONSTANTS> hash as a constructor item as per C<VARIABLES>. The C<CONSTANTS> hash can contain any kind of complex, nested, or dynamic data structures, just like regular variables. my $tt = Template->new({ CONSTANTS => { version => 3.14, release => 'skyrocket', col => { back => '#ffffff', fore => '#000000', }, myobj => My::Object->new(), mysub => sub { ... }, joint => ', ', }, }); Within a template, you access these variables using the C<constants> namespace prefix. Version [% constants.version %] ([% constants.release %]) Background: [% constants.col.back %] When the template is compiled, these variable references are replaced with the corresponding value. No further variable lookup is then required when the template is processed. You can call subroutines, object methods, and even virtual methods on constant variables. [% constants.mysub(10, 20) %] [% constants.myobj(30, 40) %] [% constants.col.keys.sort.join(', ') %] One important proviso is that any arguments you pass to subroutines or methods must also be literal values or compile time constants. For example, these are both fine: # literal argument [% constants.col.keys.sort.join(', ') %] # constant argument [% constants.col.keys.sort.join(constants.joint) %] But this next example will raise an error at parse time because C<joint> is a runtime variable and cannot be determined at compile time. # ERROR: runtime variable argument! [% constants.col.keys.sort.join(joint) %] The C<CONSTANTS_NAMESPACE> option can be used to provide a different namespace prefix for constant variables. For example: my $tt = Template->new({ CONSTANTS => { version => 3.14, # ...etc... }, CONSTANTS_NAMESPACE => 'const', }); Constants would then be referenced in templates as: [% const.version %] =head1 Special Variables A number of special variables are automatically defined by the Template Toolkit. =head2 template The C<template> variable contains a reference to the main template being processed, in the form of a L<Template::Document> object. This variable is correctly defined within C<PRE_PROCESS>, C<PROCESS> and C<POST_PROCESS> templates, allowing standard headers, footers, etc., to access metadata items from the main template. The C<name> and C<modtime> metadata items are automatically provided, giving the template name and modification time in seconds since the epoch. Note that the C<template> variable always references the top-level template, even when processing other template components via C<INCLUDE>, C<PROCESS>, etc. =head2 component The C<component> variable is like C<template> but always contains a reference to the current, innermost template component being processed. In the main template, the C<template> and C<component> variable will reference the same L<Template::Document> object. In any other template component called from the main template, the C<template> variable will remain unchanged, but C<component> will contain a new reference to the current component. This example should demonstrate the difference: $template->process('foo') || die $template->error(), "\n"; F<foo> template: [% template.name %] # foo [% component.name %] # foo [% PROCESS footer %] F<footer> template: [% template.name %] # foo [% component.name %] # footer Additionally, the C<component> variable has two special fields: C<caller> and C<callers>. C<caller> contains the name of the template that called the current template (or undef if the values of C<template> and C<component> are the same). C<callers> contains a reference to a list of all the templates that have been called on the road to calling the current component template (like a call stack), with the outer-most template first. Here's an example: F<outer.tt2> template: [% component.name %] # 'outer.tt2' [% component.caller %] # undef [% component.callers %] # undef [% PROCESS 'middle.tt2' %] F<middle.tt2> template: [% component.name %] # 'middle.tt2' [% component.caller %] # 'outer.tt2' [% component.callers %] # [ 'outer.tt2' ] [% PROCESS 'inner.tt2' %] F<inner.tt2> template: [% component.name %] # 'inner.tt2' [% component.caller %] # 'middle.tt2' [% component.callers %] # [ 'outer.tt2', 'middle.tt2' ] =head2 loop Within a C<FOREACH> loop, the C<loop> variable references the L<Template::Iterator> object responsible for controlling the loop. [% FOREACH item = [ 'foo', 'bar', 'baz' ] -%] [% "Items:\n" IF loop.first -%] [% loop.count %]/[% loop.size %]: [% item %] [% END %] =head2 error Within a C<CATCH> block, the C<error> variable contains a reference to the L<Template::Exception> object thrown from within the C<TRY> block. The C<type> and C<info> methods can be called or the variable itself can be printed for automatic stringification into a message of the form "C<$type error - $info>". See L<Template::Exception> for further details. [% TRY %] ... [% CATCH %] [% error %] [% END %] =head2 content The C<WRAPPER> method captures the output from a template block and then includes a named template, passing the captured output as the 'content' variable. [% WRAPPER box %] Be not afeard; the isle is full of noises, Sounds and sweet airs, that give delight and hurt not. [% END %] [% BLOCK box %] <blockquote class="prose"> [% content %] </blockquote> [% END %] =head1 Compound Variables Compound 'dotted' variables may contain any number of separate elements. Each element may evaluate to any of the permitted variable types and the processor will then correctly use this value to evaluate the rest of the variable. Arguments may be passed to any of the intermediate elements. [% myorg.people.sort('surname').first.fullname %] Intermediate variables may be used and will behave entirely as expected. [% sorted = myorg.people.sort('surname') %] [% sorted.first.fullname %] This simplified dotted notation has the benefit of hiding the implementation details of your data. For example, you could implement a data structure as a hash array one day and then change it to an object the next without requiring any change to the templates. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: Syntax.pod 0000444 00000021735 14711272051 0006544 0 ustar 00 #============================================================= -*-perl-*- # # Template::Manual::Syntax # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Manual::Syntax - Directive syntax, structure and semantics =head1 Tag Styles Template directives are embedded between start and end markers tags. By default these tag markers are C<[%> and C<%]>. [% PROCESS header %] <h1>Hello World!</h1> <a href="[% page.next %]"><img src="[% icon.next %].gif"></a> [% PROCESS footer %] You can change the tag characters using the C<START_TAG>, C<END_TAG> and C<TAG_STYLE> configuration options. You can also use the C<TAGS> directive to define a new tag style for the current template file. You can also set the C<INTERPOLATE> option to allow simple variable references to be embedded directly in templates, prefixed by a C<$>. # INTERPOLATE = 0 <td>[% name %]</td> <td>[% email %]</td> # INTERPOLATE = 1 <td>$name</td> <td>$email</td> Directives may be embedded anywhere in a line of text and can be split across several lines. Insignificant whitespace is generally ignored within the directive. [% INCLUDE header title = 'Hello World' bgcol = '#ffffff' %] [%INCLUDE menu align='right'%] Name: [% name %] ([%id%]) =head1 Outline Tags As of version 2.26, the Template Toolkit supports "outline" tags. These have a designated marker at the start of a line (C<%%> by default) and continue to the end of a line. The newline character at the end of the line is discarded (aka "chomped"). So rather than writing something like this: [% IF some.list.size -%] <ul> [% FOREACH item IN some.list -%] <li>[% item.html %]</li> [% END -%] </ul> [% END -%] You can write it like this instead: %% IF some.list.size <ul> %% FOREACH item IN some.list <li>[% item.html %]</li> %% END </ul> %% END Outline tags aren't enabled by default. There are a numbers of ways you can enable them. The first is to use the C<TAGS> directive to set the tag style to C<outline> in any templates where you want to use them. This will enable outline tags from that point on. [% TAGS outline -%] %% INCLUDE header You can set the C<TAGS> back to the C<default> value at some point later in the template if you want to disable them: [% TAGS default -%] You can set the C<TAG_STYLE> configuration option if you want then enabled in all templates by default. You can always use the C<[% TAGS default %]> directive to disable them in any templates or parts of templates if necessary. my $tt = Template->new({ TAG_STYLE => 'outline', }); The C<OUTLINE_TAG> option allows you to set the outline tag marker to something else if you're not a fan of percent signs. Setting this option will automatically enable outline tags. my $tt = Template->new({ OUTLINE_TAG => '>>', }); You can also use the C<TAGS> directive to define your own custom tags (start, end and now optionally, outline) for a template or part of a template. [% TAGS <* *> >> %] >> INCLUDE header # outline tag Hello <* name *> # inline tag If you only specify a start and end tag then outline tags will be disabled. [% TAGS <* *> %] # no outline tags =head1 Comments The C<#> character is used to indicate comments within a directive. When placed immediately inside the opening directive tag, it causes the entire directive to be ignored. [%# this entire directive is ignored no matter how many lines it wraps onto %] In any other position, it causes the remainder of the current line to be treated as a comment. [% # this is a comment theta = 20 # so is this rho = 30 # <aol>me too!</aol> %] =head1 Chomping Whitespace You can add C<-> or C<+> to the immediate start or end of a directive tag to control the whitespace chomping options. See the C<PRE_CHOMP> and C<POST_CHOMP> options for further details. [% BLOCK foo -%] # remove trailing newline This is block foo [%- END %] # remove leading newline =head1 Implicit Directives: GET and SET The simplest directives are C<GET> and C<SET> which retrieve and update variable values respectively. The C<GET> and C<SET> keywords are actually optional as the parser is smart enough to see them for what they really are (but note the caveat below on using side-effect notation). Thus, you'll generally see: [% SET foo = 10 %] [% GET foo %] written as: [% foo = 10 %] [% foo %] You can also express simple logical statements as implicit C<GET> directives: [% title or template.title or 'Default Title' %] [% mode == 'graphics' ? "Graphics Mode Enabled" : "Text Mode" %] All other directives should start with a keyword specified in UPPER CASE (but see the C<ANYCASE> option). All directives keywords are in UPPER CASE to make them visually distinctive and to distinguish them from variables of the same name but different case. It is perfectly valid, for example, to define a variable called C<stop> which is entirely separate from the C<STOP> directive. [% stop = 'Clackett Lane Bus Depot' %] The bus will next stop at [% stop %] # variable [% STOP %] # directive =head1 Block Directives Directives such as C<FOREACH>, C<WHILE>, C<BLOCK>, C<FILTER>, etc., mark the start of a block which may contain text or other directives up to the matching C<END> directive. Blocks may be nested indefinitely. The C<IF>, C<UNLESS>, C<ELSIF> and C<ELSE> directives also define blocks and may be grouped together in the usual manner. [% FOREACH item = [ 'foo' 'bar' 'baz' ] %] * Item: [% item %] [% END %] [% BLOCK footer %] Copyright 2000 [% me %] [% INCLUDE company/logo %] [% END %] [% IF foo %] [% FOREACH thing = foo.things %] [% thing %] [% END %] [% ELSIF bar %] [% INCLUDE barinfo %] [% ELSE %] do nothing... [% END %] Block directives can also be used in a convenient side-effect notation. [% INCLUDE userinfo FOREACH user = userlist %] [% INCLUDE debugtxt msg="file: $error.info" IF debugging %] [% "Danger Will Robinson" IF atrisk %] versus: [% FOREACH user = userlist %] [% INCLUDE userinfo %] [% END %] [% IF debugging %] [% INCLUDE debugtxt msg="file: $error.info" %] [% END %] [% IF atrisk %] Danger Will Robinson [% END %] =head1 Capturing Block Output The output of a directive can be captured by simply assigning the directive to a variable. [% headtext = PROCESS header title="Hello World" %] [% people = PROCESS userinfo FOREACH user = userlist %] This can be used in conjunction with the C<BLOCK> directive for defining large blocks of text or other content. [% poem = BLOCK %] The boy stood on the burning deck, His fleece was white as snow. A rolling stone gathers no moss, And Keith is sure to follow. [% END %] Note one important caveat of using this syntax in conjunction with side-effect notation. The following directive does not behave as might be expected: [% var = 'value' IF some_condition %] # does not work In this case, the directive is interpreted as (spacing added for clarity) [% var = IF some_condition %] value [% END %] rather than [% IF some_condition %] [% var = 'value' %] [% END %] The variable is assigned the output of the C<IF> block which returns C<'value'> if true, but nothing if false. In other words, the following directive will always cause 'var' to be cleared. [% var = 'value' IF 0 %] To achieve the expected behaviour, the directive should be written as: [% SET var = 'value' IF some_condition %] =head1 Chaining Filters Multiple C<FILTER> directives can be chained together in sequence. They are called in the order defined, piping the output of one into the input of the next. [% PROCESS somefile FILTER truncate(100) FILTER html %] The pipe character, C<|>, can also be used as an alias for C<FILTER>. [% PROCESS somefile | truncate(100) | html %] =head1 Multiple Directive Blocks Multiple directives can be included within a single tag when delimited by semi-colons. Note however that the C<TAGS> directive must always be specified in a tag by itself. [% IF title; INCLUDE header; ELSE; INCLUDE other/header title="Some Other Title"; END %] versus [% IF title %] [% INCLUDE header %] [% ELSE %] [% INCLUDE other/header title="Some Other Title" %] [% END %] =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: Internals.pod 0000444 00000043661 14711272051 0007217 0 ustar 00 #============================================================= -*-perl-*- # # Template::Manual::Internals # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Manual::Internals - Template Toolkit internals =head1 Introduction This section of the documentation is aimed at developers wishing to know more about how the Template Toolkit works on the inside in order to extend or adapt it to their own needs. If that doesn't sound like you then you probably don't need to read this. There is no test afterwards. =head1 Outside Looking In The L<Template> module is simply a front end module which creates and uses a L<Template::Service> and pipes the output wherever you want it to go (C<STDOUT> by default, or maybe a file, scalar, etc). The C<Apache::Template> module (available separately from CPAN) is another front end. That creates a C<Template::Service::Apache> object, calls on it as required and sends the output back to the relevant C<Apache::Request> object. These front-end modules are really only there to handle any specifics of the environment in which they're being used. The C<Apache::Template> front end, for example, handles C<Apache::Request> specifics and configuration via the F<httpd.conf>. The regular L<Template> front-end deals with C<STDOUT>, variable refs, etc. Otherwise it is L<Template::Service> (or subclass) which does all the work. The L<Template::Service> module provides a high-quality template delivery service, with bells, whistles, signed up service level agreement and a 30-day no quibble money back guarantee. "Have a good time, all the time", that's our motto. Within the lower levels of the Template Toolkit, there are lots of messy details that we generally don't want to have to worry about most of the time. Things like templates not being found, or failing to parse correctly, uncaught exceptions being thrown, missing plugin modules or dependencies, and so on. L<Template::Service> hides that all away and makes everything look simple to the outsider. It provides extra features, like C<PRE_PROCESS>, C<PROCESS> and C<POST_PROCESS>, and also provides the error recovery mechanism via C<ERROR>. You ask it to process a template and it takes care of everything for you. The C<Template::Service::Apache> module goes a little bit further, adding some extra headers to the L<Apache::Request>, setting a few extra template variables, and so on. For the most part, the job of a service is really just one of scheduling and dispatching. It receives a request in the form of a call to its L<process()|Template::Service#process()> method and schedules the named template specified as an argument, and possibly several other templates (C<PRE_PROCESS>, etc) to be processed in order. It doesn't actually process the templates itself, but instead makes a L<process()|Template::Context#process()> call against a L<Template::Context> object. L<Template::Context> is the runtime engine for the Template Toolkit - the module that hangs everything together in the lower levels of the Template Toolkit and that one that does most of the real work, albeit by crafty delegation to various other friendly helper modules. Given a template name (or perhaps a reference to a scalar or file handle) the context process() method must load and compile, or fetch a cached copy of a previously compiled template, corresponding to that name. It does this by calling on a list of one or more L<Template::Provider> objects (the C<LOAD_TEMPLATES> posse) who themselves might get involved with a L<Template::Parser> to help turn source templates into executable Perl code (but more on that later). Thankfully, all of this complexity is hidden away behind a simple L<template()|Template::Context#template()> method. You call it passing a template name as an argument, and it returns a compiled template in the form of a L<Template::Document> object, or otherwise raises an exception. A L<Template::Document> is a thin object wrapper around a compiled template subroutine. The object implements a L<process()|Template::Document#process()> method which performs a little bit of housekeeping and then calls the template subroutine. The object also defines template metadata (defined in C<[% META ... %]> directives) and has a L<block()|Template::Document#block()> method which returns a hash of any additional C<[% BLOCK xxxx %]> definitions found in the template source. So the context fetches a compiled document via its own L<template()|Template::Context#template()> method and then gets ready to process it. It first updates the stash (the place where template variables get defined - more on that shortly) to set any template variable definitions specified as the second argument by reference to hash array. Then, it calls the document L<process()|Template::Document#process()> method, passing a reference to itself, the context object, as an argument. In doing this, it provides itself as an object against which template code can make callbacks to access runtime resources and Template Toolkit functionality. What we're trying to say here is this: not only does the L<Template::Context> object receive calls from the I<outside>, i.e. those originating in user code calling the process() method on a Template object, but it also receives calls from the I<inside>, i.e. those originating in template directives of the form C<[% PROCESS template %]>. Before we move on to that, here's a simple structure diagram showing the outer layers of the Template Toolkit heading inwards, with pseudo code annotations showing a typical invocation sequence. ,--------. | Caller | use Template; `--------' my $tt = Template->new( ... ); | $tt->process($template, \%vars); | Outside - - - | - - - - - - - - - - - - - - - - - - - - - - - - - - - - T T | package Template; Inside V +----------+ sub process($template, \%vars) { | Template | $out = $self->SERVICE->process($template, $vars); +----------+ print $out or send it to $self->OUTPUT; | } | | package Template::Service; | | sub process($template, \%vars) { | try { +----------+ foreach $p in @self->PRE_PROCESS | Service | $self->CONTEXT->process($p, $vars); +----------+ | $self->CONTEXT->process($template, $vars); | | foreach $p @self->POST_PROCESS | $self->CONTEXT->process($p, $vars); | } | catch { | $self->CONTEXT->process($self->ERROR); | } | } | V package Template::Context; +----------+ | Context | sub process($template, \%vars) { +----------+ # fetch compiled template | $template = $self->template($template) | # update stash | $self->STASH->update($vars); | # process template | $template->process($self) | } V +----------+ package Template::Document; | Document | +----------+ sub process($context) { $output = &{ $self->BLOCK }($context); } =head1 Inside Looking Out To understand more about what's going on in these lower levels, we need to look at what a compiled template looks like. In fact, a compiled template is just a regular Perl sub-routine. Here's a very simple one. sub my_compiled_template { return "This is a compiled template.\n"; } You're unlikely to see a compiled template this simple unless you wrote it yourself but it is entirely valid. All a template subroutine is obliged to do is return some output (which may be an empty of course). If it can't for some reason, then it should raise an error via C<die()>. sub my_todo_template { die "This template not yet implemented\n"; } If it wants to get fancy, it can raise an error as a L<Template::Exception> object. An exception object is really just a convenient wrapper for the 'C<type>' and 'C<info>' fields. sub my_solilique_template { die (Template::Exception->new('yorrick', 'Fellow of infinite jest')); } Templates generally need to do a lot more than just generate static output or raise errors. They may want to inspect variable values, process another template, load a plugin, run a filter, and so on. Whenever a template subroutine is called, it gets passed a reference to a L<Template::Context> object. It is through this context object that template code can access the features of the Template Toolkit. We described earlier how the L<Template::Service> object calls on L<Template::Context> to handle a L<process()|Template::Context#process()> request from the I<outside>. We can make a similar request on a context to process a template, but from within the code of another template. This is a call from the I<inside>. sub my_process_template { my $context = shift; my $output = $context->process('header', { title => 'Hello World' }) . "\nsome content\n" . $context->process('footer'); } This is then roughly equivalent to a source template something like this: [% PROCESS header title = 'Hello World' %] some content [% PROCESS footer %] Template variables are stored in, and managed by a L<Template::Stash> object. This is a blessed hash array in which template variables are defined. The object wrapper provides L<get()|Template::Stash#get()> and L<set()|Template::Stash#set()> method which implement all the I<magical.variable.features> of the Template Toolkit. Each context object has its own stash, a reference to which can be returned by the appropriately named L<stash()|Template::Context#stash()> method. So to print the value of some template variable, or for example, to represent the following source template: <title>[% title %]</title> we might have a subroutine definition something like this: sub { my $context = shift; my $stash = $context->stash(); return '<title>' . $stash->get('title') . '</title>'; } The stash L<get()|Template::Stash#get()> method hides the details of the underlying variable types, automatically calling code references, checking return values, and performing other such tricks. If 'C<title>' happens to be bound to a subroutine then we can specify additional parameters as a list reference passed as the second argument to get(). [% title('The Cat Sat on the Mat') %] This translates to the stash call: $stash->get([ 'title', ['The Cat Sat on the Mat'] ]); Dotted compound variables can be requested by passing a single list reference to the C<get()> method in place of the variable name. Each pair of elements in the list should correspond to the variable name and reference to a list of arguments for each dot-delimited element of the variable. [% foo(1, 2).bar(3, 4).baz(5) %] is thus equivalent to $stash->get([ foo => [1,2], bar => [3,4], baz => [5] ]); If there aren't any arguments for an element, you can specify an empty, zero or null argument list. [% foo.bar %] $stash->get([ 'foo', 0, 'bar', 0 ]); The L<set()|Template::Stash#set()> method works in a similar way. It takes a variable name and a variable value which should be assigned to it. [% x = 10 %] $stash->set('x', 10); [% x.y = 10 %] $stash->set([ 'x', 0, 'y', 0 ], 10); So the stash gives us access to template variables and the context provides the higher level functionality. Alongside the L<process()|Template::Context#process()> method lies the L<include()|Template::Context#include()> method. Just as with the C<PROCESS> / C<INCLUDE> directives, the key difference is in variable localisation. Before processing a template, the C<process()> method simply updates the stash to set any new variable definitions, overwriting any existing values. In contrast, the C<include()> method creates a copy of the existing stash, in a process known as I<cloning> the stash, and then uses that as a temporary variable store. Any previously existing variables are still defined, but any changes made to variables, including setting the new variable values passed aas arguments will affect only the local copy of the stash (although note that it's only a shallow copy, so it's not foolproof). When the template has been processed, the C<include()> method restores the previous variable state by I<decloning> the stash. The context also provides an L<insert()|Template::Context#insert()> method to implement the C<INSERT> directive, but no C<wrapper()> method. This functionality can be implemented by rewriting the Perl code and calling C<include()>. [% WRAPPER foo -%] blah blah [% x %] [%- END %] $context->include('foo', { content => 'blah blah ' . $stash->get('x'), }); Other than the template processing methods C<process()>, C<include()> and C<insert()>, the context defines methods for fetching plugin objects, L<plugin()|Template::Context#plugin()>, and filters, L<filter()|Template::Context#filter()>. # TT USE directive [% USE foo = Bar(10) %] # equivalent Perl $stash->set('foo', $context->plugin('Bar', [10])); # TT FILTER block [% FILTER bar(20) %] blah blah blah [% END %] # equivalent Perl my $filter = $context->filter('bar', [20]); &$filter('blah blah blah'); Pretty much everything else you might want to do in a template can be done in Perl code. Things like C<IF>, C<UNLESS>, C<FOREACH> and so on all have direct counterparts in Perl. # TT IF directive [% IF msg %] Message: [% msg %] [% END %]; # equivalent Perl if ($stash->get('msg')) { $output .= 'Message: '; $output .= $stash->get('msg'); } The best way to get a better understanding of what's going on underneath the hood is to set the C<$Template::Parser::DEBUG> flag to a true value and start processing templates. This will cause the parser to print the generated Perl code for each template it compiles to C<STDERR>. You'll probably also want to set the C<$Template::Directive::PRETTY> option to have the Perl pretty-printed for human consumption. use Template; use Template::Parser; use Template::Directive; $Template::Parser::DEBUG = 1; $Template::Directive::PRETTY = 1; my $template = Template->new(); $template->process(\*DATA, { cat => 'dog', mat => 'log' }); __DATA__ The [% cat %] sat on the [% mat %] The output sent to C<STDOUT> remains as you would expect: The dog sat on the log The output sent to C<STDERR> would look something like this: compiled main template document block: sub { my $context = shift || die "template sub called without context\n"; my $stash = $context->stash; my $output = ''; my $error; eval { BLOCK: { $output .= "The "; $output .= $stash->get('cat'); $output .= " sat on the "; $output .= $stash->get('mat'); $output .= "\n"; } }; if ($@) { $error = $context->catch($@, \$output); die $error unless $error->type eq 'return'; } return $output; } =head1 Hacking on the Template Toolkit Please feel free to hack on the Template Toolkit. If you find a bug that needs fixing, if you have an idea for something that's missing, or you feel inclined to tackle something on the TODO list, then by all means go ahead and do it! If you're contemplating something non-trivial then you'll probably want to bring it up on the mailing list first to get an idea about the current state of play, find out if anyone's already working on it, and so on. The source code repository for the Template Toolkit is hosted at Github. https://github.com/abw/Template2 Clone the repository, make your changes, commit them, then send a pull request. Once you've made your changes, please remember to update the test suite by adding extra tests to one of the existing test scripts in the C<t> sub-directory, or by adding a new test script of your own. And of course, run C<make test> to ensure that all the tests pass with your new code. Don't forget that any files you do add will need to be added to the MANIFEST. Running C<make manifest> will do this for you, but you need to make sure you haven't got any other temporary files lying around that might also get added to it. Documentation is often something that gets overlooked but it's just as important as the code. If you're adding a new module, a plugin module, for example, then it's OK to include the POD documentation in with the module, but I<please> write it all in one piece at the end of the file, I<after> the code (just look at any other C<Template::*> module for an example). It's a religious issue, I know, but I have a strong distaste for POD documentation interspersed throughout the code. In my not-so-humble opinion, it makes both the code and the documentation harder to read (same kinda problem as embedding Perl in HTML). Then add a line to the Changes file giving a very brief description of what you've done. There's no need to go into detail here (save that for the commit message, comments in code or docuemtation where appropriate). Please also make sure you add your name to the lib/Template/Manual/Credits.pod file (if it isn't already there). Then commit your changes and send a pull request. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: Intro.pod 0000444 00000022734 14711272051 0006351 0 ustar 00 #============================================================= -*-perl-*- # # Template::Manual::Intro # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2020 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Manual::Intro - Introduction to the Template Toolkit =head1 Introduction The Template Toolkit is a collection of Perl modules which implement a fast, flexible, powerful and extensible template processing system. It is most often used for generating dynamic web content, although it can be used equally well for processing any kind of text documents. At the simplest level it provides an easy way to process template files, filling in embedded variable references with their equivalent values. Here's an example of a template. Dear [% name %], It has come to our attention that your account is in arrears to the sum of [% debt %]. Please settle your account before [% deadline %] or we will be forced to revoke your Licence to Thrill. The Management. By default, template directives are embedded within the character sequences C<[%> ... C<%]> but you can change these and various other options to configure how the Template Toolkit looks, feels and works. You can set the C<INTERPOLATE> option, for example, if you prefer to embed your variables in Perl style: Dear $name, It has come to our attention that your account is in arrears to the sum of $debt. ...etc... =head1 The Template Perl Module The L<Template> Perl module is the front end to the Template Toolkit for Perl programmers, providing access to the full range of functionality through a single module with a simple interface. It loads the other modules as required and instantiates a default set of objects to handle subsequent template processing requests. Configuration parameters may be passed to the L<Template> constructor method, L<new()|Template#new()>, which are then used to configure the generate object. use Template; my $tt = Template->new({ INCLUDE_PATH => '/usr/local/templates', INTERPOLATE => 1, }) || die "$Template::ERROR\n"; The L<Template> object implements a L<process()|Template#process()> method for processing template files or text. The name of the input template (or various other sources) is passed as the first argument, followed by a reference to a hash array of variable definitions for substitution in the template. my $vars = { name => 'Count Edward van Halen', debt => '3 riffs and a solo', deadline => 'the next chorus', }; $tt->process('letters/overdrawn', $vars) || die $tt->error(), "\n"; The L<process()|Template#process()> method returns a true value (C<1>) on success and prints the template output to C<STDOUT>, by default. On error, the L<process()|Template#process()> method returns a false value (C<undef>). The L<error()|Template#error()> method can then be called to retrieve details of the error. =head1 Component Based Content Construction A number of special directives are provided, such as C<INSERT>, C<INCLUDE> and C<PROCESS>, which allow content to be built up from smaller template components. This permits a modular approach to building a web site or other content repository, promoting reusability, cross-site consistency, ease of construction and subsequent maintenance. Common elements such as headers, footers, menu bars, tables, and so on, can be created as separate template files which can then be processed into other documents as required. All defined variables are inherited by these templates along with any additional "local" values specified. [% PROCESS header title = "The Cat Sat on the Mat" %] [% PROCESS menu %] The location of the missing feline has now been established. Thank you for your assistance. [% INSERT legal/disclaimer %] [% PROCESS footer %] You can also define a template as a BLOCK within the same file and PROCESS it just like any other template file. This can be invaluable for building up repetitive elements such as tables, menus, etc. [% BLOCK tabrow %] <tr><td>[% name %]</td><td>[% email %]</td></tr> [% END %] <table> [% PROCESS tabrow name="tom" email="tom@here.org" %] [% PROCESS tabrow name="dick" email="disk@there.org" %] [% PROCESS tabrow name="larry" email="larry@where.org" %] </table> =head1 Data and Code Binding One of the key features that sets the Template Toolkit apart from other template processors is the ability to bind template variables to any kind of Perl data: scalars, lists, hash arrays, sub-routines and objects. my $vars = { root => 'http://here.com/there', menu => [ 'modules', 'authors', 'scripts' ], client => { name => 'Doctor Joseph von Satriani', id => 'JVSAT', }, checkout => sub { my $total = shift; ...; return $something }, shopcart => My::Cool::Shopping::Cart->new(), }; The Template Toolkit will automatically Do The Right Thing to access the data in an appropriate manner to return some value which can then be output. The dot operator 'C<.>' is used to access into lists and hashes or to call object methods. The C<FOREACH> directive is provided for iterating through lists, and various logical tests are available using directives such as C<IF>, C<UNLESS>, C<ELSIF>, C<ELSE>, C<SWITCH>, C<CASE>, etc. [% FOREACH section = menu %] <a href="[% root %]/[% section %]/index.html">[% section %]</a> [% END %] <b>Client</b>: [% client.name %] (id: [% client.id %]) [% IF shopcart.nitems %] Your shopping cart contains the following items: <ul> [% FOREACH item = shopcart.contents %] <li>[% item.name %] : [% item.qty %] @ [% item.price %] [% END %] </ul> [% checkout(shopcart.total) %] [% ELSE %] No items currently in shopping cart. [% END %] =head1 Advanced Features: Filters, Macros, Exceptions, Plugins The Template Toolkit also provides a number of additional directives for advanced processing and programmatical functionality. It supports output filters (FILTER), allows custom macros to be defined (MACRO), has a fully-featured exception handling system (TRY, THROW, CATCH, FINAL) and supports a plugin architecture (USE) which allows special plugin modules and even regular Perl modules to be loaded and used with the minimum of fuss. The Template Toolkit is "just" a template processor but you can trivially extend it to incorporate the functionality of any Perl module you can get your hands on. Thus, it is also a scalable and extensible template framework, ideally suited for managing the presentation layer for application servers, content management systems and other web applications. =head1 Separating Presentation and Application Logic Rather than embedding Perl code or some other scripting language directly into template documents, it encourages you to keep functional components (i.e. Perl code) separate from presentation components (e.g. HTML templates). The template variables provide the interface between the two layers, allowing data to be generated in code and then passed to a template component for displaying (pipeline model) or for sub-routine or object references to be bound to variables which can then be called from the template as and when required (callback model). The directives that the Template Toolkit provide implement their own mini programming language, but they're not really designed for serious, general purpose programming. Perl is a far more appropriate language for that. If you embed application logic (e.g. Perl or other scripting language fragments) in HTML templates then you risk losing the clear separation of concerns between functionality and presentation. It becomes harder to maintain the two elements in isolation and more difficult, if not impossible, to reuse code or presentation elements by themselves. It is far better to write your application code in separate Perl modules, libraries or scripts and then use templates to control how the resulting data is presented as output. Thus you should think of the Template Toolkit language as a set of layout directives for displaying data, not calculating it. Having said that, the Template Toolkit doesn't force you into one approach or the other. It attempts to be pragmatic rather than dogmatic in allowing you to do whatever best gets the job done. Thus, if you enable the EVAL_PERL option then you can happily embed real Perl code in your templates within PERL ... END directives. =head1 Performance The Template Toolkit uses a fast YACC-like parser which compiles templates into Perl code for maximum runtime efficiency. It also has an advanced caching mechanism which manages in-memory and on-disk (i.e. persistent) versions of compiled templates. The modules that comprise the toolkit are highly configurable and the architecture around which they're built is designed to be extensible. The Template Toolkit provides a powerful framework around which content creation and delivery systems can be built while also providing a simple interface through the Template front-end module for general use. =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: VMethods.pod 0000444 00000051013 14711272051 0006777 0 ustar 00 #============================================================= -*-perl-*- # # Template::Manual::VMethods # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2015 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =head1 NAME Template::Manual::VMethods - Virtual Methods =head1 Scalar Virtual Methods =head2 chunk(size) Splits the value into a list of chunks of a certain size. [% ccard_no = "1234567824683579"; ccard_no.chunk(4).join %] Output: 1234 5678 2468 3579 If the size is specified as a negative number then the text will be chunked from right-to-left. This gives the correct grouping for numbers, for example. [% number = 1234567; number.chunk(-3).join(',') %] Output: 1,234,567 =head2 collapse Returns the text with any leading and trailing whitespace removed and any internal sequences of whitespace converted to a single space [% text = " The bird\n is the word" %] [% text.collapse %] # The bird is the word =head2 defined Returns true if the value is defined. [% user = get_user(uid) IF uid.defined %] =head2 dquote Returns the text with any double quote characters escaped with a backslash prefix. Any newline characters in the text will be replaced with "\n". [% quote = 'He said "Oh really?"' %] [% quote.dquote %] # He said \"Oh really?\" =head2 hash Return the value as a hash reference containing a single entry with the key C<value> indicating the original scalar value. As with the C<list> virtual method, this is generally used to help massage data into different formats. =head2 lcfirst Returns the text with the first letter converted to lower case. [% word = 'BIRD' %] [% word.lcfirst %] # bIRD =head2 length Returns the length of the string representation of the item: [% IF password.length < 8 %] Password too short, dumbass! [% END %] =head2 empty Returns true if the string is empty: [% IF details.empty %] No details specified [% END %] =head2 list Return the value as a single element list. This can be useful if you have a variable which may contain a single item or a list and you want to treat them equally. The C<list> method can be called against a list reference and will simply return the original reference, effectively a no-op. [% thing.list.size %] # thing can be a scalar or a list =head2 lower Returns the text in lower case. [% word = 'BIRD' %] [% word.lower %] # bird =head2 match(pattern, global) Performs a regular expression match on the string using the pattern passed as an argument. If the pattern matches the string then the method returns a reference to a list of any strings captured within parenthesis in the pattern. [% name = 'Larry Wall' %] [% matches = name.match('(\w+) (\w+)') %] [% matches.1 %], [% matches.0 %] # Wall, Larry If the pattern does not match then the method returns false, rather than returning an empty list which Perl and the Template Toolkit both consider to be a true value. This allows you to write expression like this. [% "We're not worthy!" IF name.match('Larry Wall') %] [% IF (matches = name.match('(\w+) (\w+)')) %] pattern matches: [% matches.join(', ') %] [% ELSE %] pattern does not match [% END %] Any regex modifiers, like C</s>, should be added in the regex using the C<(?s)> syntax. For example, to modify the regex to disregard whitespace (the C</x> switch), use: [% re = '(?x) (\w+) [ ] (\w+) '; matches = name.match(re); %] To perform a global search to match the pattern as many times as it appears in the source string, provide a true value for the C<global> argument following the pattern. [% text = 'bandanna'; text.match('an+', 1).join(', ') # an, ann %] =head2 repeat(n) Repeat the string a specified number of times. [% name = 'foo' %] [% name.repeat(3) %] # foofoofoo =head2 replace(search, replace) Outputs the string with all instances of the first argument (specified as a Perl regular expression) with the second. [% name = 'foo, bar & baz' %] [% name.replace('\W+', '_') %] # foo_bar_baz You can use C<$1>, C<$2>, etc., to reference captured parts (in parentheses) in the regular expression. Just be careful to I<single> quote the replacement string. If you use I<double> quotes then TT will try and interpolate the variables before passing the string to the C<replace> vmethod. [% name = 'FooBarBaz' %] [% name.replace('([A-Z])', ' $1') %] # Foo Bar Baz =head2 remove(pattern) Outputs the string with all instances of the pattern (specified as a Perl regular expression) removed. [% name = 'foo, bar & baz' %] [% name.remove('\W+') %] # foobarbaz =head2 search(pattern) Performs a similar function to L<match> but simply returns true if the string matches the regular expression pattern passed as an argument. [% name = 'foo bar baz' %] [% name.search('bar') ? 'bar' : 'no bar' %] # bar This virtual method is now deprecated in favour of L<match>. Move along now, there's nothing more to see here. =head2 size Always returns 1 for scalar values. This method is provided for consistency with the hash and list size methods. =head2 split(pattern) Calls Perl's C<split()> function to split a string into a list of strings. [% FOREACH dir IN mypath.split(':') %] [% dir %] [% END %] =head2 substr(offset, length, replacement) Returns a substring starting at C<offset>, for C<length> characters. [% str 'foo bar baz wiz waz woz') %] [% str.substr(4, 3) %] # bar If C<length> is not specified then it returns everything from the C<offset> to the end of the string. [% str.substr(12) %] # wiz waz woz If both C<length> and C<replacement> are specified, then the method replaces everything from C<offset> for C<length> characters with C<$replacement>. The substring removed from the string is then returned. [% str.substr(0, 11, 'FOO') %] # foo bar baz [% str %] # FOO wiz waz woz =head2 squote Returns the text with any single quote characters escaped with a backslash prefix. [% tim = "Tim O'Reilly" %] [% tim.squote %] # Tim O\'Reilly =head2 trim Returns the text with any leading and trailing whitespace removed. [% text = ' hello world ' %] [% text.trim %] # hello world =head2 ucfirst Returns the text with the first letter converted to upper case. [% word = 'bird' %] [% word.ucfirst %] # Bird =head2 upper Returns the text in upper case. [% word = 'bird' %] [% word.upper %] # BIRD =head1 Hash Virtual Methods =head2 keys Returns a list of keys in the hash. They are not returned in any particular order, but the order is the same as for the corresponding values method. [% FOREACH key IN hash.keys %] * [% key %] [% END %] If you want the keys in sorted order, use the list C<sort> method. [% FOREACH key IN hash.keys.sort %] * [% key %] [% END %] Having got the keys in sorted order, you can then use variable interpolation to fetch the value. This is shown in the following example by the use of C<$key> to fetch the item from C<hash> whose key is stored in the C<key> variable. [% FOREACH key IN hash.keys.sort %] * [% key %] = [% hash.$key %] [% END %] Alternately, you can use the C<pairs> method to get a list of key/value pairs in sorted order. =head2 values Returns a list of the values in the hash. As with the C<keys> method, they are not returned in any particular order, although it is the same order that the keys are returned in. [% hash.values.join(', ') %] =head2 items Returns a list of both the keys and the values expanded into a single list. [% hash = { a = 10 b = 20 }; hash.items.join(', ') # a, 10, b, 20 %] =head2 each This method currently returns the same thing as the C<items> method. However, please note that this method will change in the next major version of the Template Toolkit (v3) to return the same thing as the C<pairs> method. This will be done in an effort to make these virtual method more consistent with each other and how Perl works. In anticipation of this, we recommend that you stop using C<hash.each> and instead use C<hash.items>. =head2 pairs This method returns a list of key/value pairs. They are returned in sorted order according to the keys. [% FOREACH pair IN product.pairs %] * [% pair.key %] is [% pair.value %] [% END %] =head2 list Returns the contents of the hash in list form. An argument can be passed to indicate the desired items required in the list: C<keys> to return a list of the keys (same as C<hash.keys>), C<values> to return a list of the values (same as C<hash.values>), C<each> to return as list of key and values (same as C<hash.each>), or C<pairs> to return a list of key/value pairs (same as C<hash.pairs>). [% keys = hash.list('keys') %] [% values = hash.list('values') %] [% items = hash.list('each') %] [% pairs = hash.list('pairs') %] When called without an argument it currently returns the same thing as the C<pairs> method. However, please note that this method will change in the next major version of the Template Toolkit (v3) to return a reference to a list containing the single hash reference (as per the scalar list method). In anticipation of this, we recommend that you stop using C<hash.list> and instead use C<hash.pairs>. =head2 sort, nsort Return a list of the keys, sorted alphabetically (C<sort>) or numerically (C<nsort>) according to the corresponding values in the hash. [% FOREACH n IN phones.sort %] [% phones.$n %] is [% n %], [% END %] =head2 import The C<import> method can be called on a hash array to import the contents of another hash array. [% hash1 = { foo = 'Foo' bar = 'Bar' } hash2 = { wiz = 'Wiz' woz = 'Woz' } %] [% hash1.import(hash2) %] [% hash1.wiz %] # Wiz You can also call the C<import()> method by itself to import a hash array into the current namespace hash. [% user = { id => 'lwall', name => 'Larry Wall' } %] [% import(user) %] [% id %]: [% name %] # lwall: Larry Wall =head2 defined, exists Returns a true or false value if an item in the hash denoted by the key passed as an argument is defined or exists, respectively. [% hash.defined('somekey') ? 'yes' : 'no' %] [% hash.exists('somekey') ? 'yes' : 'no' %] When called without any argument, C<hash.defined> returns true if the hash itself is defined (e.g. the same effect as C<scalar.defined>). =head2 delete Delete one or more items from the hash. [% hash.delete('foo', 'bar') %] =head2 size Returns the number of key/value pairs in the hash. =head2 empty Returns true if the hash is empty: [% IF config.empty %] No configuration available [% END %] =head2 item Returns an item from the hash using a key passed as an argument. [% hash.item('foo') %] # same as hash.foo =head1 List Virtual Methods =head2 first, last Returns the first/last item in the list. The item is not removed from the list. [% results.first %] to [% results.last %] If either is given a numeric argument C<n>, they return the first or last C<n> elements: The first 5 results are [% results.first(5).join(", ") %]. =head2 size, max Returns the size of a list (number of elements) and the maximum index number (size - 1), respectively. [% results.size %] search results matched your query =head2 empty Returns true if the list is empty: [% IF results.empty %] No results found [% END %] =head2 defined Returns a true or false value if the item in the list denoted by the argument is defined. [% list.defined(3) ? 'yes' : 'no' %] When called without any argument, C<list.defined> returns true if the list itself is defined (e.g. the same effect as C<scalar.defined>). =head2 reverse Returns the items of the list in reverse order. [% FOREACH s IN scores.reverse %] ... [% END %] =head2 join Joins the items in the list into a single string, using Perl's C<join()> function. [% items.join(', ') %] =head2 grep Returns a list of the items in the list that match a regular expression pattern. [% FOREACH directory.files.grep('\.txt$') %] ... [% END %] =head2 sort, nsort Returns the items in alpha (C<sort>) or numerical (C<nsort>) order. [% library = books.sort %] An argument can be provided to specify a search key. Where an item in the list is a hash reference, the search key will be used to retrieve a value from the hash which will then be used as the comparison value. Where an item is an object which implements a method of that name, the method will be called to return a comparison value. [% library = books.sort('author') %] In the example, the C<books> list can contains hash references with an C<author> key or objects with an C<author> method. You can also specify multiple sort keys. [% library = books.sort('author', 'title') %] In this case the books will be sorted primarily by author. If two or more books have authors with the same name then they will be sorted by title. =head2 unshift(item), push(item) The C<push()> method adds an item or items to the end of list. [% mylist.push(foo) %] [% mylist.push(foo, bar) %] The C<unshift()> method adds an item or items to the start of a list. [% mylist.unshift(foo) %] [% mylist.push(foo, bar) %] =head2 shift, pop Removes the first/last item from the list and returns it. [% first = mylist.shift %] [% last = mylist.pop %] =head2 unique Returns a list of the unique elements in a list, in the same order as in the list itself. [% mylist = [ 1, 2, 3, 2, 3, 4, 1, 4, 3, 4, 5 ] %] [% numbers = mylist.unique %] While this can be explicitly sorted, it is not required that the list be sorted before the unique elements are pulled out (unlike the Unix command line utility). [% numbers = mylist.unique.sort %] =head2 import Appends the contents of one or more other lists to the end of the current list. [% one = [ 1 2 3 ]; two = [ 4 5 6 ]; three = [ 7 8 9 ]; one.import(two, three); one.join(', '); # 1, 2, 3, 4, 5, 6, 7, 8, 9 %] Import also allows chaining. The below syntax is equivalent. [% one = [ 1 2 3 ]; two = [ 4 5 6 ]; three = [ 7 8 9 ]; one.import(two, three).join(', '); # 1, 2, 3, 4, 5, 6, 7, 8, 9 # or: one.import(two).import(three).join(', '); # 1, 2, 3, 4, 5, 6, 7, 8, 9 %] =head2 merge Returns a list composed of zero or more other lists: [% list_one = [ 1 2 3 ]; list_two = [ 4 5 6 ]; list_three = [ 7 8 9 ]; list_four = list_one.merge(list_two, list_three); %] The original lists are not modified. =head2 slice(from, to) Returns a slice of items in the list between the bounds passed as arguments. If the second argument, C<to>, isn't specified, then it defaults to the last item in the list. The original list is not modified. [% first_three = list.slice(0,2) %] [% last_three = list.slice(-3, -1) %] =head2 splice(offset, length, list) Behaves just like Perl's C<splice()> function allowing you to selectively remove and/or replace elements in a list. It removes C<length> items from the list, starting at C<offset> and replaces them with the items in C<list>. [% play_game = [ 'play', 'scrabble' ]; ping_pong = [ 'ping', 'pong' ]; redundant = play_game.splice(1, 1, ping_pong); redundant.join; # scrabble play_game.join; # play ping pong %] The method returns a list of the items removed by the splice. You can use the C<CALL> directive to ignore the output if you're not planning to do anything with it. [% CALL play_game.splice(1, 1, ping_pong) %] As well as providing a reference to a list of replacement values, you can pass in a list of items. [% CALL list.splice(-1, 0, 'foo', 'bar') %] Be careful about passing just one item in as a replacement value. If it is a reference to a list then the contents of the list will be used. If it's not a list, then it will be treated as a single value. You can use square brackets around a single item if you need to be explicit: [% # push a single item, an_item CALL list.splice(-1, 0, an_item); # push the items from another_list CALL list.splice(-1, 0, another_list); # push a reference to another_list CALL list.splice(-1, 0, [ another_list ]); %] =head2 hash Returns a reference to a hash array comprised of the elements in the list. The even-numbered elements (0, 2, 4, etc) become the keys and the odd-numbered elements (1, 3, 5, etc) the values. [% list = ['pi', 3.14, 'e', 2.718] %] [% hash = list.hash %] [% hash.pi %] # 3.14 [% hash.e %] # 2.718 If a numerical argument is provided then the hash returned will have keys generated for each item starting at the number specified. [% list = ['beer', 'peanuts'] %] [% hash = list.hash(1) %] [% hash.1 %] # beer [% hash.2 %] # peanuts =head2 item Returns an item from the list using an index passed as an argument. [% list.item(0) %] # same as list.0 =head1 Automagic Promotion of Scalar to List for Virtual Methods In addition to the scalar virtual methods listed in the previous section, you can also call any list virtual method against a scalar. The item will be automagically promoted to a single element list and the appropriate list virtual method will be called. One particular benefit of this comes when calling subroutines or object methods that return a list of items, rather than the preferred reference to a list of items. In this case, the Template Toolkit automatically folds the items returned into a list. The upshot is that you can continue to use existing Perl modules or code that returns lists of items, without having to refactor it just to keep the Template Toolkit happy (by returning references to list). C<Class::DBI> module is just one example of a particularly useful module which returns values this way. If only a single item is returned from a subroutine then the Template Toolkit assumes it meant to return a single item (rather than a list of 1 item) and leaves it well alone, returning the single value as it is. If you're executing a database query, for example, you might get 1 item returned, or perhaps many items which are then folded into a list. The C<FOREACH> directive will happily accept either a list or a single item which it will treat as a list. So it's safe to write directives like this, where we assume that the C<something> variable is bound to a subroutine which may return one or more items: [% FOREACH item IN something %] ... [% END %] The automagic promotion of scalars to single item lists means that you can also use list virtual methods safely, even if you only get one item returned. For example: [% something.first %] [% something.join %] [% something.reverse.join(', ') %] Note that this is very much a last-ditch behaviour. If the single item return is an object with a C<first> method, for example, then that will be called, as expected, in preference to the list virtual method. =head1 Defining Custom Virtual Methods You can define your own virtual methods for scalars, lists and hash arrays. The L<Template::Stash> package variables C<$SCALAR_OPS>, C<$LIST_OPS> and C<$HASH_OPS> are references to hash arrays that define these virtual methods. C<HASH_OPS> and C<LIST_OPS> methods are subroutines that accept a hash/list reference as the first item. C<SCALAR_OPS> are subroutines that accept a scalar value as the first item. Any other arguments specified when the method is called will be passed to the subroutine. # load Template::Stash to make method tables visible use Template::Stash; # define list method to return new list of odd numbers only $Template::Stash::LIST_OPS->{ odd } = sub { my $list = shift; return [ grep { $_ % 2 } @$list ]; }; Example template: [% primes = [ 2, 3, 5, 7, 9 ] %] [% primes.odd.join(', ') %] # 3, 5, 7, 9 TODO: document the define_vmethod() method which makes this even easier =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4: Filters.pod 0000444 00000033472 14711272052 0006670 0 ustar 00 #============================================================= -*-perl-*- # # Template::Manual::Filters # # AUTHOR # Andy Wardley <abw@wardley.org> # # COPYRIGHT # Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. # # This module is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # #======================================================================== =encoding latin1 =head1 NAME Template::Manual::Filters - Standard filters =head1 format(format) The C<format> filter takes a format string as a parameter (as per C<printf()>) and formats each line of text accordingly. [% FILTER format('<!-- %-40s -->') %] This is a block of text filtered through the above format. [% END %] Output: <!-- This is a block of text filtered --> <!-- through the above format. --> =head1 upper Folds the input to UPPER CASE. [% "hello world" FILTER upper %] Output: HELLO WORLD =head1 lower Folds the input to lower case. [% "Hello World" FILTER lower %] Output: hello world =head1 ucfirst Folds the first character of the input to UPPER CASE. [% "hello" FILTER ucfirst %] Output: Hello =head1 lcfirst Folds the first character of the input to lower case. [% "HELLO" FILTER lcfirst %] Output: hELLO =head1 trim Trims any leading or trailing whitespace from the input text. Particularly useful in conjunction with C<INCLUDE>, C<PROCESS>, etc., having the same effect as the C<TRIM> configuration option. [% INCLUDE myfile | trim %] =head1 collapse Collapse any whitespace sequences in the input text into a single space. Leading and trailing whitespace (which would be reduced to a single space) is removed, as per trim. [% FILTER collapse %] The cat sat on the mat [% END %] Output: The cat sat on the mat =head1 html Converts the characters C<E<lt>>, C<E<gt>>, C<&> and C<"> to C<<>, C<>>, C<&>, and C<"> respectively, protecting them from being interpreted as representing HTML tags or entities. [% FILTER html %] Binary "<=>" returns -1, 0, or 1 depending on... [% END %] Output: Binary "<=>" returns -1, 0, or 1 depending on... =head1 html_entity The C<html> filter is fast and simple but it doesn't encode the full range of HTML entities that your text may contain. The C<html_entity> filter uses either the C<Apache::Util> module (which is written in C and is therefore faster) or the C<HTML::Entities> module (written in Perl but equally as comprehensive) to perform the encoding. If one or other of these modules are installed on your system then the text will be encoded (via the C<escape_html()> or C<encode_entities()> subroutines respectively) to convert all extended characters into their appropriate HTML entities (e.g. converting 'C<?>' to 'C<é>'). If neither module is available on your system then an 'C<html_entity>' exception will be thrown reporting an appropriate message. If you want to force TT to use one of the above modules in preference to the other, then call either of the L<Template::Filters> class methods: L<use_html_entities()|Template::Filters/use_html_entities()> or L<use_apache_util()|Template::Filters/use_apache_util()>. use Template::Filters; Template::Filters->use_html_entities; For further information on HTML entity encoding, see L<http://www.w3.org/TR/REC-html40/sgml/entities.html>. =head1 xml Same as the C<html> filter, but adds C<'> which is the fifth XML built-in entity. =head1 html_para This filter formats a block of text into HTML paragraphs. A sequence of two or more newlines is used as the delimiter for paragraphs which are then wrapped in HTML C<E<lt>pE<gt>>...C<E<lt>/pE<gt>> tags. [% FILTER html_para %] The cat sat on the mat. Mary had a little lamb. [% END %] Output: <p> The cat sat on the mat. </p> <p> Mary had a little lamb. </p> =head1 html_break / html_para_break Similar to the html_para filter described above, but uses the HTML tag sequence C<E<lt>brE<gt>E<lt>brE<gt>> to join paragraphs. [% FILTER html_break %] The cat sat on the mat. Mary had a little lamb. [% END %] Output: The cat sat on the mat. <br> <br> Mary had a little lamb. =head1 html_line_break This filter replaces any newlines with C<E<lt>brE<gt>> HTML tags, thus preserving the line breaks of the original text in the HTML output. [% FILTER html_line_break %] The cat sat on the mat. Mary had a little lamb. [% END %] Output: The cat sat on the mat.<br> Mary had a little lamb.<br> =head1 uri This filter URI escapes the input text, converting any characters outside of the permitted URI character set (as defined by RFC 3986) into a C<%nn> hex escape. [% 'my file.html' | uri %] Output: my%20file.html The uri filter correctly encodes all reserved characters, including C<&>, C<@>, C</>, C<;>, C<:>, C<=>, C<+>, C<?> and C<$>. This filter is typically used to encode parameters in a URL that could otherwise be interpreted as part of the URL. Here's an example: [% path = 'http://tt2.org/example' back = '/other?foo=bar&baz=bam' title = 'Earth: "Mostly Harmless"' %] <a href="[% path %]?back=[% back | uri %]&title=[% title | uri %]"> The output generated is rather long so we'll show it split across two lines: <a href="http://tt2.org/example?back=%2Fother%3Ffoo%3Dbar%26 baz%3Dbam&title=Earth%3A%20%22Mostly%20Harmless%22"> Without the uri filter the output would look like this (also split across two lines). <a href="http://tt2.org/example?back=/other?foo=bar &baz=bam&title=Earth: "Mostly Harmless""> In this rather contrived example we've manage to generate both a broken URL (the repeated C<?> is not allowed) and a broken HTML element (the href attribute is terminated by the first C<"> after C<Earth: > leaving C<Mostly Harmless"> dangling on the end of the tag in precisely the way that harmless things shouldn't dangle). So don't do that. Always use the uri filter to encode your URL parameters. However, you should B<not> use the uri filter to encode an entire URL. <a href="[% page_url | uri %]"> # WRONG! This will incorrectly encode any reserved characters like C<:> and C</> and that's almost certainly not what you want in this case. Instead you should use the B<url> (note spelling) filter for this purpose. <a href="[% page_url | url %]"> # CORRECT Please note that this behaviour was changed in version 2.16 of the Template Toolkit. Prior to that, the uri filter did not encode the reserved characters, making it technically incorrect according to the RFC 2396 specification (since superceded by RFC2732 and RFC3986). So we fixed it in 2.16 and provided the url filter to implement the old behaviour of not encoding reserved characters. As of version 2.28 of the Template Toolkit, the C<uri> and L<url> filters use the unsafe character set defined by RFC3986. This means that certain characters ("(", ")", "*", "!", "'", and '"') are now deemed unsafe and will be escaped as hex character sequences. The ability to use the RFC3986 character set was added in 2.26 but not enabled by default; double quote was incorrectly deemed safe in 2.26 but correctly escaped in 2.27. If you want to enable the old behaviour then call the C<use_rfc2732()> method in L<Template::Filters> use Template::Filters Template::Filters->use_rfc2732; =head1 url The url filter is a less aggressive version of the uri filter. It encodes any characters outside of the permitted URI character set (as defined by RFC 2396) into C<%nn> hex escapes. However, unlike the uri filter, the url filter does B<not> encode the reserved characters C<&>, C<@>, C</>, C<;>, C<:>, C<=>, C<+>, C<?> and C<$>. =head1 indent(pad) Indents the text block by a fixed pad string or width. The 'C<pad>' argument can be specified as a string, or as a numerical value to indicate a pad width (spaces). Defaults to 4 spaces if unspecified. [% FILTER indent('ME> ') %] blah blah blah cabbages, rhubard, onions [% END %] Output: ME> blah blah blah ME> cabbages, rhubard, onions =head1 truncate(length,dots) Truncates the text block to the length specified, or a default length of 32. Truncated text will be terminated with 'C<...>' (i.e. the 'C<...>' falls inside the required length, rather than appending to it). [% FILTER truncate(21) %] I have much to say on this matter that has previously been said on more than one occasion. [% END %] Output: I have much to say... If you want to use something other than 'C<...>' you can pass that as a second argument. [% FILTER truncate(26, '…') %] I have much to say on this matter that has previously been said on more than one occasion. [% END %] Output: I have much to say… =head1 repeat(iterations) Repeats the text block for as many iterations as are specified (default: 1). [% FILTER repeat(3) %] We want more beer and we want more beer, [% END %] We are the more beer wanters! Output: We want more beer and we want more beer, We want more beer and we want more beer, We want more beer and we want more beer, We are the more beer wanters! =head1 remove(string) Searches the input text for any occurrences of the specified string and removes them. A Perl regular expression may be specified as the search string. [% "The cat sat on the mat" FILTER remove('\s+') %] Output: Thecatsatonthemat =head1 replace(search, replace) Similar to the remove filter described above, but taking a second parameter which is used as a replacement string for instances of the search string. [% "The cat sat on the mat" | replace('\s+', '_') %] Output: The_cat_sat_on_the_mat =head1 redirect(file, options) The C<redirect> filter redirects the output of the block into a separate file, specified relative to the C<OUTPUT_PATH> configuration item. [% FOREACH user IN myorg.userlist %] [% FILTER redirect("users/${user.id}.html") %] [% INCLUDE userinfo %] [% END %] [% END %] or more succinctly, using side-effect notation: [% FOREACH user IN myorg.userlist; INCLUDE userinfo FILTER redirect("users/${user.id}.html"); END %] A C<file> exception will be thrown if the C<OUTPUT_PATH> option is undefined. An optional C<binmode> argument can follow the filename to explicitly set the output file to binary mode. [% PROCESS my/png/generator FILTER redirect("images/logo.png", binmode=1) %] For backwards compatibility with earlier versions, a single true/false value can be used to set binary mode. [% PROCESS my/png/generator FILTER redirect("images/logo.png", 1) %] For the sake of future compatibility and clarity, if nothing else, we would strongly recommend you explicitly use the named C<binmode> option as shown in the first example. =head1 eval / evaltt The C<eval> filter evaluates the block as template text, processing any directives embedded within it. This allows template variables to contain template fragments, or for some method to be provided for returning template fragments from an external source such as a database, which can then be processed in the template as required. my $vars = { fragment => "The cat sat on the [% place %]", }; $template->process($file, $vars); The following example: [% fragment | eval %] is therefore equivalent to The cat sat on the [% place %] The C<evaltt> filter is provided as an alias for C<eval>. =head1 perl / evalperl The C<perl> filter evaluates the block as Perl code. The C<EVAL_PERL> option must be set to a true value or a C<perl> exception will be thrown. [% my_perl_code | perl %] In most cases, the C<[% PERL %]> ... C<[% END %]> block should suffice for evaluating Perl code, given that template directives are processed before being evaluate as Perl. Thus, the previous example could have been written in the more verbose form: [% PERL %] [% my_perl_code %] [% END %] as well as [% FILTER perl %] [% my_perl_code %] [% END %] The C<evalperl> filter is provided as an alias for C<perl> for backwards compatibility. =head1 stdout(options) The stdout filter prints the output generated by the enclosing block to C<STDOUT>. The C<binmode> option can be passed as either a named parameter or a single argument to set C<STDOUT> to binary mode (see the binmode perl function). [% PROCESS something/cool FILTER stdout(binmode=1) # recommended %] [% PROCESS something/cool FILTER stdout(1) # alternate %] The C<stdout> filter can be used to force C<binmode> on C<STDOUT>, or also inside C<redirect>, C<null> or C<stderr> blocks to make sure that particular output goes to C<STDOUT>. See the C<null> filter below for an example. =head1 stderr The stderr filter prints the output generated by the enclosing block to C<STDERR>. =head1 null The C<null> filter prints nothing. This is useful for plugins whose methods return values that you don't want to appear in the output. Rather than assigning every plugin method call to a dummy variable to silence it, you can wrap the block in a null filter: [% FILTER null; USE im = GD.Image(100,100); black = im.colorAllocate(0, 0, 0); red = im.colorAllocate(255,0, 0); blue = im.colorAllocate(0, 0, 255); im.arc(50,50,95,75,0,360,blue); im.fill(50,50,red); im.png | stdout(1); END; -%] Notice the use of the C<stdout> filter to ensure that a particular expression generates output to C<STDOUT> (in this case in binary mode). =cut # Local Variables: # mode: perl # perl-indent-level: 4 # indent-tabs-mode: nil # End: # # vim: expandtab shiftwidth=4:
| ver. 1.4 |
Github
|
.
| PHP 7.4.33 | Генерация страницы: 0 |
proxy
|
phpinfo
|
Настройка