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.

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.

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.

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:

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.

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.

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.

HTML::Template way to process a template. The output method requires that a filename, filehandle, scalarref, or arrayref argument was passed to the new method. All of the HT calling conventions for new are supported. The key difference is that Alloy will not actually process the template until the output method is called.

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.

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.

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 "}".

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.

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.

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.

[% 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

Clears any of the content currently generated in the innermost block or template. This can be useful when used in conjunction with the TRY statement to clear generated content if an error occurs later.

Introduced by the Velocity templating language. Parses and processes the contents of the passed item. This is similar to the eval filter, but Velocity needs a directive. Named arguments may be used for re-configuring the parser. Any of the items that can be passed to the CONFIG directive may be passed here.

Used to apply different treatments to blocks of text. It may operate as a BLOCK directive or as a post operative directive. Alloy supports all of the filters in Template::Filters. The lines between scalar virtual methods and filters is blurred (or non-existent) in Alloy. Anything that is a scalar virtual method may be used as a FILTER.

Alias for the FILTER directive. Note that | is similar to the '.' in Template::Alloy. Therefore a pipe cannot be used directly after a variable name in some situations (the pipe will act only on that variable). This is the behavior employed by TT3. To get the TT2 behavior for a PIPE, use the V2PIPE configuration item.

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.

Allows for conditional testing. Expects an expression as its only argument. If the expression is true, the contents of its block are processed. If false, the processor looks for an ELSIF block. If an ELSIF's expression is true then it is processed. Finally it looks for an ELSE block which is processed if none of the IF or ELSIF's expressions were true.

This directive operates similar to the HTML::Template loop directive. The LOOP directive expects a single variable name. This variable name should point to an arrayref of hashrefs. The keys of each hashref will be added to the variable stash when it is iterated.

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.

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.

Parse the contents of a file or block and insert them. Unlike INCLUDE, no variable localization happens so variables defined or modifications made to existing variables remain after the template is processed.

Used to exit the innermost block or template and continue processing in the surrounding block or template.

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.

Change the type of enclosing braces used to delineate template tags. This remains in effect until the end of the enclosing block or template or until the next TAGS directive. Either a named set of tags must be supplied, or two tags themselves must be supplied.

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.

The TRY block directive will catch exceptions that are thrown while processing its block (It cannot catch parse errors unless they are in included files or evaltt'ed strings. The TRY block will then look for a CATCH block that will be processed. While it is being processed, the "error" variable will be set with the thrown exception as the value. After the TRY block - the FINAL block will be ran whether or not an error was thrown (unless a CATCH block throws an error).

Note: Parse errors cannot be caught unless they are in an eval FILTER, or are in a separate template being INCLUDEd or PROCESSed.

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.

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') %]

Implement a TT style view. For more information, please see the Template::View documentation. This DIRECTIVE will correctly parse the arguments and then pass them along to a newly created Template::View object. It will fail if Template::View can not be found.

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.

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.

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:

If true, allows calls include_filename to temporarily add the directory of the current template being processed to the INCLUDE_PATHS arrayref. This allows templates to refer to files in the local template directory without specifying the local directory as part of the filename. Default is 0. If set to a negative value, the current directory will be added to the end of the current INCLUDE_PATHS.

This property may also be set in the template using the CONFIG directive.

Boolean. Default 0 (default 1 in Velocity syntax). If set to true, double quoted strings will automatically be passed to the eval filter. This configuration option may also be passed to the CONFIG directive.

Can be the name of any filter. Default undef. Any variable returned by a GET directive (including implicit GET) will be passed to the named filter. This configuration option may also be passed to the CONFIG directive.

Number of compiled templates to keep in memory. Default undef. Undefined means to allow all templates to cache. A value of 0 will force no caching. The cache mechanism will clear templates that have not been used recently.

Default 1. If set, any string refs will have an MD5 sum taken that will then be used for caching the document - both in memory and on the file system (if configured). This will give a significant speed boost. Note that this affects strings passed to the EVALUATE directive or eval filters as well. It may be set using the CONFIG directive.

Can be one of 'item', 'list', or 'smart'. The default type is 'smart'. The CALL_CONTEXT configuration specifies in what Perl context coderefs and methods used in the processed templates will be called. TT historically has avoided the distinction of item (scalar) vs list context. To avoid worrying about this, TT introduced 'smart' context. The @() and $() context specifiers make it easier to use CALL_CONTEXT in some situations.

The following table shows the relationship between the various contexts:

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:

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).

Defaults to an internal coderef. If set to a coderef, the DUMP directive will pass the arguments to be dumped and expects a string with the dumped data. This gives complete control over the dump process.

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:

Defaults to 1 if $ENV{'REQUEST_METHOD'} is set - 0 otherwise. If set to 1, then the output of the DUMP directive is passed to the html filter and encased in "pre" tags. If set to 0 no html encoding takes place.

Default undef. If set, and if Perl version is greater than or equal to 5.7.3 (when Encode.pm was first included), then Encode::decode will be called every time a template file is processed and will be passed the value of ENCODING and text from the template.

This item can also be set using [% CONFIG ENCODING => encoding %] before calling INCLUDE or PROCESS directives to change encodings on the fly.

Used as a fall back when the processing of a template fails. May either be a single filename that will be used in all cases, or may be a hashref of options where the keynames represent error types that will be handled by the filename in their value. A key named default will be used if no other matching keyname can be found. The selection process is similar to that of the TRY/CATCH/THROW directives (see those directives for more information).

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.

Boolean. Default false. If set to a true value, PERL and RAWPERL blocks will be allowed to run. This is a potential security hole, as arbitrary perl can be included in the template. If Template::Toolkit is installed, a true EVAL_PERL value also allows the perl and evalperl filters to be used.

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.

Default 0. If true, documents will be cached in $Template::Alloy::GLOBAL_CACHE. It may also be passed a hashref, in which case the documents will be cached in the passed hashref.

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.

Boolean. Specifies whether variables in text portions of the template will be interpolated. For example, the $variable and ${var.value} would be substituted with the appropriate values from the variable cache (if INTERPOLATE is on).

Indicates if the USE directive can fall back and try and load a perl module if the indicated module was not found in the PLUGIN_BASE path. See the USE directive. This configuration has no bearing on the COMPILE_PERL directive used to indicate using compiled perl documents.

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.

Default value is Template::Plugin. The base module namespace that template plugins will be looked for. See the USE directive for more information. May be either a single namespace, or an arrayref of namespaces.

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.

Boolean. Default false. If true, then the syntax will require that semi-colons separate multiple directives in the same tag. This is useful for keeping the syntax a little more clean as well as trouble shooting some errors.

Template::Alloy manages its own stash of variables. You can pass a Template::Stash or Template::Stash::XS object, but Template::Alloy will copy all of values out of the object into its own stash. Template::Alloy won't use any of the methods of the passed STASH object. The STASH option is only available when using the process method.

Defaults to $STAT_TTL which defaults to 1. Represents time-to-live seconds until a cached in memory document is compared to the file 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.

Defaults to false. If set to true, generated template content will be printed to the currently selected filehandle (default is STDOUT) as soon as it is ready - there will be no buffering of the output.

The Stream role uses the Play role's directives (non-compiled_perl).

All directives and configuration work, except for the following exceptions:

The WRAPPER configuration and directive items effectively turn off STREAM since the WRAPPERS are generated in reverse order and because the content is inserted into the middle of the WRAPPERS. WRAPPERS will still work, they just won't stream.

Defaults to false. If set to true, any undefined variable that is encountered will cause the processing of the template to abort. This can be caught with a TRY block. This can be useful for making sure that the template only attempts to use variables that were correctly initialized similar in spirit to Perl's "use strict."

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.

Default undef. Can be set to a subroutine which will be called when STRICT is set and an undefined variable is processed. It will be passed the error type, error message, and a hashref of template information containing the current component being processed, the current outer template being processed, the identity reference for the variable, and the stringified name of the identity. This override can be used for filtering allowable elements.

Defaults to "cet". Indicates the syntax that will be used for parsing included templates or eval'ed strings. You can use the CONFIG directive to change the SYNTAX on the fly (it will not affect the syntax of the document currently being parsed).

This is not a TT configuration option. This option expects to be a code ref that will be called if a variable is undefined during a call to play_expr. It is passed the variable identity array as a single argument. This is most similar to the "undefined" method of Template::Stash. It allows for the "auto-defining" of a variable for use in the template. It is suggested that UNDEFINED_GET be used instead as UNDEFINED_ANY is a little to general in defining variables.

You can also sub class the module and override the undefined_any method.

This is not a TT configuration option. This option expects to be a code ref that will be called if a variable is undefined during a call to GET. It is passed the variable identity array as a single argument. This is more useful than UNDEFINED_ANY in that it is only called during a GET directive rather than in embedded expressions (such as [% a || b || c %]).

You can also sub class the module and override the undefined_get method.

This allows for some compatibility with TT1 templates. The only real behavior change is that [% $foo %] becomes the same as [% foo %]. The following is a basic table of changes invoked by using V1DOLLAR.

A hashref of variables to initialize the template stash with. These variables are available for use in any of the executed templates. See the section on VARIABLES for the types of information that can be passed in.

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).

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.

If set to one, then Alloy will use a global, in-memory document cache to store compiled templates in between calls. This is generally only useful in a mod_perl environment. The document is checked for a different modification time at each request.

Default false. When true, calls to the loop directive will create the following variables that give information about the current iteration of the loop:

__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.

Controls the type of escape used on named variables in TMPL_VAR directives. Can be one of HTML, URL, or JS. The values of TMPL_VAR directives will be encoded with this type unless they specify their own type via an ESCAPE attribute.

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.

Play the parsed expression. Turns a variable identity array into the parsed variable. This method is also responsible for playing operators and running virtual methods and filters. The variable identity array may also contain literal values, or operator identity arrays.

Given the "document" hashref, will either load the parsed AST from file (if configured to do so), or will load the content, parse the content using the Parse role, and will return the tree. File based caching of the parsed AST happens here.

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.

Called during processing of template when STRICT configuration is set and an uninitialized variable is met. Arguments are the variable identity reference. Will call STRICT_THROW configuration item if set, otherwise will call throw with a useful message.

Called during play_expr if a value is returned that is undefined. This could be used to magically create variables on the fly. This is similar to Template::Stash::undefined. It is suggested that undefined_get be used instead. Default behavior returns undef. You may also pass a coderef via the UNDEFINED_ANY configuration variable. Also, you can try using the DEBUG => 'undef', configuration option which will throw an error on undefined variables.

Called when a variable is undefined during a GET directive. This is useful to see if a value that is about to get inserted into the text is undefined. undefined_any is a little too general for most cases. Also, you may pass a coderef via the UNDEFINED_GET configuration variable.