| Template::Alloy(3pm) | User Contributed Perl Documentation | Template::Alloy(3pm) |
Template::Alloy - TT2/3, HT, HTE, Tmpl, and Velocity Engine
my $t = Template::Alloy->new(
INCLUDE_PATH => ['/path/to/templates'],
);
my $swap = {
key1 => 'val1',
key2 => 'val2',
code => sub { 42 },
hash => {a => 'b'},
};
# print to STDOUT
$t->process('my/template.tt', $swap)
|| die $t->error;
# process into a variable
my $out = '';
$t->process('my/template.tt', $swap, \$out);
### Alloy uses the same syntax and configuration as Template::Toolkit
my $t = Template::Alloy->new(
filename => 'my/template.ht',
path => ['/path/to/templates'],
);
my $swap = {
key1 => 'val1',
key2 => 'val2',
code => sub { 42 },
hash => {a => 'b'},
};
$t->param($swap);
# print to STDOUT (errors die)
$t->output(print_to => \*STDOUT);
# process into a variable
my $out = $t->output;
### Alloy can also use the same syntax and configuration as HTML::Template
my $t = Template::Alloy->new;
my $swap = {
key1 => 'val1',
key2 => 'val2',
code => sub { 42 },
hash => {a => 'b'},
};
$t->set_delimiters('#[', ']#');
$t->set_strip(0);
$t->set_values($swap);
$t->set_dir('/path/to/templates');
my $out = $t->parse_file('my/template.tmpl');
my $str = "Foo #[echo $key1]# Bar";
my $out = $t->parse_string($str);
### Alloy uses the same syntax and configuration as Text::Tmpl
my $t = Template::Alloy->new;
my $swap = {
key1 => 'val1',
key2 => 'val2',
code => sub { 42 },
hash => {a => 'b'},
};
my $out = $t->merge('my/template.vtl', $swap);
my $str = "#set($foo 1 + 3) ($foo) ($bar) ($!baz)";
my $out = $t->merge(\$str, $swap);
my $t = Template::Alloy->new;
my $swap = {
key1 => 'val1',
key2 => 'val2',
code => sub { 42 },
hash => {a => 'b'},
};
my $out = '';
$t->process_js('my/template.jstem', $swap, \$out);
my $str = "[% var foo = 1 + 3; write('(' + foo + ') (' + get('key1') + ')'); %]";
my $out = '';
$t->process_js(\$str, $swap, \$out);
"An alloy is a homogeneous mixture of two or more elements" (http://en.wikipedia.org/wiki/Alloy).
Template::Alloy represents the mixing of features and capabilities from all of the major mini-language based template systems (support for non-mini-language based systems will happen eventually). With Template::Alloy you can use your favorite template interface and syntax and get features from each of the other major template systems. And Template::Alloy is fast - whether your using mod_perl, CGI, or running from the commandline. There is even Template::Alloy::JS for getting a little more speed when that is necessary.
Template::Alloy happened by accident (accidentally on purpose). The Template::Alloy (Alloy hereafter) was originally a part of the CGI::Ex suite that performed simple variable interpolation. It used TT2 style variables in TT2 style tags "[% foo.bar %]". That was all the original Template::Alloy did. This was fine and dandy for a couple of years. In winter of 2005-2006 Alloy was revamped to add a few features. One thing led to another and soon Alloy provided for most of the features of TT2 as well as some from TT3. Template::Alloy now provides a full-featured implementation of the Template::Toolkit language.
After a move to a new company that was using HTML::Template::Expr and Text::Tmpl templates, support was investigated and interfaces for HTML::Template, HTML::Template::Expr, Text::Tmpl, and Velocity (VTL) were added. All of the various engines offer the same features - each using a different syntax and interface.
More recently, the Template::Alloy::JS capabilities were introduced to bring Javascript templates to the server side (along with an increase in speed if ran in persistent environments).
Template::Toolkit brought the most to the table. HTML::Template brought the LOOP directive. HTML::Template::Expr brought more vmethods and using vmethods as top level functions. Text::Tmpl brought the COMMENT directive and encouraged speed matching (Text::Tmpl is almost entirely C based and is very fast). The Velocity engine brought AUTO_EVAL and SHOW_UNDEFINED_INTERP.
Most of the standard Template::Toolkit documentation covering directives, variables, configuration, plugins, filters, syntax, and vmethods should apply to Alloy just fine (This pod tries to explain everything - but there is too much). See Template::Alloy::TT for a listing of the differences between Alloy and TT.
Most of the standard HTML::Template and HTML::Template::Expr documentation covering methods, variables, expressions, and syntax will apply to Alloy just fine as well.
Most of the standard Text::Tmpl documentation applies, as does the documentation covering Velocity (VTL).
So should you use Template::Alloy ? Well, try it out. It may give you no visible improvement. Or it could.
Template::Alloy uses a recursive regex based grammar (early versions during the CGI::Ex::Template phase did not). This allows for the embedding of opening and closing tags inside other tags (as in [% a = "[% 1 + 2 %]" ; a|eval %]). The individual methods such as parse_expr and play_expr may be used by external applications to add TT style variable parsing to other applications.
The regex parser returns an AST (abstract syntax tree) of the text, directives, variables, and expressions. All of the different template syntax options compile to the same AST format. The AST is composed only of scalars and arrayrefs and is suitable for sending to JavaScript via JSON or sharing with other languages. The parse_tree method is used for returning this AST.
Once at the AST stage, there are two modes of operation. Alloy can either operate directly on the AST using the Play role, or it can compile the AST to perl code via the Compile role, and then execute the code. To use the perl code route, you must set the COMPILE_PERL flag to 1. If you are running in a cached-in-memory environment such as mod_perl, this is the fastest option. If you are running in a non-cached-in-memory environment, then using the Play role to run the AST is generally faster. The AST method is also more secure as cached AST won't ever eval any "perl" (assuming PERL blocks are disabled - which is the default).
Template::Alloy has split out its functionality into discrete roles. In Template::Toolkit, this functionality is split into separate classes. The roles in Template::Alloy simply add on more methods to the main class. When Perl 6 arrives, these roles will be translated into true Roles.
The following is a list of roles used by Template::Alloy.
Template::Alloy::Compile - Compile-to-perl role
Template::Alloy::HTE - HTML::Template::Expr role
Template::Alloy::Operator - Operator role
Template::Alloy::Parse - Parse-to-AST role
Template::Alloy::Play - Play-AST role
Template::Alloy::Stream - Stream output role
Template::Alloy::Tmpl - Text::Tmpl role
Template::Alloy::TT - Template::Toolkit role
Template::Alloy::Velocity - Velocity role
Template::Alloy::VMethod - Virtual methods role
Template::Alloy::JS - Javascript functionality - available separately
Template::Alloy automatically loads the roles when they are needed or requested - but not sooner (with the exception of the Operator role and the VMethod role which are always needed and always loaded). This is good for a CGI environment. In mod_perl you may want to preload a role to make the most of shared memory. You may do this by passing either the role name or a method supplied by that role.
# import roles necessary for running TT
use Template::Alloy qw(Parse Play Compile TT);
# import roles based on methods
use Template::Alloy qw(parse_tree play_tree compile_tree process);
Note: importing roles by method names does not import them into that namespace - it is autoloading the role and methods into the Template::Alloy namespace. To help make this more clear you may use the following syntax as well.
# import roles necessary for running TT
use Template::Alloy load => qw(Parse Play Compile TT);
# import roles based on methods
use Template::Alloy load => qw(process parse_tree play_tree compile_tree);
# import roles based on methods
use Template::Alloy
Parse => 1,
Play => 1,
Compile => 1,
TT => 1;
Even with all roles loaded Template::Alloy is still relatively small. You can load all of the roles (except the JS role) by passing "all" to the use statement.
use Template::Alloy 'all';
# or
use Template::Alloy load => 'all';
# or
use Template::Alloy all => 1;
As a final option, Template::Alloy also includes the ability to stand-in for other template modules. It is able to do this because it supports the majority of the interface of the other template systems. You can do this in the following way:
use Template::Alloy qw(Text::Tmpl HTML::Template);
# or
use Template::Alloy load => qw(Text::Tmpl HTML::Template);
# or
use Template::Alloy
'Text::Tmpl' => 1,
'HTML::Template' => 1;
Note that the use statement will die if any of the passed module names are already loaded and not subclasses of Template::Alloy. This will avoid thinking that you are using Template::Alloy when you really aren't. Using the 'all' option won't automatically do this - you must mention the "stood-in" modules by name.
The following modules may be "stood-in" for:
Template
Text::Tmpl
HTML::Template
HTML::Template::Expr
This feature is intended to make using Template::Alloy with existing code easier. Most cases should work just fine. Almost all syntax will just work (except Alloy may make some things work that were previously broken). However Template::Alloy doesn't support 100% of the interface of any of the template systems. If you are using "features-on-the-edge" then you may need to re-write portions of your code that interact with the template system.
The following section lists most of the publicly available methods. Some less commonly used public methods are listed later in this document.
my $obj = Template::Alloy->new({
INCLUDE_PATH => ['/my/path/to/content', '/my/path/to/content2'],
});
Arguments may be passed as a hash or as a hashref. Returns a Template::Alloy object.
There are currently no errors during Template::Alloy object creation. If you are using the HTML::Template interface, this is different behavior. The document is not parsed until the output or process methods are called.
my $t = Template::Alloy->new;
$t->process($in, $swap, $out)
|| die $t->error;
Process takes three arguments.
The $in argument can be any one of:
String containing the filename of the template to be processed.
The filename should be relative to INCLUDE_PATH. (See
INCLUDE_PATH, ABSOLUTE, and RELATIVE configuration items). In
memory caching and file side caching are available for this type.
A reference to a scalar containing the contents of the template to be processed.
A coderef that will be called to return the contents of the template.
An open filehandle that will return the contents of the template when read.
The $swap argument should be hashref containing key value pairs that will be available to variables swapped into the template. Values can be hashrefs, hashrefs of hashrefs and so on, arrayrefs, arrayrefs of arrayrefs and so on, coderefs, objects, and simple scalar values such as numbers and strings. See the section on variables.
The $out argument can be any one of:
undef - meaning to print the completed template to STDOUT.
String containing a filename. The completed template will be placed in the file.
A reference to a string. The contents will be appended to the scalar reference.
A coderef. The coderef will be called with the contents as a single argument.
An object that can run the method "print". The contents will be passed as
a single argument to print.
An arrayref. The contents will be pushed onto the array.
An open filehandle. The contents will be printed to the open handle.
Additionally - the $out argument can be configured using the OUTPUT configuration item.
The process method defaults to using the "cet" syntax which will parse TT3 and most TT2 documents. To parse HT or HTE documents, you must pass the SYNTAX configuration item to the "new" method. All calls to process would then default to HTE syntax.
my $obj = Template::Alloy->new(SYNTAX => 'hte');
The $in parameter is limited to a filename or a reference a string containing the contents.
The $out parameter may only be a reference to a scalar string that output will be appended to.
Additionally, the following configuration variables will be ignored: VARIABLES, PRE_DEFINE, BLOCKS, PRE_PROCESS, PROCESS, POST_PROCESS, AUTO_RESET, OUTPUT.
$obj->process('somefile.html', {a => 'b'}, \$string_ref)
|| die $obj->error;
my $obj = Template::Alloy->new(filename => 'myfile.html');
$obj->param(\%swap);
print $obj->output;
See the HTML::Template documentation for more information.
The output method defaults to using the "hte" syntax which will parse HTE and HT documents. To parse TT3 or TT2 documents, you must pass the SYNTAX configuration item to the "new" method. All calls to process would then default to TT3 syntax.
my $obj = Template::Alloy->new(SYNTAX => 'tt3');
Any errors that occur during the output method will die with the error as the die value.
my $val = $obj->param('key'); # get one value
$obj->param(key => $val); # set one value
$obj->param(key => $val, key2 => $val2); # set multiple
$obj->param({key => $val, key2 => $val2}); # set multiple
See the HTML::Template documentation for more information.
Note: Alloy does not support the die_on_bad_params configuration. This is because Alloy does not resolve variable names until the output method is called.
Template::Alloy->define_vmethod(
'text',
reverse => sub { my $item = shift; return scalar reverse $item },
);
Template::Alloy->register_function(
reverse => sub { my $item = shift; return scalar reverse $item },
);
Template::Alloy->define_directive(
MYDIR => {
parse_sub => sub {}, # parse additional items in the tag
play_sub => sub {
my ($self, $ref, $node, $out_ref) = @_;
$$out_ref .= "I always say the same thing!";
return;
},
is_block => 1, # is this block like
is_postop => 0, # not a post operative directive
no_interp => 1, # no interpolation in this block
continues => undef, # it doesn't "continue" any other directives
},
);
Now with a template like:
my $str = "([% MYDIR %]This is something[% END %])";
Template::Alloy->new->process(\$str);
You will get:
(I always say the same thing!)
We'll add more details in later revisions of this document.
Template::Alloy->define_syntax(
my_uber_syntax => sub {
my $self = shift;
local $self->{'V2PIPE'} = 0;
local $self->{'V2EQUALS'} = 0;
local $self->{'PRE_CHOMP'} = 0;
local $self->{'POST_CHOMP'} = 0;
local $self->{'NO_INCLUDES'} = 0;
return $self->parse_tree_tt3(@_);
},
);
The subroutine that is used must return an opcode tree (AST) that can be played by the execute_tree method.
Template::Alloy->define_operator({
type => 'right', # can be one of prefix, postfix, right, left, none, ternary, assign
precedence => 84, # relative precedence for resolving multiple operators without parens
symbols => ['foo', 'FOO'], # any mix of chars can be used for the operators
play_sub => sub {
my ($one, $two) = @_;
return "You've been foo'ed ($one, $two)";
},
});
You can then use it in a template as in the following:
my $str = "[% 'ralph' foo 1 + 2 * 3 %]";
Template::Alloy->new->process(\$str);
You will get:
You've been foo'ed (ralph, 7)
Future revisions of this document will include more samples. This is an experimental feature and the API will probably change.
# import by role
Template::Alloy->import(qw(Compile Play Parse TT));
# import by method
Template::Alloy->import(qw(compile_tree play_tree parse_tree process));
# import by "stand-in" class
Template::Alloy->import('Text::Tmpl', 'HTML::Template::Expr');
As mentioned in the ROLE section - arguments passed to import are not imported into current namespace. Roles and methods are only imported into the Template::Alloy namespace.
This section discusses how to use variables and expressions in the TT mini-language.
A variable is the most simple construct to insert into the TT mini language. A variable name will look for the matching value inside Template::Alloys internal stash of variables which is essentially a hash reference. This stash is initially populated by either passing a hashref as the second argument to the process method, or by setting the "VARIABLES" or "PRE_DEFINE" configuration variables.
If you are using either the HT or the HTE syntax, the VAR, IF, UNLESS, LOOP, and INCLUDE directives will accept a NAME attribute which may only be a single level (non-chained) HTML::Template variable name, or they may accept an EXPR attribute which may be any valid TT3 variable or expression.
The following are some sample ways to access variables.
### some sample variables
my %vars = (
one => '1.0',
foo => 'bar',
vname => 'one',
some_code => sub { "You passed me (".join(', ', @_).")" },
some_data => {
a => 'A',
bar => 3234,
c => [3, 1, 4, 1, 5, 9],
vname => 'one',
},
my_list => [20 .. 50],
cet => Template::Alloy->new,
);
### pass the variables into the Alloy process
$cet->process($template_name, \%vars)
|| die $cet->error;
### pass the variables during object creation (will be available to every process call)
my $cet = Template::Alloy->new(VARIABLES => \%vars);
Once you have variables defined, they can be used directly in the template by using their name in the stash. Or by using the GET directive.
[% foo %]
[% one %]
[% GET foo %]
Would print when processed:
bar
1.0
bar
To access members of a hashref or an arrayref, you can chain together the names using a ".".
[% some_data.a %]
[% my_list.0] [% my_list.1 %] [% my_list.-1 %]
[% some_data.c.2 %]
Would print:
A
20 21 50
4
If the value of a variable is a code reference, it will be called. You can add a set of parenthesis and arguments to pass arguments. Arguments are variables and can be as complex as necessary.
[% some_code %]
[% some_code() %]
[% some_code(foo) %]
[% some_code(one, 2, 3) %]
Would print:
You passed me ().
You passed me ().
You passed me (bar).
You passed me (1.0, 2, 3).
If the value of a variable is an object, methods can be called using the "." operator.
[% cet %]
[% cet.dump_parse_expr('1 + 2').replace('\s+', ' ') %]
Would print something like:
Template::Alloy=HASH(0x814dc28)
$VAR1 = [ [ undef, '+', '1', '2' ], 0 ];
Each type of data (string, array and hash) have virtual methods associated with them. Virtual methods allow for access to functions that are commonly used on those types of data. For the full list of built in virtual methods, please see the section titled VIRTUAL METHODS
[% foo.length %]
[% my_list.size %]
[% some_data.c.join(" | ") %]
Would print:
3
31
3 | 1 | 4 | 5 | 9
It is also possible to "interpolate" variable names using a "$". This allows for storing the name of a variable inside another variable. If a variable name is a little more complex it can be embedded inside of "${" and "}".
[% $vname %]
[% ${vname} %]
[% ${some_data.vname} %]
[% some_data.$foo %]
[% some_data.${foo} %]
Would print:
1.0
1.0
1.0
3234
3234
In Alloy it is also possible to embed any expression (non-directive) in "${" and "}" and it is possible to use non-integers for array access. (This is not available in TT2)
[% ['a'..'z'].${ 2.3 } %]
[% {ab => 'AB'}.${ 'a' ~ 'b' } %]
[% color = qw/Red Blue/; FOR [1..4] ; color.${ loop.index % color.size } ; END %]
Would print:
c
AB
RedBlueRedBlue
To define variables during processing, you can use the = operator. In most cases this is the same as using the SET directive.
[% a = 234 %][% a %]
[% SET b = "Hello" %][% b %]
Would print:
234
Hello
It is also possible to create arrayrefs and hashrefs.
[% a = [1, 2, 3] %]
[% b = {key1 => 'val1', 'key2' => 'val2'} %]
[% a.1 %]
[% b.key1 %] [% b.key2 %]
Would print:
2
val1 val2
It is possible to set multiple values in the same SET directive.
[% SET a = 'A'
b = 'B'
c = 'C' %]
[% a %] [% b %] [% c %]
Would print:
A B C
It is also possible to unset variables, or to set members of nested data structures.
[% a = 1 %]
[% SET a %]
[% b.0.c = 37 %]
([% a %])
[% b.0.c %]
Would print
()
37
The following are the types of literals (numbers and strings) and constructors (hash and array constructs) allowed in Alloy. They can be used as arguments to functions, in place of variables in directives, and in place of variables in expressions. In Alloy it is also possible to call virtual methods on literal values.
[% 23423 %] Prints an integer.
[% 3.14159 %] Prints a number.
[% pi = 3.14159 %] Sets the value of the variable.
[% 3.13159.length %] Prints 7 (the string length of the number)
Scientific notation is supported.
[% 314159e-5 + 0 %] Prints 3.14159.
[% .0000001.fmt('%.1e') %] Prints 1.0e-07
Hexadecimal input is also supported.
[% 0xff + 0 %] Prints 255
[% 48875.fmt('%x') %] Prints beeb
[% 'foobar' %] Prints "foobar".
[% '$foo\n' %] Prints "$foo\\n". # the \\n is a literal "\" and an "n"
[% 'That\'s nice' %] Prints "That's nice".
[% str = 'A string' %] Sets the value of str.
[% 'A string'.split %] Splits the string on ' ' and returns the list.
Note: virtual methods can only be used on literal strings in Alloy, not in TT.
You may also embed the current tags in strings (Alloy only).
[% '[% 1 + 2 %]' | eval %] Prints "3"
[% "foobar" %] Prints "foobar".
[% "$foo" %] Prints "bar" (assuming the value of foo is bar).
[% "${foo}" %] Prints "bar" (assuming the value of foo is bar).
[% "foobar\n" %] Prints "foobar\n". # the \n is a newline.
[% str = "Hello" %] Sets the value of str.
[% "foo".replace('foo','bar') %] Prints "bar".
Note: virtual methods can only be used on literal strings in Alloy, not in TT.
You may also embed the current tags in strings (Alloy only).
[% "[% 1 + 2 %]" | eval %] Prints "3"
[% [1, 2, 3] %] Prints something like ARRAY(0x8309e90).
[% array1 = [1 .. 3] %] Sets the value of array1.
[% array2 = [foo, 'a', []] %] Sets the value of array2.
[% [4, 5, 6].size %] Prints 3.
[% [7, 8, 9].reverse.0 %] Prints 9.
Note: virtual methods can only be used on array constructs in Alloy, not in TT.
[% qw/1 2 3/ %] Prints something like ARRAY(0x8309e90).
[% array1 = qw{Foo Bar Baz} %] Sets the value of array1.
[% qw[4 5 6].size %] Prints 3.
[% qw(Red Blue).reverse.0 %] Prints Blue.
Note: this works in Alloy and is planned for TT3.
[% {foo => 'bar'} %] Prints something like HASH(0x8305880)
[% hash = {foo => 'bar', c => {}} %] Sets the value of hash.
[% {a => 'A', b => 'B'}.size %] Prints 2.
[% {'a' => 'A', 'b' => 'B'}.size %] Prints 2.
[% name = "Tom" %]
[% {Tom => 'You are Tom',
Kay => 'You are Kay'}.$name %] Prints You are Tom
Note: virtual methods can only be used on hash constructs in Alloy, not in TT.
[% /foo/ %] Prints (?-xism:foo)
[% a = /(foo)/i %][% "FOO".match(a).0 %] Prints FOO
Note: this works in Alloy and is planned for TT3.
Virtual methods (vmethods) are a TT feature that allow for operating on the swapped template variables.
This document shows some samples of using vmethods. For a full listing of available virtual methods, see Template::Alloy::VMethod.
Expressions are one or more variables or literals joined together with operators. An expression can be used anywhere a variable can be used with the exception of the variable name in the SET directive, and the filename of PROCESS, INCLUDE, WRAPPER, and INSERT.
For a full listing of operators, see Template::Alloy::Operator.
The following section shows some samples of expressions. For a full list of available operators, please see the section titled OPERATORS.
[% 1 + 2 %] Prints 3
[% 1 + 2 * 3 %] Prints 7
[% (1 + 2) * 3 %] Prints 9
[% x = 2 %] # assignments don't return anything
[% (x = 2) %] Prints 2 # unless they are in parens
[% y = 3 %]
[% x * (y - 1) %] Prints 4
This section contains the alphabetical list of DIRECTIVES available in Alloy. DIRECTIVES are the "functions" and control structures that work in the various mini-languages. For further discussion and examples beyond what is listed below, please refer to the TT directives documentation or to the appropriate documentation for the particular directive.
The examples given in this section are done using the Template::Toolkit syntax, but can be done in any of the various syntax options. See Template::Alloy::TT, Template::Alloy::HTE, Template::Alloy::Tmpl, and Template::Alloy::Velocity.
[% IF 1 %]One[% END %]
[% FOREACH a = [1 .. 3] %]
a = [% a %]
[% END %]
[% SET a = 1 %][% SET a = 2 %][% GET a %]
In TT multiple directives can be inside the same set of '[%' and '%]' tags as long as they are separated by space or semi-colons (;) (The Alloy version of Tmpl allows multiple also - but none of the other syntax options do). Any block directive that can also be used as a post-operative directive (such as IF, WHILE, FOREACH, UNLESS, FILTER, and WRAPPER) must be separated from preceding directives with a semi-colon if it is being used as a block directive. It is more safe to always use a semi-colon. Note: separating by space is only available in Alloy but is a planned TT3 feature.
[% SET a = 1 ; SET a = 2 ; GET a %]
[% SET a = 1
SET a = 2
GET a
%]
[% GET 1
IF 0 # is a post-operative
GET 2 %] # prints 2
[% GET 1;
IF 0 # it is block based
GET 2
END
%] # prints 1
The following is the list of directives.
[% BLOCK foo %]Some text[% END %]
[% PROCESS foo %]
Would print
Some text
[% INCLUDE foo %]
[% BLOCK foo %]Some text[% END %]
Would print
Some text
Anonymous BLOCKS can be used for capturing.
[% a = BLOCK %]Some text[% END %][% a %]
Would print
Some text
Anonymous BLOCKS can be used with macros.
[% COMMENT %]
This text won't be shown.
[% IF 1 %]And this won't either.[% END %]
[% END %]
[% CONFIG
ANYCASE => 1
PRE_CHOMP => '-'
%]
The following compile time configuration options may be set:
ANYCASE
AUTO_EVAL
AUTO_FILTER
CACHE_STR_REFS
ENCODING
INTERPOLATE
POST_CHOMP
PRE_CHOMP
SEMICOLONS
SHOW_UNDEFINED_INTERP
SYNTAX
V1DOLLAR
V2EQUALS
V2PIPE
The following runtime configuration options may be set:
ADD_LOCAL_PATH
CALL_CONTEXT
DUMP
VMETHOD_FUNCTIONS
STRICT (can only be enabled, cannot be disabled)
If non-named parameters as passed, they will show the current configuration:
[% CONFIG ANYCASE, PRE_CHOMP %]
CONFIG ANYCASE = undef
CONFIG PRE_CHOMP = undef
[% DEBUG format '($file) (line $line) ($text)' %]
[% DEBUG on %]
[% DEBUG off %]
[% DEFAULT foo = 'bar' %][% foo %] => 'bar'
[% foo = 'baz' %][% DEFAULT foo = 'bar' %][% foo %] => 'baz'
The output also includes the current file and line number that the DUMP directive was called from.
See the DUMP configuration item for ways to customize and control the output available to the DUMP directive.
[% DUMP %] # dumps everything
[% DUMP 1 + 2 %]
[% EVALUATE "[% 1 + 3 %]" %]
[% foo = "bar" %]
[% EVALUATE "<TMPL_VAR foo>" SYNTAX => 'ht' %]
TODO - enumerate the at least 7 ways to pass and use filters.
[% FOREACH i IN [1 .. 3] %]
The variable i = [% i %]
[%~ END %]
[% a = [1 .. 3] %]
[% FOREACH j IN a %]
The variable j = [% j %]
[%~ END %]
Would print:
The variable i = 1
The variable i = 2
The variable i = 3
The variable j = 1
The variable j = 2
The variable j = 3
You can also use the "=" instead of "IN" or "in".
[% FOREACH i = [1 .. 3] %]
The variable i = [% i %]
[%~ END %]
Same as before.
Setting into a variable is optional.
[% a = [1 .. 3] %]
[% FOREACH a %] Hi [% END %]
Would print:
hi hi hi
If the item being iterated is a hashref and the FOREACH does not set into a variable, then values of the hashref are copied into the variable stash.
[% FOREACH [{a => 1}, {a => 2}] %]
Key a = [% a %]
[%~ END %]
Would print:
Key a = 1
Key a = 2
The FOREACH process uses the Template::Alloy::Iterator class to handle iterations (It is compatible with Template::Iterator). During the FOREACH loop an object blessed into the iterator class is stored in the variable "loop".
The loop variable provides the following information during a FOREACH:
index - the current index
max - the max index of the list
size - the number of items in the list
count - index + 1
number - index + 1
first - true if on the first item
last - true if on the last item
next - return the next item in the list
prev - return the previous item in the list
odd - return 1 if the current count is odd, 0 otherwise
even - return 1 if the current count is even, 0 otherwise
parity - return "odd" if the current count is odd, "even" otherwise
The following:
[% FOREACH [1 .. 3] %] [% loop.count %]/[% loop.size %] [% END %]
Would print:
1/3 2/3 3/3
The iterator is also available using a plugin. This allows for access to multiple "loop" variables in a nested FOREACH directive.
[%~ USE outer_loop = Iterator(["a", "b"]) %]
[%~ FOREACH i = outer_loop %]
[%~ FOREACH j = ["X", "Y"] %]
[% outer_loop.count %]-[% loop.count %] = ([% i %] and [% j %])
[%~ END %]
[%~ END %]
Would print:
1-1 = (a and X)
1-2 = (a and Y)
2-1 = (b and X)
2-2 = (b and Y)
FOREACH may also be used as a post operative directive.
[% "$i" FOREACH i = [1 .. 5] %] => 12345
[% GET a %]
The GET keyword may be omitted.
[% a %]
[% 7 + 2 - 3 %] => 6
See the section on VARIABLES.
[% IF a == b %]A equaled B[% END %]
[% IF a == b -%]
A equaled B
[%- ELSIF a == c -%]
A equaled C
[%- ELSE -%]
Couldn't determine that A equaled anything.
[%- END %]
IF may also be used as a post operative directive.
[% 'A equaled B' IF a == b %]
Note: If you are using HTML::Template style documents, the TMPL_IF tag parses using the limited HTML::Template parsing rules. However, you may use EXPR="" to embed a TT3 style expression.
[% INCLUDE path/to/template.html %]
[% INCLUDE "path/to/template.html" %]
[% file = "path/to/template.html" %]
[% INCLUDE $file %]
[% BLOCK foo %]This is foo[% END %]
[% INCLUDE foo %]
Arguments may also be passed to the template:
[% INCLUDE "path/to/template.html" a = "An arg" b = "Another arg" %]
Filenames must be relative to INCLUDE_PATH unless the ABSOLUTE or RELATIVE configuration items are set.
Multiple filenames can be passed by separating them with a plus, a space, or commas (TT2 doesn't support the comma). Any supplied arguments will be used on all templates.
[% INCLUDE "path/to/template.html",
"path/to/template2.html" a = "An arg" b = "Another arg" %]
On Perl 5.6 on some platforms there may be some issues with the variable localization. There is no problem on 5.8 and greater.
Filenames must be relative to INCLUDE_PATH unless the ABSOLUTE or RELATIVE configuration items are set.
Multiple filenames can be passed by separating them with a plus, a space, or commas (TT2 doesn't support the comma).
[% INSERT "path/to/template.html",
"path/to/template2.html" %]
Allow eval'ing the block of text as javascript. The block will be parsed and then eval'ed.
[% a = "BimBam" %]
[%~ JS %]
write('The variable a was "' + get('a') + '"');
set('b', "FooBar");
[% END %]
[% b %]
Would print:
The variable a was "BimBam"
FooBar
[% var a = [{b => 1}, {b => 2}, {b => 3}] %]
[% LOOP a %] ([% b %]) [% END %]
Would print:
(1) (2) (3)
If Alloy is in HT mode and GLOBAL_VARS is false, the contents of the hashref will be the only items available during the loop iteration.
If LOOP_CONTEXT_VARS is true, and
$QR_PRIVATE is false (default when called
through the output method), then the variables __first__, __last__,
__inner__, __odd__, and __counter__ will be set. See the HTML::Template
loop_context_vars configuration item for more information.
[% MACRO foo(i, j) BLOCK %]You passed me [% i %] and [% j %].[% END %]
[%~ foo("a", "b") %]
[% foo(1, 2) %]
Would print:
You passed me a and b.
You passed me 1 and 2.
Another example:
[% MACRO bar(max) FOREACH i = [1 .. max] %]([% i %])[% END %]
[%~ bar(4) %]
Would print:
(1)(2)(3)(4)
Starting with version 1.012 of Template::Alloy there is also a macro operator.
[% foo = ->(i,j){ "You passed me $i and $j" } %]
[% bar = ->(max){ FOREACH i = [1 .. max]; i ; END } %]
See the Template::Alloy::Operator documentation for more examples.
Once defined, they cannot be overwritten.
[% template.foobar %]
[%~ META foobar = 'baz' %]
[%~ META foobar = 'bing' %]
Would print:
baz
Allow eval'ing the block of text as perl. The block will be parsed and then eval'ed.
[% a = "BimBam" %]
[%~ PERL %]
my $a = "[% a %]";
print "The variable \$a was \"$a\"";
$stash->set('b', "FooBar");
[% END %]
[% b %]
Would print:
The variable $a was "BimBam"
FooBar
During execution, anything printed to STDOUT will be inserted into the template. Also, the $stash and $context variables are set and are references to objects that mimic the interface provided by Template::Context and Template::Stash. These are provided for compatibility only. $self contains the current Template::Alloy object.
[% PROCESS path/to/template.html %]
[% PROCESS "path/to/template.html" %]
[% file = "path/to/template.html" %]
[% PROCESS $file %]
[% BLOCK foo %]This is foo[% END %]
[% PROCESS foo %]
Arguments may also be passed to the template:
[% PROCESS "path/to/template.html" a = "An arg" b = "Another arg" %]
Filenames must be relative to INCLUDE_PATH unless the ABSOLUTE or RELATIVE configuration items are set.
Multiple filenames can be passed by separating them with a plus, a space, or commas (TT2 doesn't support the comma). Any supplied arguments will be used on all templates.
[% PROCESS "path/to/template.html",
"path/to/template2.html" a = "An arg" b = "Another arg" %]
There are two changes from TT2 behavior. First, In Alloy, a RETURN during a MACRO call will only exit the MACRO. Second, the RETURN directive takes an optional variable name or expression, if passed, the MACRO will return this value instead of the normal text from the MACRO. The process_simple method will also return this value.
You can also use the item, list, and hash return vmethods.
[% RETURN %] # just exits
[% RETURN "foo" %] # return value is foo
[% "foo".return %] # same thing
[% SET a = 1 %][% a %] => "1"
[% a = 1 %][% a %] => "1"
[% b = 1 %][% SET a = b %][% a %] => "1"
[% a = 1 %][% SET a %][% a %] => ""
[% SET a = [1, 2, 3] %][% a.1 %] => "2"
[% SET a = {b => 'c'} %][% a.b %] => "c"
[% a = "hi" %]
[% b = "bar" %]
[% SWITCH a %]
[% CASE "foo" %]a was foo
[% CASE b %]a was bar
[% CASE ["hi", "hello"] %]You said hi or hello
[% CASE DEFAULT %]I don't know what you said
[% END %]
Would print:
You said hi or hello
[% TAGS html %]
[% TAGS <!-- --> %]
The named tags are (duplicated from TT):
asp => ['<%', '%>' ], # ASP
default => ['\[%', '%\]' ], # default
html => ['<!--', '-->' ], # HTML comments
mason => ['<%', '>' ], # HTML::Mason
metatext => ['%%', '%%' ], # Text::MetaText
php => ['<\?', '\?>' ], # PHP
star => ['\[\*', '\*\]' ], # TT alternate
template => ['\[%', '%\]' ], # Normal Template Toolkit
template1 => ['[\[%]%', '%[%\]]'], # allow TT1 style
tt2 => ['\[%', '%\]' ], # TT2
If custom tags are supplied, by default they are escaped using quotemeta. You may also pass explicitly quoted strings, or regular expressions as arguments as well (if your regex begins with a ', ", or / you must quote it.
[% TAGS [<] [>] %] matches "[<] tag [>]"
[% TAGS '[<]' '[>]' %] matches "[<] tag [>]"
[% TAGS "[<]" "[>]" %] matches "[<] tag [>]"
[% TAGS /[<]/ /[>]/ %] matches "< tag >"
[% TAGS ** ** %] matches "** tag **"
[% TAGS /**/ /**/ %] Throws an exception.
You should be sure that the start tag does not include grouping parens or INTERPOLATE will not function properly.
[% THROW mytypes.sometime 'Something happened' arg1 => val1 %]
See the TRY directive for examples of usage.
Note: Parse errors cannot be caught unless they are in an eval FILTER, or are in a separate template being INCLUDEd or PROCESSed.
[% TRY %]
Nothing bad happened.
[% CATCH %]
Caught the error.
[% FINAL %]
This section runs no matter what happens.
[% END %]
Would print:
Nothing bad happened.
This section runs no matter what happens.
Another example:
[% TRY %]
[% THROW "Something happened" %]
[% CATCH %]
Error: [% error %]
Error.type: [% error.type %]
Error.info: [% error.info %]
[% FINAL %]
This section runs no matter what happens.
[% END %]
Would print:
Error: undef error - Something happened
Error.type: undef
Error.info: Something happened
This section runs no matter what happens.
You can give the error a type and more information including named arguments. This information replaces the "info" property of the exception.
[% TRY %]
[% THROW foo.bar "Something happened" "grrrr" foo => 'bar' %]
[% CATCH %]
Error: [% error %]
Error.type: [% error.type %]
Error.info: [% error.info %]
Error.info.0: [% error.info.0 %]
Error.info.1: [% error.info.1 %]
Error.info.args.0: [% error.info.args.0 %]
Error.info.foo: [% error.info.foo %]
[% END %]
Would print something like:
Error: foo.bar error - HASH(0x82a395c)
Error.type: foo.bar
Error.info: HASH(0x82a395c)
Error.info.0: Something happened
Error.info.1: grrrr
Error.info.args.0: Something happened
Error.info.foo: bar
You can also give the CATCH block a type to catch. And you can nest TRY blocks. If types are specified, Alloy will try and find the closest matching type. Also, an error object can be re-thrown using $error as the argument to THROW.
[% TRY %]
[% TRY %]
[% THROW foo.bar "Something happened" %]
[% CATCH bar %]
Caught bar.
[% CATCH DEFAULT %]
Caught default - but re-threw.
[% THROW $error %]
[% END %]
[% CATCH foo %]
Caught foo.
[% CATCH foo.bar %]
Caught foo.bar.
[% CATCH %]
Caught anything else.
[% END %]
Would print:
Caught default - but re-threw.
Caught foo.bar.
[% UNLESS 0 %]hi[% END %] => hi
Can also be a post operative directive.
[% USE iter = Iterator(['foo', 'bar']) %]
[%~ iter.get_first %]
[% iter.size %]
Would print:
foo
2
Note that it is possible to send arguments to the new object constructor. It is also possible to omit the variable name being assigned. In that case the name of the plugin becomes the variable.
[% USE Iterator(['foo', 'bar', 'baz']) %]
[%~ Iterator.get_first %]
[% Iterator.size %]
Would print:
foo
3
Plugins that are loaded are looked up for in the namespace listed in the PLUGIN_BASE directive which defaults to Template::Plugin. So in the previous example, if Template::Toolkit was installed, the iter object would loaded by the class Template::Plugin::Iterator. In Alloy, an effective way to disable plugins is to set the PLUGIN_BASE to a non-existent base such as "_" (In TT it will still fall back to look in Template::Plugin).
Note: The iterator plugin will fall back and use Template::Alloy::Iterator if Template::Toolkit is not installed. No other plugins come installed with Template::Alloy.
The names of the Plugin being loaded from PLUGIN_BASE are case insensitive. However, using case insensitive names is bad as it requires scanning the @INC directories for any module matching the PLUGIN_BASE and caching the result (OK - not that bad).
If the plugin is not found and the LOAD_PERL directive is set, then Alloy will try and load a module by that name (note: this type of lookup is case sensitive and will not scan the @INC dirs for a matching file).
# The LOAD_PERL directive should be set to 1
[% USE ta = Template::Alloy %]
[%~ ta.dump_parse_expr('2 * 3') %]
Would print:
[[undef, '*', 2, 3], 0];
See the PLUGIN_BASE, and PLUGINS configuration items.
See the documentation for Template::Manual::Plugins.
[% WHILE i < 3 %]
[%~ i = i + 1 %]
i = [% i %]
[%~ END %]
Would print:
i = 1
i = 2
i = 3
You could also do:
[% i = 4 %]
[% WHILE (i = i - 1) %]
i = [% i %]
[%~ END %]
Would print:
i = 3
i = 2
i = 1
Note that (f = f - 1) is a valid expression that returns the value of the assignment. The parenthesis are not optional.
WHILE has a built in limit of 1000 iterations. This is controlled by the global variable $WHILE_MAX in Template::Alloy.
WHILE may also be used as a post operative directive.
[% "$i" WHILE (i = i + 1) < 7 %] => 123456
[% WRAPPER foo b = 23 %]
My content to be processed ([% b %]).[% a = 2 %]
[% END %]
[% BLOCK foo %]
A header ([% a %]).
[% content %]
A footer ([% a %]).
[% END %]
This would print.
A header (2).
My content to be processed (23).
A footer (2).
The WRAPPER directive may also be used as a post operative directive.
[% BLOCK baz %]([% content %])[% END -%]
[% "foobar" WRAPPER baz %]
Would print
(foobar)');
Multiple filenames can be passed by separating them with a plus, a space, or commas (TT2 doesn't support the comma). Any supplied arguments will be used on all templates. Wrappers are processed in reverse order, so that the first wrapper listed will surround each subsequent wrapper listed. Variables from inner wrappers are available to the next wrapper that surrounds it.
[% WRAPPER "path/to/outer.html",
"path/to/inner.html" a = "An arg" b = "Another arg" %]
HTML::Template templates use directives that look similar to the following:
<TMPL_VAR NAME="foo">
<TMPL_IF NAME="bar">
BAR
</TMPL_IF>
The normal set of HTML::Template directives are TMPL_VAR, TMPL_IF, TMPL_ELSE, TMPL_UNLESS, TMPL_INCLUDE, and TMPL_LOOP. These tags should have either a NAME attribute, an EXPR attribute, or a bare variable name that is used to specify the value to be operated. If a NAME is specified, it may only be a single level value (as opposed to a TT chained variable). In the case of the TMPL_INCLUDE directive, the NAME is the file to be included.
In Alloy, the EXPR attribute can be used with any of these types to specify TT compatible variable or expression that will be used for the value.
<TMPL_VAR NAME="foo"> Prints the value contained in foo
<TMPL_VAR foo> Prints the value contained in foo
<TMPL_VAR EXPR="foo"> Prints the value contained in foo
<TMPL_VAR NAME="foo.bar.baz"> Prints the value contained in {'foo.bar.baz'}
<TMPL_VAR EXPR="foo.bar.baz"> Prints the value contained in {foo}->{bar}->{baz}
<TMPL_IF foo> Prints FOO if foo is true
FOO
</TMPL_IF
<TMPL_UNLESS foo> Prints FOO unless foo is true
FOO
</TMPL_UNLESS
<TMPL_INCLUDE NAME="foo.ht"> Includes the template in "foo.ht"
<TMPL_LOOP foo> Iterates on the arrayref foo
<TMPL_VAR name>
</TMPL_LOOP>
Template::Alloy makes all of the other TT3 directives available in addition to the normal set of HTML::Template directives. For example, the following is valid in Alloy.
<TMPL_MACRO bar(n) BLOCK>You said <TMPL_VAR n></TMPL_MACRO>
<TMPL_GET bar("hello")>
The TMPL_VAR tag may also include an optional ESCAPE attribute. This specifies how the value of the tag should be escaped prior to substituting into the template.
Escape value | Type of escape
---------------------------------
HTML, 1 | HTML encoding
URL | URL encoding
JS | basic javascript encoding (\n, \r, and \")
NONE, 0 | No encoding (default).
The TMPL_VAR tag may also include an optional DEFAULT attribute that contains a string that will be used if the variable returns false.
<TMPL_VAR foo DEFAULT="Foo was false">
Chomping refers to the handling of whitespace immediately before and immediately after template tags. By default, nothing happens to this whitespace. Modifiers can be placed just inside the opening and just before the closing tags to control this behavior.
Additionally, the PRE_CHOMP and POST_CHOMP configuration variables can be set and will globally control all chomping behavior for tags that do not have their own chomp modifier. PRE_CHOMP and POST_CHOMP can be set to any of the following values:
none: 0 + Template::Constants::CHOMP_NONE
one: 1 - Template::Constants::CHOMP_ONE
collapse: 2 = Template::Constants::CHOMP_COLLAPSE
greedy: 3 ~ Template::Constants::CHOMP_GREEDY
Hello.
[%+ "Hi." +%]
Howdy.
Would print:
Hello.
Hi.
Howdy.
Hello.
[%- "Hi." -%]
Howdy.
Would print:
Hello.
Hi.
Howdy.
Hello.
[%= "Hi." =%]
Howdy.
Would print:
Hello. Hi. Howdy.
Hello.
[%~ "Hi." ~%]
Howdy.
Would print:
Hello.Hi.Howdy.
The following configuration variables are supported (in alphabetical order). Note: for further discussion you can refer to the TT config documentation.
Items may be passed in upper or lower case. If lower case names are passed they will be resolved to uppercase during the "new" method.
All of the variables in this section can be passed to the "new" constructor.
my $obj = Template::Alloy->new(
VARIABLES => \%hash_of_variables,
AUTO_RESET => 0,
TRIM => 1,
POST_CHOMP => "=",
PRE_CHOMP => "-",
);
This property may also be set in the template using the CONFIG directive.
[% CONFIG ADD_LOCAL_PATH => 1 %]
[% get 23 %] prints 23 with ANYCASE => 1
# with AUTO_FILTER => 'html'
[% f = "&"; GET f %] prints &
[% f = "&"; f %] prints & (implicit GET)
If a variable already has another filter applied the AUTO_FILTER is not applied. The "none" scalar virtual method has been added to allow for using variables without reapplying filters.
# with AUTO_FILTER => 'html'
[% f = "&"; f | none %] prints &
[% f = "&"; g = f; g %] prints &
[% f = "&"; g = f; g | none %] prints & (because g = f is a SET directive)
[% f = "&"; g = GET f; g | none %] prints & (because the actual GET directive was called)
A hashref of blocks that can be used by the process method.
BLOCKS => {
block_1 => sub { ... }, # coderef that returns a block
block_2 => 'A String', # simple string
},
Note that a Template::Document cannot be supplied as a value (TT supports this). However, it is possible to supply a value that is equal to the hashref returned by the load_template method.
The following table shows the relationship between the various contexts:
return values smart context list context item context
------------- ------------- ------------ ------------
A 'foo' 'foo' ['foo'] 'foo'
B undef undef [undef] undef
C (no return value) undef [] undef
D (7) 7 [7] 7
E (7,8,9) [7,8,9] [7,8,9] 9
F @a = (7) 7 [7] 1
G @a = (7,8,9) [7,8,9] [7,8,9] 3
H ({b=>"c"}) {b=>"c"} [{b=>"c"}] {b=>"c"}
I ([1]) [1] [[1]] [1]
J ([1],[2]) [[1],[2]] [[1],[2]] [2]
K [7,8,9] [7,8,9] [[7,8,9]] [7,8,9]
L (undef, "foo") die "foo" [undef, "foo"] "foo"
M wantarray?1:0 1 [1] 0
Cases F, H, I and M are common sticking points of the smart context in TT2. Note that list context always returns an arrayref from a method or function call. Smart context can give confusing results sometimes, especially the I and J cases. Case L for smart match is very surprising.
The list and item context provide another feature for method calls. In smart context, TT will look for a hash key in the object by the same name as the method, if a method by that name doesn't exist. In item and list context Alloy will die if a method by that name cannot be found.
The CALL_CONTEXT configuration item can be passed to new or it may also be set during runtime using the CONFIG directive. The following method call would be in list context:
[% CONFIG CALL_CONTEXT => 'list';
results = my_obj.get_results;
CONFIG CALL_CONTEXT => 'smart'
%]
Note that we needed to restore CALL_CONTEXT to the default 'smart' value. Template::Alloy has added the "@()" (list) and the "$()" (item) context specifiers. The previous example could be written as:
[% results = @( my_obj.get_results ) %]
To call that same method in item (scalar) context you would do the following:
[% results = $( my_obj.get_results ) %]
The "@()" and "$()" operators are based on the Perl 6 counterpart.
If set, the AST of parsed documents will be cached. If COMPILE_PERL is set, the compiled perl code will also be stored.
If set, the AST of parsed documents will be cached. If COMPILE_PERL is set, the compiled perl code will also be stored.
Requires installation of Template::Alloy::JS. When enabled, the parsed templates will be translated into Javascript and executed using the V8 javascript engine. If compile_dir is also set, this compiled javascript will be cached to disk.
If your templates are short, there is little benefit to using this other than you can then use the JS directive. If your templates are long or you are running in a cached environment, this will speed up your templates.
Certain limitations exist when COMPILE_JS is set, most notably the USE and VIEW directives are not supported, and method calls on objects passed to the template do not work (code refs passed in do work however). These limitations are due to the nature of JavaScript::V8 bind and Perl/JavaScript OO differences.
If set to 1 or 2, will translate the normal AST into a perl 5 code document. This document can then be executed directly, cached in memory, or cached on the file system depending upon the configuration items set.
If set to 1, a perl code document will always be generated.
If set to 2, a perl code document will only be generated if an AST has already been cached for the document. This should give a speed benefit and avoid extra compilation unless the document has been used more than once.
If Alloy is running in a cached environment such as mod_perl, then using compile_perl can offer some speed benefit and makes Alloy faster than Text::Tmpl and as fast as HTML::Template::Compiled (but Alloy has more features).
If you are not running in a cached environment, such as from commandline, or from CGI, it is generally faster to only run from the AST (with COMPILE_PERL => 0).
CONSTANTS => {my_constant => 42},
A template containing:
[% constants.my_constant %]
Will have the value 42 compiled in.
Constants defined in this way can be chained as in [% constant.foo.bar.baz %].
The only supported TT values are:
DEBUG_UNDEF (2) - debug when an undefined value is used (now easier to use STRICT)
DEBUG_DIRS (8) - debug when a directive is used.
DEBUG_ALL (2047) - turn on all debugging.
Either of the following would turn on undef and directive debugging:
DEBUG => 'undef, dirs', # preferred
DEBUG => 2 | 8,
DEBUG => DEBUG_UNDEF | DEBUG_DIRS, # constants from Template::Constants
If set to 0, all DUMP directives will do nothing. This is useful if you would like to turn off the DUMP directives under some environments.
IF set to a true value (or undefined) then DUMP directives will operate.
If set to a hashref, the values of the hash can be used to configure the operation of the DUMP directives. The following are the values that can be set in this hash.
Note 1: The default handler makes sure that values matching the private variable regex are not included. If you install your own handler, you will need to take care of these variables if you intend for them to not be shown.
Note 2: If you would like the name of the variable to be dumped, include the string '$VAR1' and the DUMP directive will interpolate the value. For example, to dump all output as YAML - you could do the following:
DUMP => {
handler => sub {
require YAML;
return "\$VAR1 =\n".YAML::Dump(shift);
},
}
This item can also be set using [% CONFIG ENCODING => encoding %] before calling INCLUDE or PROCESS directives to change encodings on the fly.
my $t = Template::Alloy->new({
ERROR => 'general/catch_all_errors.html',
});
my $t = Template::Alloy->new({
ERROR => {
default => 'general/catch_all_errors.html',
foo => 'catch_all_general_foo_errors.html',
'foo.bar' => 'catch_foo_bar_errors.html',
},
});
Note that the ERROR handler will only be used for errors during the processing of the main document. It will not catch errors that occur in templates found in the PRE_PROCESS, POST_PROCESS, and WRAPPER configuration items.
my $filters = {
filter1 => sub { my $str = shift; $s =~ s/./1/gs; $s },
filter2 => [sub { my $str = shift; $s =~ s/./2/gs; $s }, 0],
filter3 => [sub { my ($context, @args) = @_; return sub { my $s = shift; $s =~ s/./3/gs; $s } }, 1],
};
my $str = q{
[% a = "Hello" %]
1 ([% a | filter1 %])
2 ([% a | filter2 %])
3 ([% a | filter3 %])
};
my $obj = Template::Alloy->new(FILTERS => $filters);
$obj->process(\$str) || die $obj->error;
Would print:
1 (11111)
2 (22222)
3 (33333)
Filters passed in as an arrayref should contain a coderef and a value indicating if they are dynamic or static (true meaning dynamic). The dynamic filters are passed the pseudo context object and any arguments and should return a coderef that will be called as the filter. The filter coderef is then passed the string.
The TT, Tmpl, and velocity will automatically cache documents in the object. The HTML::Template interface uses a new object each time. Setting the HTML::Template's CACHE configuration is the same as setting GLOBAL_CACHE.
[% IF 1 %]The variable $variable had a value ${var.value}[% END %]
[% f = "[% f|eval %]" %][% f|eval %]
[% MACRO f BLOCK %][% f %][% END %][% f %]
Template::Alloy->new(NAMESPACE => {constants => {
foo => 'bar',
}});
Is the same as
Template::Alloy->new(CONSTANTS => {
foo => 'bar',
});
Any number of hashes can be added to the NAMESPACE hash.
Similar to STAT_TTL - but represents the time-to-live seconds until a document that was not found is checked again against the system for modifications. Setting this number higher will allow for fewer file system accesses. Setting it to a negative number will allow for the file system to be checked every hit.
See the process method for a listing of possible values.
PLUGINS => {
Iterator => 'Template::Plugin::Iterator',
DBI => 'MyDBI',
},
See the USE directive for more information.
A list of templates to be processed and appended to the content after the main template. During this processing the "template" namespace will contain the name of the main file being processed.
This is useful for adding a global footer to all templates.
A list of templates to be processed before and pre-pended to the content before the main template. During this processing the "template" namespace will contain the name of the main file being processed.
This is useful for adding a global header to all templates.
Specify a file to use as the template rather than the one passed in to the ->process method.
[% CONFIG INTERPOLATE => 1 %]
[% SET foo = 1 %][% SET bar %]
($foo)($bar) ($!foo)($!bar)
Would print:
(1)() (1)()
But the following:
[% CONFIG INTERPOLATE => 1, SHOW_UNDEFINED_INTERP => 1 %]
[% SET foo = 1 %][% SET bar %]
($foo)($bar) ($!foo)($!bar)
Would print:
(1)($bar) (1)()
Note that you can use an exclamation point directly after the dollar to make the variable silent. This is similar to how Velocity works.
The Stream role uses the Play role's directives (non-compiled_perl).
All directives and configuration work, except for the following exceptions:
All output is printed directly to the currently selected filehandle (defaults to STDOUT) via the CORE::print function. Any output parameter passed to process or process_simple will be ignored.
If you would like the output to go to another handle, you will need to select that handle, process the template, and re-select STDOUT.
When this occurs the strict_throw method is called.
See the STRICT_THROW configuration for additional options.
Similar functionality could be implemented using UNDEFINED_ANY.
The STRICT configuration item can be passed to new or it may also be set during runtime using the CONFIG directive. Once set though it cannot be disabled for the duration of the current template and sub components. For example you could call [% CONFIG STRICT => 1 %] in header.tt and strict mode would be enabled for the header.tt and any sub templates processed by header.tt.
my $ta = Template::Alloy->new({
STRICT => 1,
STRICT_THROW => sub {
my ($ta, $err_type, $msg, $args) = @_;
return if $args->{'component'} eq 'header.tt'
&& $args->{'template'} eq 'main.html'
&& $args->{'name'} eq 'foo.bar(1)'; # stringified identity name
$ta->throw($err_type, $msg); # all other undefined variables die
},
});
The syntax may be passed in upper or lower case.
The available choices are:
alloy - Template::Alloy style - the same as TT3
tt3 - Template::Toolkit ver3 - same as Alloy
tt2 - Template::Toolkit ver2 - almost the same as TT3
tt1 - Template::Toolkit ver1 - almost the same as TT2
ht - HTML::Template - same as HTML::Template::Expr without EXPR
hte - HTML::Template::Expr
js - JavaScript style - requires compile_js to be set.
jsr - JavaScript Raw style - requires compile_js to be set.
Passing in a different syntax allows for the process method to use a non-TT syntax and for the output method to use a non-HT syntax.
The following is a sample of HTML::Template interface usage parsing a Template::Toolkit style document.
my $obj = Template::Alloy->new(filename => 'my/template.tt'
syntax => 'cet');
$obj->param(\%swap);
print $obj->output;
The following is a sample of Template::Toolkit interface usage parsing a HTML::Template::Expr style document.
my $obj = Template::Alloy->new(SYNTAX => 'hte');
$obj->process('my/template.ht', \%swap);
You can use the define_syntax method to add another custom syntax to the list of available options.
You can also sub class the module and override the undefined_any method.
You can also sub class the module and override the undefined_get method.
With V1DOLLAR Equivalent Without V1DOLLAR (Normal default)
"[% foo %]" "[% foo %]"
"[% $foo %]" "[% foo %]"
"[% ${foo} %]" "[% ${foo} %]"
"[% foo.$bar %]" "[% foo.bar %]"
"[% ${foo.bar} %]" "[% ${foo.bar} %]"
"[% ${foo.$bar} %]" "[% ${foo.bar} %]"
"Text: $foo" "Text: $foo"
"Text: ${foo}" "Text: ${foo}"
"Text: ${$foo}" "Text: ${foo}"
If set to 1 then "==" is an alias for "eq" and "!= is an alias for "ne".
[% CONFIG V2EQUALS => 1 %][% ('7' == '7.0') || 0 %]
[% CONFIG V2EQUALS => 0 %][% ('7' == '7.0') || 0 %]
Prints
0
1
With V2PIPE = 1
[%- BLOCK a %]b is [% b %]
[% END %]
[%- PROCESS a b => 237 | repeat(2) %]
# output of block "a" with b set to 237 is passed to the repeat(2) filter
b is 237
b is 237
With V2PIPE = 0 (default)
[%- BLOCK a %]b is [% b %]
[% END %]
[% PROCESS a b => 237 | repeat(2) %]
# b set to 237 repeated twice, and b passed to block "a"
b is 237237
[% "abc".length %]
[% length("abc") %]
You may set VMETHOD_FUNCTIONS to 0 to disable this behavior.
Operates similar to the WRAPPER directive. The option can be given a single filename, or an arrayref of filenames that will be used to wrap the processed content. If an arrayref is passed the filenames are processed in reverse order, so that the first filename specified will end up being on the outside (surrounding all other wrappers).
my $t = Template::Alloy->new(
WRAPPER => ['my/wrappers/outer.html', 'my/wrappers/inner.html'],
);
Content generated by the PRE_PROCESS and POST_PROCESS will come before and after (respectively) the content generated by the WRAPPER configuration item.
See the WRAPPER directive for more examples of how wrappers are constructed.
The following HTML::Template and HTML::Template::Expr configuration variables are supported (in HTML::Template documentation order). Note: for further discussion you can refer to the HT documentation. Many of the variables mentioned in the TT CONFIGURATION section apply here as well. Unless noted, these items only apply when using the output method.
Items may be passed in upper or lower case. All passed items are resolved to upper case.
These variables should be passed to the "new" constructor.
my $obj = Template::Alloy->new(
type => 'filename',
source => 'my/template.ht',
die_on_bad_params => 1,
loop_context_vars => 1,
global_vars => 1
post_chomp => "=",
pre_chomp => "-",
);
Must be set to enable caching.
Will not be cached.
Will not be cached.
Will not be cached.
__first__ - True on first iteration only
__last__ - True on last iteration only
__inner__ - True on any iteration that isn't first or last
__odd__ - True on odd iterations
__counter__ - The iteration count
These variables are also available to LOOPs run under TT syntax if loop_context_vars is set and if QR_PRIVATE is set to 0.
You may alternately use the AUTO_FILTER directive which can be any of the item vmethod filters (you must use lower case when specifying the AUTO_FILTER directive). The AUTO_FILTER directive will also be applied to TMPL_VAR EXPR and TMPL_GET items while DEFAULT_ESCAPE only applies to TMPL_VAR NAME items.
The output method uses 'hte' syntax by default.
The following list of methods are other interesting methods of Alloy that may be re-implemented by subclasses of Alloy.
my $doc = $self->load_template($file); # errors die
This method handles the in-memory caching of the document.
Given the "document" hashref, will either load the compiled perl from file (if configured to do so), or will load the AST using "load_tree", will compile a new perl code document using the Compile role, and will return the perl code. File based caching of the compiled perl happens here.
See Template::Alloy::Parse for more details.
See Template::Alloy::Parse for more details.
The following is a brief list of other methods used by Alloy. Generally, these shouldn't be overwritten by subclasses.
See Template::Alloy::Operator for more details.
Thanks to Andy Wardley for creating Template::Toolkit.
Thanks to Sam Tregar for creating HTML::Template.
Thanks to David Lowe for creating Text::Tmpl.
Thanks to the Apache Velocity guys.
Thanks to Ben Grimm for a patch to allow passing a parsed document to the ->process method.
Thanks to David Warring for finding a parse error in HTE syntax.
Thanks to Carl Franks for adding the base ENCODING support.
Paul Seamons <paul@seamons.com>
This module may be distributed under the same terms as Perl itself.
| 2022-10-16 | perl v5.36.0 |