.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Template::Alloy 3pm" .TH Template::Alloy 3pm "2013-08-23" "perl v5.18.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Template::Alloy \- TT2/3, HT, HTE, Tmpl, and Velocity Engine .SH "SYNOPSIS" .IX Header "SYNOPSIS" .SS "Template::Toolkit style usage" .IX Subsection "Template::Toolkit style usage" .Vb 3 \& my $t = Template::Alloy\->new( \& INCLUDE_PATH => [\*(Aq/path/to/templates\*(Aq], \& ); \& \& my $swap = { \& key1 => \*(Aqval1\*(Aq, \& key2 => \*(Aqval2\*(Aq, \& code => sub { 42 }, \& hash => {a => \*(Aqb\*(Aq}, \& }; \& \& # print to STDOUT \& $t\->process(\*(Aqmy/template.tt\*(Aq, $swap) \& || die $t\->error; \& \& # process into a variable \& my $out = \*(Aq\*(Aq; \& $t\->process(\*(Aqmy/template.tt\*(Aq, $swap, \e$out); \& \& ### Alloy uses the same syntax and configuration as Template::Toolkit .Ve .SS "HTML::Template::Expr style usage" .IX Subsection "HTML::Template::Expr style usage" .Vb 4 \& my $t = Template::Alloy\->new( \& filename => \*(Aqmy/template.ht\*(Aq, \& path => [\*(Aq/path/to/templates\*(Aq], \& ); \& \& my $swap = { \& key1 => \*(Aqval1\*(Aq, \& key2 => \*(Aqval2\*(Aq, \& code => sub { 42 }, \& hash => {a => \*(Aqb\*(Aq}, \& }; \& \& $t\->param($swap); \& \& # print to STDOUT (errors die) \& $t\->output(print_to => \e*STDOUT); \& \& # process into a variable \& my $out = $t\->output; \& \& ### Alloy can also use the same syntax and configuration as HTML::Template .Ve .SS "Text::Tmpl style usage" .IX Subsection "Text::Tmpl style usage" .Vb 1 \& my $t = Template::Alloy\->new; \& \& my $swap = { \& key1 => \*(Aqval1\*(Aq, \& key2 => \*(Aqval2\*(Aq, \& code => sub { 42 }, \& hash => {a => \*(Aqb\*(Aq}, \& }; \& \& $t\->set_delimiters(\*(Aq#[\*(Aq, \*(Aq]#\*(Aq); \& $t\->set_strip(0); \& $t\->set_values($swap); \& $t\->set_dir(\*(Aq/path/to/templates\*(Aq); \& \& my $out = $t\->parse_file(\*(Aqmy/template.tmpl\*(Aq); \& \& my $str = "Foo #[echo $key1]# Bar"; \& my $out = $t\->parse_string($str); \& \& \& ### Alloy uses the same syntax and configuration as Text::Tmpl .Ve .SS "Velocity (\s-1VTL\s0) style usage" .IX Subsection "Velocity (VTL) style usage" .Vb 1 \& my $t = Template::Alloy\->new; \& \& my $swap = { \& key1 => \*(Aqval1\*(Aq, \& key2 => \*(Aqval2\*(Aq, \& code => sub { 42 }, \& hash => {a => \*(Aqb\*(Aq}, \& }; \& \& my $out = $t\->merge(\*(Aqmy/template.vtl\*(Aq, $swap); \& \& my $str = "#set($foo 1 + 3) ($foo) ($bar) ($!baz)"; \& my $out = $t\->merge(\e$str, $swap); .Ve .SS "Javascript style usage (requires Template::Alloy::JS)" .IX Subsection "Javascript style usage (requires Template::Alloy::JS)" .Vb 1 \& my $t = Template::Alloy\->new; \& \& my $swap = { \& key1 => \*(Aqval1\*(Aq, \& key2 => \*(Aqval2\*(Aq, \& code => sub { 42 }, \& hash => {a => \*(Aqb\*(Aq}, \& }; \& \& my $out = \*(Aq\*(Aq; \& $t\->process_js(\*(Aqmy/template.jstem\*(Aq, $swap, \e$out); \& \& my $str = "[% var foo = 1 + 3; write(\*(Aq(\*(Aq + foo + \*(Aq) (\*(Aq + get(\*(Aqkey1\*(Aq) + \*(Aq)\*(Aq); %]"; \& my $out = \*(Aq\*(Aq; \& $t\->process_js(\e$str, $swap, \e$out); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\*(L"An alloy is a homogeneous mixture of two or more elements\*(R" (http://en.wikipedia.org/wiki/Alloy). .PP 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, \s-1CGI,\s0 or running from the commandline. There is even Template::Alloy::JS for getting a little more speed when that is necessary. .PP 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 \s-1TT2\s0 style variables in \s-1TT2\s0 style tags \*(L"[% foo.bar %]\*(R". 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 \s-1TT2\s0 as well as some from \s-1TT3. \s0 Template::Alloy now provides a full-featured implementation of the Template::Toolkit language. .PP 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 (\s-1VTL\s0) were added. All of the various engines offer the same features \- each using a different syntax and interface. .PP 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). .PP Template::Toolkit brought the most to the table. HTML::Template brought the \s-1LOOP\s0 directive. HTML::Template::Expr brought more vmethods and using vmethods as top level functions. Text::Tmpl brought the \&\s-1COMMENT\s0 directive and encouraged speed matching (Text::Tmpl is almost entirely C based and is very fast). The Velocity engine brought \&\s-1AUTO_EVAL\s0 and \s-1SHOW_UNDEFINED_INTERP.\s0 .PP 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 \s-1TT.\s0 .PP 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. .PP Most of the standard Text::Tmpl documentation applies, as does the documentation covering Velocity (\s-1VTL\s0). .PP So should you use Template::Alloy ? Well, try it out. It may give you no visible improvement. Or it could. .SH "BACKEND" .IX Header "BACKEND" 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 = \&\*(L"[% 1 + 2 %]\*(R" ; a|eval %]). The individual methods such as parse_expr and play_expr may be used by external applications to add \s-1TT\s0 style variable parsing to other applications. .PP The regex parser returns an \s-1AST \s0(abstract syntax tree) of the text, directives, variables, and expressions. All of the different template syntax options compile to the same \s-1AST\s0 format. The \s-1AST\s0 is composed only of scalars and arrayrefs and is suitable for sending to JavaScript via \s-1JSON\s0 or sharing with other languages. The parse_tree method is used for returning this \s-1AST.\s0 .PP Once at the \s-1AST\s0 stage, there are two modes of operation. Alloy can either operate directly on the \s-1AST\s0 using the Play role, or it can compile the \s-1AST\s0 to perl code via the Compile role, and then execute the code. To use the perl code route, you must set the \s-1COMPILE_PERL\s0 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 \&\s-1AST\s0 is generally faster. The \s-1AST\s0 method is also more secure as cached \&\s-1AST\s0 won't ever eval any \*(L"perl\*(R" (assuming \s-1PERL\s0 blocks are disabled \- which is the default). .SH "ROLES" .IX Header "ROLES" 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. .PP The following is a list of roles used by Template::Alloy. .PP .Vb 10 \& 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 .Ve .PP 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 \s-1CGI\s0 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. .PP .Vb 2 \& # 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); .Ve .PP 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. .PP .Vb 2 \& # 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; .Ve .PP Even with all roles loaded Template::Alloy is still relatively small. You can load all of the roles (except the \s-1JS\s0 role) by passing \*(L"all\*(R" to the use statement. .PP .Vb 1 \& use Template::Alloy \*(Aqall\*(Aq; \& \& # or \& use Template::Alloy load => \*(Aqall\*(Aq; \& \& # or \& use Template::Alloy all => 1; .Ve .PP 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: .PP .Vb 1 \& use Template::Alloy qw(Text::Tmpl HTML::Template); \& \& # or \& use Template::Alloy load => qw(Text::Tmpl HTML::Template); \& \& # or \& use Template::Alloy \& \*(AqText::Tmpl\*(Aq => 1, \& \*(AqHTML::Template\*(Aq => 1; .Ve .PP 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 \*(L"stood-in\*(R" modules by name. .PP The following modules may be \*(L"stood-in\*(R" for: .PP .Vb 4 \& Template \& Text::Tmpl \& HTML::Template \& HTML::Template::Expr .Ve .PP 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 \*(L"features-on-the-edge\*(R" then you may need to re-write portions of your code that interact with the template system. .SH "PUBLIC METHODS" .IX Header "PUBLIC METHODS" The following section lists most of the publicly available methods. Some less commonly used public methods are listed later in this document. .ie n .IP """new""" 4 .el .IP "\f(CWnew\fR" 4 .IX Item "new" .Vb 3 \& my $obj = Template::Alloy\->new({ \& INCLUDE_PATH => [\*(Aq/my/path/to/content\*(Aq, \*(Aq/my/path/to/content2\*(Aq], \& }); .Ve .Sp Arguments may be passed as a hash or as a hashref. Returns a Template::Alloy object. .Sp 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. .ie n .IP """process""" 4 .el .IP "\f(CWprocess\fR" 4 .IX Item "process" This is the \s-1TT\s0 interface for starting processing. Any errors that result in the template processing being stopped will be stored and available via the \->error method. .Sp .Vb 3 \& my $t = Template::Alloy\->new; \& $t\->process($in, $swap, $out) \& || die $t\->error; .Ve .Sp Process takes three arguments. .Sp The \f(CW$in\fR argument can be any one of: .Sp .Vb 4 \& 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. .Ve .Sp The \f(CW$swap\fR 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. .Sp The \f(CW$out\fR argument can be any one of: .Sp .Vb 1 \& 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. .Ve .Sp Additionally \- the \f(CW$out\fR argument can be configured using the \s-1OUTPUT\s0 configuration item. .Sp The process method defaults to using the \*(L"cet\*(R" syntax which will parse \s-1TT3\s0 and most \&\s-1TT2\s0 documents. To parse \s-1HT\s0 or \s-1HTE\s0 documents, you must pass the \s-1SYNTAX\s0 configuration item to the \*(L"new\*(R" method. All calls to process would then default to \s-1HTE\s0 syntax. .Sp .Vb 1 \& my $obj = Template::Alloy\->new(SYNTAX => \*(Aqhte\*(Aq); .Ve .ie n .IP """process_simple""" 4 .el .IP "\f(CWprocess_simple\fR" 4 .IX Item "process_simple" Similar to the process method but with the following restrictions: .Sp The \f(CW$in\fR parameter is limited to a filename or a reference a string containing the contents. .Sp The \f(CW$out\fR parameter may only be a reference to a scalar string that output will be appended to. .Sp Additionally, the following configuration variables will be ignored: \&\s-1VARIABLES, PRE_DEFINE, BLOCKS, PRE_PROCESS, PROCESS, POST_PROCESS, AUTO_RESET, OUTPUT.\s0 .ie n .IP """error""" 4 .el .IP "\f(CWerror\fR" 4 .IX Item "error" Should something go wrong during a \*(L"process\*(R" command, the error that occurred can be retrieved via the error method. .Sp .Vb 2 \& $obj\->process(\*(Aqsomefile.html\*(Aq, {a => \*(Aqb\*(Aq}, \e$string_ref) \& || die $obj\->error; .Ve .ie n .IP """output""" 4 .el .IP "\f(CWoutput\fR" 4 .IX Item "output" 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 \s-1HT\s0 calling conventions for new are supported. The key difference is that Alloy will not actually process the template until the output method is called. .Sp .Vb 3 \& my $obj = Template::Alloy\->new(filename => \*(Aqmyfile.html\*(Aq); \& $obj\->param(\e%swap); \& print $obj\->output; .Ve .Sp See the HTML::Template documentation for more information. .Sp The output method defaults to using the \*(L"hte\*(R" syntax which will parse \&\s-1HTE\s0 and \s-1HT\s0 documents. To parse \s-1TT3\s0 or \s-1TT2\s0 documents, you must pass the \s-1SYNTAX\s0 configuration item to the \*(L"new\*(R" method. All calls to process would then default to \s-1TT3\s0 syntax. .Sp .Vb 1 \& my $obj = Template::Alloy\->new(SYNTAX => \*(Aqtt3\*(Aq); .Ve .Sp Any errors that occur during the output method will die with the error as the die value. .ie n .IP """param""" 4 .el .IP "\f(CWparam\fR" 4 .IX Item "param" HTML::Template way to get or set variable values that will be used by the output method. .Sp .Vb 1 \& my $val = $obj\->param(\*(Aqkey\*(Aq); # 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 .Ve .Sp See the HTML::Template documentation for more information. .Sp 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. .ie n .IP """define_vmethod""" 4 .el .IP "\f(CWdefine_vmethod\fR" 4 .IX Item "define_vmethod" This method is available for defining extra Virtual methods or filters. This method is similar to Template::Stash::define_vmethod. .Sp .Vb 4 \& Template::Alloy\->define_vmethod( \& \*(Aqtext\*(Aq, \& reverse => sub { my $item = shift; return scalar reverse $item }, \& ); .Ve .ie n .IP """register_function""" 4 .el .IP "\f(CWregister_function\fR" 4 .IX Item "register_function" This is the HTML::Template way of defining text vmethods. It is the same as calling define_vmethod with \*(L"text\*(R" as the first argument. .Sp .Vb 3 \& Template::Alloy\->register_function( \& reverse => sub { my $item = shift; return scalar reverse $item }, \& ); .Ve .ie n .IP """define_directive""" 4 .el .IP "\f(CWdefine_directive\fR" 4 .IX Item "define_directive" This method can be used for adding new directives or overridding existing ones. .Sp .Vb 10 \& 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\*(Aqt "continue" any other directives \& }, \& ); .Ve .Sp Now with a template like: .Sp .Vb 2 \& my $str = "([% MYDIR %]This is something[% END %])"; \& Template::Alloy\->new\->process(\e$str); .Ve .Sp You will get: .Sp .Vb 1 \& (I always say the same thing!) .Ve .Sp We'll add more details in later revisions of this document. .ie n .IP """define_syntax""" 4 .el .IP "\f(CWdefine_syntax\fR" 4 .IX Item "define_syntax" This method can be used for adding another syntax to or overriding existing ones in the list of choices available in Alloy. The syntax can be chosen by the \s-1SYNTAX\s0 configuration item. .Sp .Vb 11 \& Template::Alloy\->define_syntax( \& my_uber_syntax => sub { \& my $self = shift; \& local $self\->{\*(AqV2PIPE\*(Aq} = 0; \& local $self\->{\*(AqV2EQUALS\*(Aq} = 0; \& local $self\->{\*(AqPRE_CHOMP\*(Aq} = 0; \& local $self\->{\*(AqPOST_CHOMP\*(Aq} = 0; \& local $self\->{\*(AqNO_INCLUDES\*(Aq} = 0; \& return $self\->parse_tree_tt3(@_); \& }, \& ); .Ve .Sp The subroutine that is used must return an opcode tree (\s-1AST\s0) that can be played by the execute_tree method. .ie n .IP """define_operator""" 4 .el .IP "\f(CWdefine_operator\fR" 4 .IX Item "define_operator" This method allows for adding new operators or overriding existing ones. .Sp .Vb 9 \& Template::Alloy\->define_operator({ \& type => \*(Aqright\*(Aq, # can be one of prefix, postfix, right, left, none, ternary, assign \& precedence => 84, # relative precedence for resolving multiple operators without parens \& symbols => [\*(Aqfoo\*(Aq, \*(AqFOO\*(Aq], # any mix of chars can be used for the operators \& play_sub => sub { \& my ($one, $two) = @_; \& return "You\*(Aqve been foo\*(Aqed ($one, $two)"; \& }, \& }); .Ve .Sp You can then use it in a template as in the following: .Sp .Vb 2 \& my $str = "[% \*(Aqralph\*(Aq foo 1 + 2 * 3 %]"; \& Template::Alloy\->new\->process(\e$str); .Ve .Sp You will get: .Sp .Vb 1 \& You\*(Aqve been foo\*(Aqed (ralph, 7) .Ve .Sp Future revisions of this document will include more samples. This is an experimental feature and the \s-1API\s0 will probably change. .ie n .IP """dump_parse_tree""" 4 .el .IP "\f(CWdump_parse_tree\fR" 4 .IX Item "dump_parse_tree" This method allows for returning a Data::Dumper dump of a parsed template. It is mainly used for testing. .ie n .IP """dump_parse_expr""" 4 .el .IP "\f(CWdump_parse_expr\fR" 4 .IX Item "dump_parse_expr" This method allows for returning a Data::Dumper dump of a parsed variable. It is mainly used for testing. .ie n .IP """import""" 4 .el .IP "\f(CWimport\fR" 4 .IX Item "import" All of the arguments that can be passed to \*(L"use\*(R" that are listed above in the section dealing with \s-1ROLES,\s0 can be used with the import method. .Sp .Vb 2 \& # 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(\*(AqText::Tmpl\*(Aq, \*(AqHTML::Template::Expr\*(Aq); .Ve .Sp As mentioned in the \s-1ROLE\s0 section \- arguments passed to import are not imported into current namespace. Roles and methods are only imported into the Template::Alloy namespace. .SH "VARIABLES" .IX Header "VARIABLES" This section discusses how to use variables and expressions in the \s-1TT\s0 mini-language. .PP A variable is the most simple construct to insert into the \s-1TT\s0 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 \*(L"\s-1VARIABLES\*(R"\s0 or \*(L"\s-1PRE_DEFINE\*(R"\s0 configuration variables. .PP If you are using either the \s-1HT\s0 or the \s-1HTE\s0 syntax, the \s-1VAR, IF, UNLESS, LOOP,\s0 and \s-1INCLUDE\s0 directives will accept a \s-1NAME\s0 attribute which may only be a single level (non-chained) HTML::Template variable name, or they may accept an \s-1EXPR\s0 attribute which may be any valid \s-1TT3\s0 variable or expression. .PP The following are some sample ways to access variables. .PP .Vb 10 \& ### some sample variables \& my %vars = ( \& one => \*(Aq1.0\*(Aq, \& foo => \*(Aqbar\*(Aq, \& vname => \*(Aqone\*(Aq, \& some_code => sub { "You passed me (".join(\*(Aq, \*(Aq, @_).")" }, \& some_data => { \& a => \*(AqA\*(Aq, \& bar => 3234, \& c => [3, 1, 4, 1, 5, 9], \& vname => \*(Aqone\*(Aq, \& }, \& my_list => [20 .. 50], \& cet => Template::Alloy\->new, \& ); \& \& ### pass the variables into the Alloy process \& $cet\->process($template_name, \e%vars) \& || die $cet\->error; \& \& ### pass the variables during object creation (will be available to every process call) \& my $cet = Template::Alloy\->new(VARIABLES => \e%vars); .Ve .SS "\s-1GETTING VARIABLES\s0" .IX Subsection "GETTING VARIABLES" Once you have variables defined, they can be used directly in the template by using their name in the stash. Or by using the \s-1GET\s0 directive. .PP .Vb 3 \& [% foo %] \& [% one %] \& [% GET foo %] .Ve .PP Would print when processed: .PP .Vb 3 \& bar \& 1.0 \& bar .Ve .PP To access members of a hashref or an arrayref, you can chain together the names using a \*(L".\*(R". .PP .Vb 3 \& [% some_data.a %] \& [% my_list.0] [% my_list.1 %] [% my_list.\-1 %] \& [% some_data.c.2 %] .Ve .PP Would print: .PP .Vb 3 \& A \& 20 21 50 \& 4 .Ve .PP 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. .PP .Vb 4 \& [% some_code %] \& [% some_code() %] \& [% some_code(foo) %] \& [% some_code(one, 2, 3) %] .Ve .PP Would print: .PP .Vb 4 \& You passed me (). \& You passed me (). \& You passed me (bar). \& You passed me (1.0, 2, 3). .Ve .PP If the value of a variable is an object, methods can be called using the \*(L".\*(R" operator. .PP .Vb 1 \& [% cet %] \& \& [% cet.dump_parse_expr(\*(Aq1 + 2\*(Aq).replace(\*(Aq\es+\*(Aq, \*(Aq \*(Aq) %] .Ve .PP Would print something like: .PP .Vb 1 \& Template::Alloy=HASH(0x814dc28) \& \& $VAR1 = [ [ undef, \*(Aq+\*(Aq, \*(Aq1\*(Aq, \*(Aq2\*(Aq ], 0 ]; .Ve .PP 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 \s-1VIRTUAL METHODS\s0 .PP .Vb 3 \& [% foo.length %] \& [% my_list.size %] \& [% some_data.c.join(" | ") %] .Ve .PP Would print: .PP .Vb 3 \& 3 \& 31 \& 3 | 1 | 4 | 5 | 9 .Ve .PP It is also possible to \*(L"interpolate\*(R" variable names using a \*(L"$\*(R". 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 \&\*(L"${\*(R" and \*(L"}\*(R". .PP .Vb 5 \& [% $vname %] \& [% ${vname} %] \& [% ${some_data.vname} %] \& [% some_data.$foo %] \& [% some_data.${foo} %] .Ve .PP Would print: .PP .Vb 5 \& 1.0 \& 1.0 \& 1.0 \& 3234 \& 3234 .Ve .PP In Alloy it is also possible to embed any expression (non-directive) in \&\*(L"${\*(R" and \*(L"}\*(R" and it is possible to use non-integers for array access. (This is not available in \s-1TT2\s0) .PP .Vb 3 \& [% [\*(Aqa\*(Aq..\*(Aqz\*(Aq].${ 2.3 } %] \& [% {ab => \*(AqAB\*(Aq}.${ \*(Aqa\*(Aq ~ \*(Aqb\*(Aq } %] \& [% color = qw/Red Blue/; FOR [1..4] ; color.${ loop.index % color.size } ; END %] .Ve .PP Would print: .PP .Vb 3 \& c \& AB \& RedBlueRedBlue .Ve .SS "\s-1SETTING VARIABLES.\s0" .IX Subsection "SETTING VARIABLES." To define variables during processing, you can use the = operator. In most cases this is the same as using the \s-1SET\s0 directive. .PP .Vb 2 \& [% a = 234 %][% a %] \& [% SET b = "Hello" %][% b %] .Ve .PP Would print: .PP .Vb 2 \& 234 \& Hello .Ve .PP It is also possible to create arrayrefs and hashrefs. .PP .Vb 2 \& [% a = [1, 2, 3] %] \& [% b = {key1 => \*(Aqval1\*(Aq, \*(Aqkey2\*(Aq => \*(Aqval2\*(Aq} %] \& \& [% a.1 %] \& [% b.key1 %] [% b.key2 %] .Ve .PP Would print: .PP .Vb 2 \& 2 \& val1 val2 .Ve .PP It is possible to set multiple values in the same \s-1SET\s0 directive. .PP .Vb 4 \& [% SET a = \*(AqA\*(Aq \& b = \*(AqB\*(Aq \& c = \*(AqC\*(Aq %] \& [% a %] [% b %] [% c %] .Ve .PP Would print: .PP .Vb 1 \& A B C .Ve .PP It is also possible to unset variables, or to set members of nested data structures. .PP .Vb 2 \& [% a = 1 %] \& [% SET a %] \& \& [% b.0.c = 37 %] \& \& ([% a %]) \& [% b.0.c %] .Ve .PP Would print .PP .Vb 2 \& () \& 37 .Ve .SH "LITERALS AND CONSTRUCTORS" .IX Header "LITERALS AND CONSTRUCTORS" 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. .IP "Integers and Numbers." 4 .IX Item "Integers and Numbers." .Vb 4 \& [% 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) .Ve .Sp Scientific notation is supported. .Sp .Vb 1 \& [% 314159e\-5 + 0 %] Prints 3.14159. \& \& [% .0000001.fmt(\*(Aq%.1e\*(Aq) %] Prints 1.0e\-07 .Ve .Sp Hexadecimal input is also supported. .Sp .Vb 1 \& [% 0xff + 0 %] Prints 255 \& \& [% 48875.fmt(\*(Aq%x\*(Aq) %] Prints beeb .Ve .IP "Single quoted strings." 4 .IX Item "Single quoted strings." Returns the string. No variable interpolation happens. .Sp .Vb 5 \& [% \*(Aqfoobar\*(Aq %] Prints "foobar". \& [% \*(Aq$foo\en\*(Aq %] Prints "$foo\e\en". # the \e\en is a literal "\e" and an "n" \& [% \*(AqThat\e\*(Aqs nice\*(Aq %] Prints "That\*(Aqs nice". \& [% str = \*(AqA string\*(Aq %] Sets the value of str. \& [% \*(AqA string\*(Aq.split %] Splits the string on \*(Aq \*(Aq and returns the list. .Ve .Sp Note: virtual methods can only be used on literal strings in Alloy, not in \s-1TT.\s0 .Sp You may also embed the current tags in strings (Alloy only). .Sp .Vb 1 \& [% \*(Aq[% 1 + 2 %]\*(Aq | eval %] Prints "3" .Ve .IP "Double quoted strings." 4 .IX Item "Double quoted strings." Returns the string. Variable interpolation happens. .Sp .Vb 6 \& [% "foobar" %] Prints "foobar". \& [% "$foo" %] Prints "bar" (assuming the value of foo is bar). \& [% "${foo}" %] Prints "bar" (assuming the value of foo is bar). \& [% "foobar\en" %] Prints "foobar\en". # the \en is a newline. \& [% str = "Hello" %] Sets the value of str. \& [% "foo".replace(\*(Aqfoo\*(Aq,\*(Aqbar\*(Aq) %] Prints "bar". .Ve .Sp Note: virtual methods can only be used on literal strings in Alloy, not in \s-1TT.\s0 .Sp You may also embed the current tags in strings (Alloy only). .Sp .Vb 1 \& [% "[% 1 + 2 %]" | eval %] Prints "3" .Ve .IP "Array Constructs." 4 .IX Item "Array Constructs." .Vb 5 \& [% [1, 2, 3] %] Prints something like ARRAY(0x8309e90). \& [% array1 = [1 .. 3] %] Sets the value of array1. \& [% array2 = [foo, \*(Aqa\*(Aq, []] %] Sets the value of array2. \& [% [4, 5, 6].size %] Prints 3. \& [% [7, 8, 9].reverse.0 %] Prints 9. .Ve .Sp Note: virtual methods can only be used on array contructs in Alloy, not in \s-1TT.\s0 .IP "Quoted Array Constructs." 4 .IX Item "Quoted Array Constructs." .Vb 4 \& [% 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. .Ve .Sp Note: this works in Alloy and is planned for \s-1TT3.\s0 .IP "Hash Constructs." 4 .IX Item "Hash Constructs." .Vb 7 \& [% {foo => \*(Aqbar\*(Aq} %] Prints something like HASH(0x8305880) \& [% hash = {foo => \*(Aqbar\*(Aq, c => {}} %] Sets the value of hash. \& [% {a => \*(AqA\*(Aq, b => \*(AqB\*(Aq}.size %] Prints 2. \& [% {\*(Aqa\*(Aq => \*(AqA\*(Aq, \*(Aqb\*(Aq => \*(AqB\*(Aq}.size %] Prints 2. \& [% name = "Tom" %] \& [% {Tom => \*(AqYou are Tom\*(Aq, \& Kay => \*(AqYou are Kay\*(Aq}.$name %] Prints You are Tom .Ve .Sp Note: virtual methods can only be used on hash contructs in Alloy, not in \s-1TT.\s0 .IP "Regex Constructs." 4 .IX Item "Regex Constructs." .Vb 2 \& [% /foo/ %] Prints (?\-xism:foo) \& [% a = /(foo)/i %][% "FOO".match(a).0 %] Prints FOO .Ve .Sp Note: this works in Alloy and is planned for \s-1TT3.\s0 .SH "VIRTUAL METHODS" .IX Header "VIRTUAL METHODS" Virtual methods (vmethods) are a \s-1TT\s0 feature that allow for operating on the swapped template variables. .PP This document shows some samples of using vmethods. For a full listing of available virtual methods, see Template::Alloy::VMethod. .SH "EXPRESSIONS" .IX Header "EXPRESSIONS" 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 \s-1SET\s0 directive, and the filename of \s-1PROCESS, INCLUDE, WRAPPER,\s0 and \s-1INSERT.\s0 .PP For a full listing of operators, see Template::Alloy::Operator. .PP The following section shows some samples of expressions. For a full list of available operators, please see the section titled \s-1OPERATORS.\s0 .PP .Vb 3 \& [% 1 + 2 %] Prints 3 \& [% 1 + 2 * 3 %] Prints 7 \& [% (1 + 2) * 3 %] Prints 9 \& \& [% x = 2 %] # assignments don\*(Aqt return anything \& [% (x = 2) %] Prints 2 # unless they are in parens \& [% y = 3 %] \& [% x * (y \- 1) %] Prints 4 .Ve .SH "DIRECTIVES" .IX Header "DIRECTIVES" This section contains the alphabetical list of \s-1DIRECTIVES\s0 available in Alloy. \s-1DIRECTIVES\s0 are the \*(L"functions\*(R" and control structures that work in the various mini-languages. For further discussion and examples beyond what is listed below, please refer to the \s-1TT\s0 directives documentation or to the appropriate documentation for the particular directive. .PP 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. .PP .Vb 4 \& [% IF 1 %]One[% END %] \& [% FOREACH a = [1 .. 3] %] \& a = [% a %] \& [% END %] \& \& [% SET a = 1 %][% SET a = 2 %][% GET a %] .Ve .PP In \s-1TT\s0 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 \s-1IF, WHILE, FOREACH, UNLESS, FILTER,\s0 and \s-1WRAPPER\s0) 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 \s-1TT3\s0 feature. .PP .Vb 5 \& [% 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 .Ve .PP The following is the list of directives. .ie n .IP """BLOCK""" 4 .el .IP "\f(CWBLOCK\fR" 4 .IX Item "BLOCK" Saves a block of text under a name for later use in \s-1PROCESS, INCLUDE,\s0 and \s-1WRAPPER\s0 directives. Blocks may be placed anywhere within the template being processed including after where they are used. .Sp .Vb 2 \& [% BLOCK foo %]Some text[% END %] \& [% PROCESS foo %] \& \& Would print \& \& Some text \& \& [% INCLUDE foo %] \& [% BLOCK foo %]Some text[% END %] \& \& Would print \& \& Some text .Ve .Sp Anonymous \s-1BLOCKS\s0 can be used for capturing. .Sp .Vb 1 \& [% a = BLOCK %]Some text[% END %][% a %] \& \& Would print \& \& Some text .Ve .Sp Anonymous \s-1BLOCKS\s0 can be used with macros. .ie n .IP """BREAK""" 4 .el .IP "\f(CWBREAK\fR" 4 .IX Item "BREAK" Alias for \s-1LAST. \s0 Used for exiting \s-1FOREACH\s0 and \s-1WHILE\s0 loops. .ie n .IP """CALL""" 4 .el .IP "\f(CWCALL\fR" 4 .IX Item "CALL" Calls the variable (and any underlying coderefs) as in the \s-1GET\s0 method, but always returns an empty string. .ie n .IP """CASE""" 4 .el .IP "\f(CWCASE\fR" 4 .IX Item "CASE" Used with the \s-1SWITCH\s0 directive. See the \*(L"\s-1SWITCH\*(R"\s0 directive. .ie n .IP """CATCH""" 4 .el .IP "\f(CWCATCH\fR" 4 .IX Item "CATCH" Used with the \s-1TRY\s0 directive. See the \*(L"\s-1TRY\*(R"\s0 directive. .ie n .IP """CLEAR""" 4 .el .IP "\f(CWCLEAR\fR" 4 .IX Item "CLEAR" Clears any of the content currently generated in the innermost block or template. This can be useful when used in conjunction with the \s-1TRY\s0 statement to clear generated content if an error occurs later. .ie n .IP """COMMENT""" 4 .el .IP "\f(CWCOMMENT\fR" 4 .IX Item "COMMENT" Will comment out any text found between open and close tags. Note, that the intermediate items are still parsed and \s-1END\s0 tags must align \- but the parsed content will be discarded. .Sp .Vb 4 \& [% COMMENT %] \& This text won\*(Aqt be shown. \& [% IF 1 %]And this won\*(Aqt either.[% END %] \& [% END %] .Ve .ie n .IP """CONFIG""" 4 .el .IP "\f(CWCONFIG\fR" 4 .IX Item "CONFIG" Allow for changing the value of some compile time and runtime configuration options. .Sp .Vb 4 \& [% CONFIG \& ANYCASE => 1 \& PRE_CHOMP => \*(Aq\-\*(Aq \& %] .Ve .Sp The following compile time configuration options may be set: .Sp .Vb 10 \& ANYCASE \& AUTO_EVAL \& AUTO_FILTER \& CACHE_STR_REFS \& ENCODING \& INTERPOLATE \& POST_CHOMP \& PRE_CHOMP \& SEMICOLONS \& SHOW_UNDEFINED_INTERP \& SYNTAX \& V1DOLLAR \& V2EQUALS \& V2PIPE .Ve .Sp The following runtime configuration options may be set: .Sp .Vb 5 \& ADD_LOCAL_PATH \& CALL_CONTEXT \& DUMP \& VMETHOD_FUNCTIONS \& STRICT (can only be enabled, cannot be disabled) .Ve .Sp If non-named parameters as passed, they will show the current configuration: .Sp .Vb 1 \& [% CONFIG ANYCASE, PRE_CHOMP %] \& \& CONFIG ANYCASE = undef \& CONFIG PRE_CHOMP = undef .Ve .ie n .IP """DEBUG""" 4 .el .IP "\f(CWDEBUG\fR" 4 .IX Item "DEBUG" Used to reset the \s-1DEBUG_FORMAT\s0 configuration variable, or to turn \&\s-1DEBUG\s0 statements on or off. This only has effect if the \s-1DEBUG_DIRS\s0 or \&\s-1DEBUG_ALL\s0 flags were passed to the \s-1DEBUG\s0 configuration variable. .Sp .Vb 3 \& [% DEBUG format \*(Aq($file) (line $line) ($text)\*(Aq %] \& [% DEBUG on %] \& [% DEBUG off %] .Ve .ie n .IP """DEFAULT""" 4 .el .IP "\f(CWDEFAULT\fR" 4 .IX Item "DEFAULT" Similar to \s-1SET,\s0 but only sets the value if a previous value was not defined or was zero length. .Sp .Vb 1 \& [% DEFAULT foo = \*(Aqbar\*(Aq %][% foo %] => \*(Aqbar\*(Aq \& \& [% foo = \*(Aqbaz\*(Aq %][% DEFAULT foo = \*(Aqbar\*(Aq %][% foo %] => \*(Aqbaz\*(Aq .Ve .ie n .IP """DUMP""" 4 .el .IP "\f(CWDUMP\fR" 4 .IX Item "DUMP" \&\s-1DUMP\s0 inserts a Data::Dumper printout of the variable or expression. If no argument is passed it will dump the entire contents of the current variable stash (with private keys removed). .Sp The output also includes the current file and line number that the \&\s-1DUMP\s0 directive was called from. .Sp See the \s-1DUMP\s0 configuration item for ways to customize and control the output available to the \s-1DUMP\s0 directive. .Sp .Vb 1 \& [% DUMP %] # dumps everything \& \& [% DUMP 1 + 2 %] .Ve .ie n .IP """ELSE""" 4 .el .IP "\f(CWELSE\fR" 4 .IX Item "ELSE" Used with the \s-1IF\s0 directive. See the \*(L"\s-1IF\*(R"\s0 directive. .ie n .IP """ELSIF""" 4 .el .IP "\f(CWELSIF\fR" 4 .IX Item "ELSIF" Used with the \s-1IF\s0 directive. See the \*(L"\s-1IF\*(R"\s0 directive. .ie n .IP """END""" 4 .el .IP "\f(CWEND\fR" 4 .IX Item "END" Used to end a block directive. .ie n .IP """EVAL""" 4 .el .IP "\f(CWEVAL\fR" 4 .IX Item "EVAL" Same as the \s-1EVALUATE\s0 directive. .ie n .IP """EVALUATE""" 4 .el .IP "\f(CWEVALUATE\fR" 4 .IX Item "EVALUATE" 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 \s-1CONFIG\s0 directive may be passed here. .Sp .Vb 1 \& [% EVALUATE "[% 1 + 3 %]" %] \& \& [% foo = "bar" %] \& [% EVALUATE "" SYNTAX => \*(Aqht\*(Aq %] .Ve .ie n .IP """FILTER""" 4 .el .IP "\f(CWFILTER\fR" 4 .IX Item "FILTER" Used to apply different treatments to blocks of text. It may operate as a \s-1BLOCK\s0 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 \s-1FILTER.\s0 .Sp \&\s-1TODO \-\s0 enumerate the at least 7 ways to pass and use filters. .ie n .IP "\*(Aq|\*(Aq" 4 .el .IP "\f(CW\*(Aq|\*(Aq\fR" 4 .IX Item "|" Alias for the \s-1FILTER\s0 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 \s-1TT3. \s0 To get the \s-1TT2\s0 behavior for a \s-1PIPE,\s0 use the V2PIPE configuration item. .ie n .IP """FINAL""" 4 .el .IP "\f(CWFINAL\fR" 4 .IX Item "FINAL" Used with the \s-1TRY\s0 directive. See the \*(L"\s-1TRY\*(R"\s0 directive. .ie n .IP """FOR""" 4 .el .IP "\f(CWFOR\fR" 4 .IX Item "FOR" Alias for \s-1FOREACH\s0 .ie n .IP """FOREACH""" 4 .el .IP "\f(CWFOREACH\fR" 4 .IX Item "FOREACH" Allows for iterating over the contents of any arrayref. If the variable is not an arrayref, it is automatically promoted to one. .Sp .Vb 3 \& [% FOREACH i IN [1 .. 3] %] \& The variable i = [% i %] \& [%~ END %] \& \& [% a = [1 .. 3] %] \& [% FOREACH j IN a %] \& The variable j = [% j %] \& [%~ END %] .Ve .Sp Would print: .Sp .Vb 3 \& The variable i = 1 \& The variable i = 2 \& The variable i = 3 \& \& The variable j = 1 \& The variable j = 2 \& The variable j = 3 .Ve .Sp You can also use the \*(L"=\*(R" instead of \*(L"\s-1IN\*(R"\s0 or \*(L"in\*(R". .Sp .Vb 3 \& [% FOREACH i = [1 .. 3] %] \& The variable i = [% i %] \& [%~ END %] \& \& Same as before. .Ve .Sp Setting into a variable is optional. .Sp .Vb 2 \& [% a = [1 .. 3] %] \& [% FOREACH a %] Hi [% END %] .Ve .Sp Would print: .Sp .Vb 1 \& hi hi hi .Ve .Sp If the item being iterated is a hashref and the \s-1FOREACH\s0 does not set into a variable, then values of the hashref are copied into the variable stash. .Sp .Vb 3 \& [% FOREACH [{a => 1}, {a => 2}] %] \& Key a = [% a %] \& [%~ END %] .Ve .Sp Would print: .Sp .Vb 2 \& Key a = 1 \& Key a = 2 .Ve .Sp The \s-1FOREACH\s0 process uses the Template::Alloy::Iterator class to handle iterations (It is compatible with Template::Iterator). During the \s-1FOREACH\s0 loop an object blessed into the iterator class is stored in the variable \*(L"loop\*(R". .Sp The loop variable provides the following information during a \s-1FOREACH:\s0 .Sp .Vb 12 \& 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 .Ve .Sp The following: .Sp .Vb 1 \& [% FOREACH [1 .. 3] %] [% loop.count %]/[% loop.size %] [% END %] .Ve .Sp Would print: .Sp .Vb 1 \& 1/3 2/3 3/3 .Ve .Sp The iterator is also available using a plugin. This allows for access to multiple \*(L"loop\*(R" variables in a nested \s-1FOREACH\s0 directive. .Sp .Vb 6 \& [%~ USE outer_loop = Iterator(["a", "b"]) %] \& [%~ FOREACH i = outer_loop %] \& [%~ FOREACH j = ["X", "Y"] %] \& [% outer_loop.count %]\-[% loop.count %] = ([% i %] and [% j %]) \& [%~ END %] \& [%~ END %] .Ve .Sp Would print: .Sp .Vb 4 \& 1\-1 = (a and X) \& 1\-2 = (a and Y) \& 2\-1 = (b and X) \& 2\-2 = (b and Y) .Ve .Sp \&\s-1FOREACH\s0 may also be used as a post operative directive. .Sp .Vb 1 \& [% "$i" FOREACH i = [1 .. 5] %] => 12345 .Ve .ie n .IP """GET""" 4 .el .IP "\f(CWGET\fR" 4 .IX Item "GET" Return the value of a variable or expression. .Sp .Vb 1 \& [% GET a %] .Ve .Sp The \s-1GET\s0 keyword may be omitted. .Sp .Vb 1 \& [% a %] \& \& [% 7 + 2 \- 3 %] => 6 .Ve .Sp See the section on \s-1VARIABLES.\s0 .ie n .IP """IF (IF / ELSIF / ELSE)""" 4 .el .IP "\f(CWIF (IF / ELSIF / ELSE)\fR" 4 .IX Item "IF (IF / ELSIF / ELSE)" 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 \s-1ELSIF\s0 block. If an \&\s-1ELSIF\s0's expression is true then it is processed. Finally it looks for an \s-1ELSE\s0 block which is processed if none of the \s-1IF\s0 or \s-1ELSIF\s0's expressions were true. .Sp .Vb 1 \& [% IF a == b %]A equaled B[% END %] \& \& [% IF a == b \-%] \& A equaled B \& [%\- ELSIF a == c \-%] \& A equaled C \& [%\- ELSE \-%] \& Couldn\*(Aqt determine that A equaled anything. \& [%\- END %] .Ve .Sp \&\s-1IF\s0 may also be used as a post operative directive. .Sp .Vb 1 \& [% \*(AqA equaled B\*(Aq IF a == b %] .Ve .Sp Note: If you are using HTML::Template style documents, the \s-1TMPL_IF\s0 tag parses using the limited HTML::Template parsing rules. However, you may use EXPR="" to embed a \s-1TT3\s0 style expression. .ie n .IP """INCLUDE""" 4 .el .IP "\f(CWINCLUDE\fR" 4 .IX Item "INCLUDE" Parse the contents of a file or block and insert them. Variables defined or modifications made to existing variables are discarded after a template is included. .Sp .Vb 1 \& [% 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 %] .Ve .Sp Arguments may also be passed to the template: .Sp .Vb 1 \& [% INCLUDE "path/to/template.html" a = "An arg" b = "Another arg" %] .Ve .Sp Filenames must be relative to \s-1INCLUDE_PATH\s0 unless the \s-1ABSOLUTE\s0 or \s-1RELATIVE\s0 configuration items are set. .Sp Multiple filenames can be passed by separating them with a plus, a space, or commas (\s-1TT2\s0 doesn't support the comma). Any supplied arguments will be used on all templates. .Sp .Vb 2 \& [% INCLUDE "path/to/template.html", \& "path/to/template2.html" a = "An arg" b = "Another arg" %] .Ve .Sp 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. .ie n .IP """INSERT""" 4 .el .IP "\f(CWINSERT\fR" 4 .IX Item "INSERT" Insert the contents of a file without template parsing. .Sp Filenames must be relative to \s-1INCLUDE_PATH\s0 unless the \s-1ABSOLUTE\s0 or \s-1RELATIVE\s0 configuration items are set. .Sp Multiple filenames can be passed by separating them with a plus, a space, or commas (\s-1TT2\s0 doesn't support the comma). .Sp .Vb 2 \& [% INSERT "path/to/template.html", \& "path/to/template2.html" %] .Ve .ie n .IP """JS""" 4 .el .IP "\f(CWJS\fR" 4 .IX Item "JS" Only available if the \s-1COMPILE_JS\s0 configuration item is true (default is false). This requires the Template::Alloy::JS module to be installed. .Sp Allow eval'ing the block of text as javascript. The block will be parsed and then eval'ed. .Sp .Vb 6 \& [% a = "BimBam" %] \& [%~ JS %] \& write(\*(AqThe variable a was "\*(Aq + get(\*(Aqa\*(Aq) + \*(Aq"\*(Aq); \& set(\*(Aqb\*(Aq, "FooBar"); \& [% END %] \& [% b %] .Ve .Sp Would print: .Sp .Vb 2 \& The variable a was "BimBam" \& FooBar .Ve .ie n .IP """LAST""" 4 .el .IP "\f(CWLAST\fR" 4 .IX Item "LAST" Used to exit out of a \s-1WHILE\s0 or \s-1FOREACH\s0 loop. .ie n .IP """LOOP""" 4 .el .IP "\f(CWLOOP\fR" 4 .IX Item "LOOP" This directive operates similar to the HTML::Template loop directive. The \s-1LOOP\s0 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. .Sp .Vb 1 \& [% var a = [{b => 1}, {b => 2}, {b => 3}] %] \& \& [% LOOP a %] ([% b %]) [% END %] .Ve .Sp Would print: .Sp .Vb 1 \& (1) (2) (3) .Ve .Sp If Alloy is in \s-1HT\s0 mode and \s-1GLOBAL_VARS\s0 is false, the contents of the hashref will be the only items available during the loop iteration. .Sp If \s-1LOOP_CONTEXT_VARS\s0 is true, and \f(CW$QR_PRIVATE\fR 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. .ie n .IP """MACRO""" 4 .el .IP "\f(CWMACRO\fR" 4 .IX Item "MACRO" Takes a directive and turns it into a variable that can take arguments. .Sp .Vb 1 \& [% MACRO foo(i, j) BLOCK %]You passed me [% i %] and [% j %].[% END %] \& \& [%~ foo("a", "b") %] \& [% foo(1, 2) %] .Ve .Sp Would print: .Sp .Vb 2 \& You passed me a and b. \& You passed me 1 and 2. .Ve .Sp Another example: .Sp .Vb 1 \& [% MACRO bar(max) FOREACH i = [1 .. max] %]([% i %])[% END %] \& \& [%~ bar(4) %] .Ve .Sp Would print: .Sp .Vb 1 \& (1)(2)(3)(4) .Ve .Sp Starting with version 1.012 of Template::Alloy there is also a macro operator. .Sp .Vb 1 \& [% foo = \->(i,j){ "You passed me $i and $j" } %] \& \& [% bar = \->(max){ FOREACH i = [1 .. max]; i ; END } %] .Ve .Sp See the Template::Alloy::Operator documentation for more examples. .ie n .IP """META""" 4 .el .IP "\f(CWMETA\fR" 4 .IX Item "META" Used to define variables that will be available via either the template or component namespace. .Sp Once defined, they cannot be overwritten. .Sp .Vb 3 \& [% template.foobar %] \& [%~ META foobar = \*(Aqbaz\*(Aq %] \& [%~ META foobar = \*(Aqbing\*(Aq %] .Ve .Sp Would print: .Sp .Vb 1 \& baz .Ve .ie n .IP """NEXT""" 4 .el .IP "\f(CWNEXT\fR" 4 .IX Item "NEXT" Used to go to the next iteration of a \s-1WHILE\s0 or \s-1FOREACH\s0 loop. .ie n .IP """PERL""" 4 .el .IP "\f(CWPERL\fR" 4 .IX Item "PERL" Only available if the \s-1EVAL_PERL\s0 configuration item is true (default is false). .Sp Allow eval'ing the block of text as perl. The block will be parsed and then eval'ed. .Sp .Vb 7 \& [% a = "BimBam" %] \& [%~ PERL %] \& my $a = "[% a %]"; \& print "The variable \e$a was \e"$a\e""; \& $stash\->set(\*(Aqb\*(Aq, "FooBar"); \& [% END %] \& [% b %] .Ve .Sp Would print: .Sp .Vb 2 \& The variable $a was "BimBam" \& FooBar .Ve .Sp During execution, anything printed to \s-1STDOUT\s0 will be inserted into the template. Also, the \f(CW$stash\fR and \f(CW$context\fR 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. \f(CW$self\fR contains the current Template::Alloy object. .ie n .IP """PROCESS""" 4 .el .IP "\f(CWPROCESS\fR" 4 .IX Item "PROCESS" Parse the contents of a file or block and insert them. Unlike \s-1INCLUDE,\s0 no variable localization happens so variables defined or modifications made to existing variables remain after the template is processed. .Sp .Vb 1 \& [% 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 %] .Ve .Sp Arguments may also be passed to the template: .Sp .Vb 1 \& [% PROCESS "path/to/template.html" a = "An arg" b = "Another arg" %] .Ve .Sp Filenames must be relative to \s-1INCLUDE_PATH\s0 unless the \s-1ABSOLUTE\s0 or \s-1RELATIVE\s0 configuration items are set. .Sp Multiple filenames can be passed by separating them with a plus, a space, or commas (\s-1TT2\s0 doesn't support the comma). Any supplied arguments will be used on all templates. .Sp .Vb 2 \& [% PROCESS "path/to/template.html", \& "path/to/template2.html" a = "An arg" b = "Another arg" %] .Ve .ie n .IP """RAWPERL""" 4 .el .IP "\f(CWRAWPERL\fR" 4 .IX Item "RAWPERL" Only available if the \s-1EVAL_PERL\s0 configuration item is true (default is false). Similar to the \s-1PERL\s0 directive, but you will need to append to the \f(CW$output\fR variable rather than just calling \s-1PRINT.\s0 .ie n .IP """RETURN""" 4 .el .IP "\f(CWRETURN\fR" 4 .IX Item "RETURN" Used to exit the innermost block or template and continue processing in the surrounding block or template. .Sp There are two changes from \s-1TT2\s0 behavior. First, In Alloy, a \s-1RETURN\s0 during a \s-1MACRO\s0 call will only exit the \s-1MACRO. \s0 Second, the \s-1RETURN\s0 directive takes an optional variable name or expression, if passed, the \s-1MACRO\s0 will return this value instead of the normal text from the \s-1MACRO. \s0 The process_simple method will also return this value. .Sp You can also use the item, list, and hash return vmethods. .Sp .Vb 3 \& [% RETURN %] # just exits \& [% RETURN "foo" %] # return value is foo \& [% "foo".return %] # same thing .Ve .ie n .IP """SET""" 4 .el .IP "\f(CWSET\fR" 4 .IX Item "SET" Used to set variables. .Sp .Vb 6 \& [% 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 => \*(Aqc\*(Aq} %][% a.b %] => "c" .Ve .ie n .IP """STOP""" 4 .el .IP "\f(CWSTOP\fR" 4 .IX Item "STOP" Used to exit the entire process method (out of all blocks and templates). No content will be processed beyond this point. .ie n .IP """SWITCH""" 4 .el .IP "\f(CWSWITCH\fR" 4 .IX Item "SWITCH" Allow for \s-1SWITCH\s0 and \s-1CASE\s0 functionality. .Sp .Vb 8 \& [% 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\*(Aqt know what you said \& [% END %] .Ve .Sp Would print: .Sp .Vb 1 \& You said hi or hello .Ve .ie n .IP """TAGS""" 4 .el .IP "\f(CWTAGS\fR" 4 .IX Item "TAGS" 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 \s-1TAGS\s0 directive. Either a named set of tags must be supplied, or two tags themselves must be supplied. .Sp .Vb 1 \& [% TAGS html %] \& \& [% TAGS %] .Ve .Sp The named tags are (duplicated from \s-1TT\s0): .Sp .Vb 10 \& asp => [\*(Aq<%\*(Aq, \*(Aq%>\*(Aq ], # ASP \& default => [\*(Aq\e[%\*(Aq, \*(Aq%\e]\*(Aq ], # default \& html => [\*(Aq\*(Aq ], # HTML comments \& mason => [\*(Aq<%\*(Aq, \*(Aq>\*(Aq ], # HTML::Mason \& metatext => [\*(Aq%%\*(Aq, \*(Aq%%\*(Aq ], # Text::MetaText \& php => [\*(Aq<\e?\*(Aq, \*(Aq\e?>\*(Aq ], # PHP \& star => [\*(Aq\e[\e*\*(Aq, \*(Aq\e*\e]\*(Aq ], # TT alternate \& template => [\*(Aq\e[%\*(Aq, \*(Aq%\e]\*(Aq ], # Normal Template Toolkit \& template1 => [\*(Aq[\e[%]%\*(Aq, \*(Aq%[%\e]]\*(Aq], # allow TT1 style \& tt2 => [\*(Aq\e[%\*(Aq, \*(Aq%\e]\*(Aq ], # TT2 .Ve .Sp 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. .Sp .Vb 1 \& [% TAGS [<] [>] %] matches "[<] tag [>]" \& \& [% TAGS \*(Aq[<]\*(Aq \*(Aq[>]\*(Aq %] matches "[<] tag [>]" \& \& [% TAGS "[<]" "[>]" %] matches "[<] tag [>]" \& \& [% TAGS /[<]/ /[>]/ %] matches "< tag >" \& \& [% TAGS ** ** %] matches "** tag **" \& \& [% TAGS /**/ /**/ %] Throws an exception. .Ve .Sp You should be sure that the start tag does not include grouping parens or \s-1INTERPOLATE\s0 will not function properly. .ie n .IP """THROW""" 4 .el .IP "\f(CWTHROW\fR" 4 .IX Item "THROW" Allows for throwing an exception. If the exception is not caught via the \s-1TRY DIRECTIVE,\s0 the template will abort processing of the directive. .Sp .Vb 1 \& [% THROW mytypes.sometime \*(AqSomething happened\*(Aq arg1 => val1 %] .Ve .Sp See the \s-1TRY\s0 directive for examples of usage. .ie n .IP """TRY""" 4 .el .IP "\f(CWTRY\fR" 4 .IX Item "TRY" The \s-1TRY\s0 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 \s-1TRY\s0 block will then look for a \s-1CATCH\s0 block that will be processed. While it is being processed, the \*(L"error\*(R" variable will be set with the thrown exception as the value. After the \s-1TRY\s0 block \- the \s-1FINAL\s0 block will be ran whether or not an error was thrown (unless a \s-1CATCH\s0 block throws an error). .Sp Note: Parse errors cannot be caught unless they are in an eval \s-1FILTER,\s0 or are in a separate template being INCLUDEd or PROCESSed. .Sp .Vb 7 \& [% TRY %] \& Nothing bad happened. \& [% CATCH %] \& Caught the error. \& [% FINAL %] \& This section runs no matter what happens. \& [% END %] .Ve .Sp Would print: .Sp .Vb 2 \& Nothing bad happened. \& This section runs no matter what happens. .Ve .Sp Another example: .Sp .Vb 9 \& [% TRY %] \& [% THROW "Something happened" %] \& [% CATCH %] \& Error: [% error %] \& Error.type: [% error.type %] \& Error.info: [% error.info %] \& [% FINAL %] \& This section runs no matter what happens. \& [% END %] .Ve .Sp Would print: .Sp .Vb 4 \& Error: undef error \- Something happened \& Error.type: undef \& Error.info: Something happened \& This section runs no matter what happens. .Ve .Sp You can give the error a type and more information including named arguments. This information replaces the \*(L"info\*(R" property of the exception. .Sp .Vb 11 \& [% TRY %] \& [% THROW foo.bar "Something happened" "grrrr" foo => \*(Aqbar\*(Aq %] \& [% 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 %] .Ve .Sp Would print something like: .Sp .Vb 7 \& 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 .Ve .Sp You can also give the \s-1CATCH\s0 block a type to catch. And you can nest \s-1TRY\s0 blocks. If types are specified, Alloy will try and find the closest matching type. Also, an error object can be re-thrown using \f(CW$error\fR as the argument to \s-1THROW.\s0 .Sp .Vb 10 \& [% 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 %] .Ve .Sp Would print: .Sp .Vb 1 \& Caught default \- but re\-threw. \& \& Caught foo.bar. .Ve .ie n .IP """UNLESS""" 4 .el .IP "\f(CWUNLESS\fR" 4 .IX Item "UNLESS" Same as \s-1IF\s0 but condition is negated. .Sp .Vb 1 \& [% UNLESS 0 %]hi[% END %] => hi .Ve .Sp Can also be a post operative directive. .ie n .IP """USE""" 4 .el .IP "\f(CWUSE\fR" 4 .IX Item "USE" Allows for loading a Template::Toolkit style plugin. .Sp .Vb 3 \& [% USE iter = Iterator([\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq]) %] \& [%~ iter.get_first %] \& [% iter.size %] .Ve .Sp Would print: .Sp .Vb 2 \& foo \& 2 .Ve .Sp 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. .Sp .Vb 3 \& [% USE Iterator([\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq]) %] \& [%~ Iterator.get_first %] \& [% Iterator.size %] .Ve .Sp Would print: .Sp .Vb 2 \& foo \& 3 .Ve .Sp Plugins that are loaded are looked up for in the namespace listed in the \s-1PLUGIN_BASE\s0 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 \s-1PLUGIN_BASE\s0 to a non-existent base such as \*(L"_\*(R" (In \s-1TT\s0 it will still fall back to look in Template::Plugin). .Sp 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. .Sp The names of the Plugin being loaded from \s-1PLUGIN_BASE\s0 are case insensitive. However, using case insensitive names is bad as it requires scanning the \f(CW@INC\fR directories for any module matching the \&\s-1PLUGIN_BASE\s0 and caching the result (\s-1OK \-\s0 not that bad). .Sp If the plugin is not found and the \s-1LOAD_PERL\s0 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 \f(CW@INC\fR dirs for a matching file). .Sp .Vb 3 \& # The LOAD_PERL directive should be set to 1 \& [% USE ta = Template::Alloy %] \& [%~ ta.dump_parse_expr(\*(Aq2 * 3\*(Aq) %] .Ve .Sp Would print: .Sp .Vb 1 \& [[undef, \*(Aq*\*(Aq, 2, 3], 0]; .Ve .Sp See the \s-1PLUGIN_BASE,\s0 and \s-1PLUGINS\s0 configuration items. .Sp See the documentation for Template::Manual::Plugins. .ie n .IP """VIEW""" 4 .el .IP "\f(CWVIEW\fR" 4 .IX Item "VIEW" Implement a \s-1TT\s0 style view. For more information, please see the Template::View documentation. This \s-1DIRECTIVE\s0 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. .ie n .IP """WHILE""" 4 .el .IP "\f(CWWHILE\fR" 4 .IX Item "WHILE" Will process a block of code while a condition is true. .Sp .Vb 4 \& [% WHILE i < 3 %] \& [%~ i = i + 1 %] \& i = [% i %] \& [%~ END %] .Ve .Sp Would print: .Sp .Vb 3 \& i = 1 \& i = 2 \& i = 3 .Ve .Sp You could also do: .Sp .Vb 4 \& [% i = 4 %] \& [% WHILE (i = i \- 1) %] \& i = [% i %] \& [%~ END %] .Ve .Sp Would print: .Sp .Vb 3 \& i = 3 \& i = 2 \& i = 1 .Ve .Sp Note that (f = f \- 1) is a valid expression that returns the value of the assignment. The parenthesis are not optional. .Sp \&\s-1WHILE\s0 has a built in limit of 1000 iterations. This is controlled by the global variable \f(CW$WHILE_MAX\fR in Template::Alloy. .Sp \&\s-1WHILE\s0 may also be used as a post operative directive. .Sp .Vb 1 \& [% "$i" WHILE (i = i + 1) < 7 %] => 123456 .Ve .ie n .IP """WRAPPER""" 4 .el .IP "\f(CWWRAPPER\fR" 4 .IX Item "WRAPPER" Block directive. Processes contents of its block and then passes them in the [% content %] variable to the block or filename listed in the \&\s-1WRAPPER\s0 tag. .Sp .Vb 3 \& [% WRAPPER foo b = 23 %] \& My content to be processed ([% b %]).[% a = 2 %] \& [% END %] \& \& [% BLOCK foo %] \& A header ([% a %]). \& [% content %] \& A footer ([% a %]). \& [% END %] .Ve .Sp This would print. .Sp .Vb 3 \& A header (2). \& My content to be processed (23). \& A footer (2). .Ve .Sp The \s-1WRAPPER\s0 directive may also be used as a post operative directive. .Sp .Vb 2 \& [% BLOCK baz %]([% content %])[% END \-%] \& [% "foobar" WRAPPER baz %] .Ve .Sp Would print .Sp .Vb 1 \& (foobar)\*(Aq); .Ve .Sp Multiple filenames can be passed by separating them with a plus, a space, or commas (\s-1TT2\s0 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. .Sp .Vb 2 \& [% WRAPPER "path/to/outer.html", \& "path/to/inner.html" a = "An arg" b = "Another arg" %] .Ve .SH "DIRECTIVES (HTML::Template Style)" .IX Header "DIRECTIVES (HTML::Template Style)" HTML::Template templates use directives that look similar to the following: .PP .Vb 1 \& \& \& \& BAR \& .Ve .PP The normal set of HTML::Template directives are \s-1TMPL_VAR, TMPL_IF, TMPL_ELSE, TMPL_UNLESS, TMPL_INCLUDE,\s0 and \s-1TMPL_LOOP.\s0 These tags should have either a \s-1NAME\s0 attribute, an \s-1EXPR\s0 attribute, or a bare variable name that is used to specify the value to be operated. If a \s-1NAME\s0 is specified, it may only be a single level value (as opposed to a \s-1TT\s0 chained variable). In the case of the \s-1TMPL_INCLUDE\s0 directive, the \s-1NAME\s0 is the file to be included. .PP In Alloy, the \s-1EXPR\s0 attribute can be used with any of these types to specify \s-1TT\s0 compatible variable or expression that will be used for the value. .PP .Vb 3 \& Prints the value contained in foo \& Prints the value contained in foo \& Prints the value contained in foo \& \& Prints the value contained in {\*(Aqfoo.bar.baz\*(Aq} \& Prints the value contained in {foo}\->{bar}\->{baz} \& \& Prints FOO if foo is true \& FOO \& Prints FOO unless foo is true \& FOO \& Includes the template in "foo.ht" \& \& Iterates on the arrayref foo \& \& .Ve .PP Template::Alloy makes all of the other \s-1TT3\s0 directives available in addition to the normal set of HTML::Template directives. For example, the following is valid in Alloy. .PP .Vb 2 \& You said \& .Ve .PP The \s-1TMPL_VAR\s0 tag may also include an optional \s-1ESCAPE\s0 attribute. This specifies how the value of the tag should be escaped prior to substituting into the template. .PP .Vb 6 \& Escape value | Type of escape \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& HTML, 1 | HTML encoding \& URL | URL encoding \& JS | basic javascript encoding (\en, \er, and \e") \& NONE, 0 | No encoding (default). .Ve .PP The \s-1TMPL_VAR\s0 tag may also include an optional \s-1DEFAULT\s0 attribute that contains a string that will be used if the variable returns false. .PP .Vb 1 \& .Ve .SH "CHOMPING" .IX Header "CHOMPING" 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. .PP Additionally, the \s-1PRE_CHOMP\s0 and \s-1POST_CHOMP\s0 configuration variables can be set and will globally control all chomping behavior for tags that do not have their own chomp modifier. \s-1PRE_CHOMP\s0 and \s-1POST_CHOMP\s0 can be set to any of the following values: .PP .Vb 4 \& none: 0 + Template::Constants::CHOMP_NONE \& one: 1 \- Template::Constants::CHOMP_ONE \& collapse: 2 = Template::Constants::CHOMP_COLLAPSE \& greedy: 3 ~ Template::Constants::CHOMP_GREEDY .Ve .IP "\s-1CHOMP_NONE\s0" 4 .IX Item "CHOMP_NONE" Don't do any chomping. The \*(L"+\*(R" sign is used to indicate \s-1CHOMP_NONE.\s0 .Sp .Vb 1 \& Hello. \& \& [%+ "Hi." +%] \& \& Howdy. .Ve .Sp Would print: .Sp .Vb 1 \& Hello. \& \& Hi. \& \& Howdy. .Ve .IP "\s-1CHOMP_ONE \s0(formerly known as \s-1CHOMP_ALL\s0)" 4 .IX Item "CHOMP_ONE (formerly known as CHOMP_ALL)" Delete any whitespace up to the adjacent newline. The \*(L"\-\*(R" is used to indicate \s-1CHOMP_ONE.\s0 .Sp .Vb 1 \& Hello. \& \& [%\- "Hi." \-%] \& \& Howdy. .Ve .Sp Would print: .Sp .Vb 3 \& Hello. \& Hi. \& Howdy. .Ve .IP "\s-1CHOMP_COLLAPSE\s0" 4 .IX Item "CHOMP_COLLAPSE" Collapse adjacent whitespace to a single space. The \*(L"=\*(R" is used to indicate \s-1CHOMP_COLLAPSE.\s0 .Sp .Vb 1 \& Hello. \& \& [%= "Hi." =%] \& \& Howdy. .Ve .Sp Would print: .Sp .Vb 1 \& Hello. Hi. Howdy. .Ve .IP "\s-1CHOMP_GREEDY\s0" 4 .IX Item "CHOMP_GREEDY" Remove all adjacent whitespace. The \*(L"~\*(R" is used to indicate \s-1CHOMP_GREEDY.\s0 .Sp .Vb 1 \& Hello. \& \& [%~ "Hi." ~%] \& \& Howdy. .Ve .Sp Would print: .Sp .Vb 1 \& Hello.Hi.Howdy. .Ve .SH "CONFIGURATION" .IX Header "CONFIGURATION" The following configuration variables are supported (in alphabetical order). Note: for further discussion you can refer to the \s-1TT\s0 config documentation. .PP Items may be passed in upper or lower case. If lower case names are passed they will be resolved to uppercase during the \*(L"new\*(R" method. .PP All of the variables in this section can be passed to the \*(L"new\*(R" constructor. .PP .Vb 7 \& my $obj = Template::Alloy\->new( \& VARIABLES => \e%hash_of_variables, \& AUTO_RESET => 0, \& TRIM => 1, \& POST_CHOMP => "=", \& PRE_CHOMP => "\-", \& ); .Ve .IP "\s-1ABSOLUTE\s0" 4 .IX Item "ABSOLUTE" Boolean. Default false. Are absolute paths allowed for included files. .IP "\s-1ADD_LOCAL_PATH\s0" 4 .IX Item "ADD_LOCAL_PATH" If true, allows calls include_filename to temporarily add the directory of the current template being processed to the \s-1INCLUDE_PATHS\s0 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 \s-1INCLUDE_PATHS.\s0 .Sp This property may also be set in the template using the \s-1CONFIG\s0 directive. .Sp .Vb 1 \& [% CONFIG ADD_LOCAL_PATH => 1 %] .Ve .IP "\s-1ANYCASE\s0" 4 .IX Item "ANYCASE" Allow directive matching to be case insensitive. .Sp .Vb 1 \& [% get 23 %] prints 23 with ANYCASE => 1 .Ve .IP "\s-1AUTO_RESET\s0" 4 .IX Item "AUTO_RESET" Boolean. Default 1. Clear blocks that were set during the process method. .IP "\s-1AUTO_EVAL\s0" 4 .IX Item "AUTO_EVAL" 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 \s-1CONFIG\s0 directive. .IP "\s-1AUTO_FILTER\s0" 4 .IX Item "AUTO_FILTER" Can be the name of any filter. Default undef. Any variable returned by a \&\s-1GET\s0 directive (including implicit \s-1GET\s0) will be passed to the named filter. This configuration option may also be passed to the \s-1CONFIG\s0 directive. .Sp .Vb 1 \& # with AUTO_FILTER => \*(Aqhtml\*(Aq \& \& [% f = "&"; GET f %] prints & \& [% f = "&"; f %] prints & (implicit GET) .Ve .Sp If a variable already has another filter applied the \s-1AUTO_FILTER\s0 is not applied. The \*(L"none\*(R" scalar virtual method has been added to allow for using variables without reapplying filters. .Sp .Vb 1 \& # with AUTO_FILTER => \*(Aqhtml\*(Aq \& \& [% 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) .Ve .IP "\s-1BLOCKS\s0" 4 .IX Item "BLOCKS" Only available via when using the process interface. .Sp A hashref of blocks that can be used by the process method. .Sp .Vb 4 \& BLOCKS => { \& block_1 => sub { ... }, # coderef that returns a block \& block_2 => \*(AqA String\*(Aq, # simple string \& }, .Ve .Sp Note that a Template::Document cannot be supplied as a value (\s-1TT\s0 supports this). However, it is possible to supply a value that is equal to the hashref returned by the load_template method. .IP "\s-1CACHE_SIZE\s0" 4 .IX Item "CACHE_SIZE" 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. .IP "\s-1CACHE_STR_REFS\s0" 4 .IX Item "CACHE_STR_REFS" Default 1. If set, any string refs will have an \s-1MD5\s0 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 \s-1EVALUATE\s0 directive or eval filters as well. It may be set using the \s-1CONFIG\s0 directive. .IP "\s-1CALL_CONTEXT \s0(Not in \s-1TT\s0)" 4 .IX Item "CALL_CONTEXT (Not in TT)" Can be one of 'item', 'list', or 'smart'. The default type is \&'smart'. The \s-1CALL_CONTEXT\s0 configuration specifies in what Perl context coderefs and methods used in the processed templates will be called. \s-1TT\s0 historically has avoided the distinction of item (scalar) vs list context. To avoid worrying about this, \s-1TT\s0 introduced 'smart' context. The \f(CW\*(C`@()\*(C'\fR and \f(CW\*(C`$()\*(C'\fR context specifiers make it easier to use \&\s-1CALL_CONTEXT\s0 in some situations. .Sp The following table shows the relationship between the various contexts: .Sp .Vb 10 \& return values smart context list context item context \& \-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\- \& A \*(Aqfoo\*(Aq \*(Aqfoo\*(Aq [\*(Aqfoo\*(Aq] \*(Aqfoo\*(Aq \& 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 .Ve .Sp Cases F, H, I and M are common sticking points of the smart context in \s-1TT2. \s0 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. .Sp The list and item context provide another feature for method calls. In smart context, \s-1TT\s0 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. .Sp The \s-1CALL_CONTEXT\s0 configuration item can be passed to new or it may also be set during runtime using the \s-1CONFIG\s0 directive. The following method call would be in list context: .Sp .Vb 4 \& [% CONFIG CALL_CONTEXT => \*(Aqlist\*(Aq; \& results = my_obj.get_results; \& CONFIG CALL_CONTEXT => \*(Aqsmart\*(Aq \& %] .Ve .Sp Note that we needed to restore \s-1CALL_CONTEXT\s0 to the default 'smart' value. Template::Alloy has added the \f(CW\*(C`@()\*(C'\fR (list) and the \f(CW\*(C`$()\*(C'\fR (item) context specifiers. The previous example could be written as: .Sp .Vb 1 \& [% results = @( my_obj.get_results ) %] .Ve .Sp To call that same method in item (scalar) context you would do the following: .Sp .Vb 1 \& [% results = $( my_obj.get_results ) %] .Ve .Sp The \f(CW\*(C`@()\*(C'\fR and \f(CW\*(C`$()\*(C'\fR operators are based on the Perl 6 counterpart. .IP "\s-1COMPILE_DIR\s0" 4 .IX Item "COMPILE_DIR" Base directory to store compiled templates. Default undef. Compiled templates will only be stored if one of \s-1COMPILE_DIR\s0 and \s-1COMPILE_EXT\s0 is set. .Sp If set, the \s-1AST\s0 of parsed documents will be cached. If \s-1COMPILE_PERL\s0 is set, the compiled perl code will also be stored. .IP "\s-1COMPILE_EXT\s0" 4 .IX Item "COMPILE_EXT" Extension to add to stored compiled template filenames. Default undef. .Sp If set, the \s-1AST\s0 of parsed documents will be cached. If \s-1COMPILE_PERL\s0 is set, the compiled perl code will also be stored. .IP "\s-1COMPILE_JS\s0" 4 .IX Item "COMPILE_JS" Default false. .Sp 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. .Sp If your templates are short, there is little benefit to using this other than you can then use the \s-1JS\s0 directive. If your templates are long or you are running in a cached environment, this will speed up your templates. .Sp Certain limitations exist when \s-1COMPILE_JS\s0 is set, most notably the \s-1USE\s0 and \s-1VIEW\s0 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 \s-1OO\s0 differences. .IP "\s-1COMPILE_PERL\s0" 4 .IX Item "COMPILE_PERL" Default false. .Sp If set to 1 or 2, will translate the normal \s-1AST\s0 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. .Sp If set to 1, a perl code document will always be generated. .Sp If set to 2, a perl code document will only be generated if an \s-1AST\s0 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. .Sp 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). .Sp If you are not running in a cached environment, such as from commandline, or from \&\s-1CGI,\s0 it is generally faster to only run from the \s-1AST \s0(with \s-1COMPILE_PERL\s0 => 0). .IP "\s-1CONSTANTS\s0" 4 .IX Item "CONSTANTS" Hashref. Used to define variables that will be \*(L"folded\*(R" into the compiled template. Variables defined here cannot be overridden. .Sp .Vb 1 \& CONSTANTS => {my_constant => 42}, \& \& A template containing: \& \& [% constants.my_constant %] \& \& Will have the value 42 compiled in. .Ve .Sp Constants defined in this way can be chained as in [% constant.foo.bar.baz %]. .IP "\s-1CONSTANT_NAMESPACE\s0" 4 .IX Item "CONSTANT_NAMESPACE" Allow for setting the top level of values passed in \s-1CONSTANTS. \s0 Default value is 'constants'. .IP "\s-1DEBUG\s0" 4 .IX Item "DEBUG" Takes a list of constants |'ed together which enables different debugging modes. Alternately the lowercase names may be used (multiple values joined by a \*(L",\*(R"). .Sp .Vb 4 \& 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 => \*(Aqundef, dirs\*(Aq, # preferred \& DEBUG => 2 | 8, \& DEBUG => DEBUG_UNDEF | DEBUG_DIRS, # constants from Template::Constants .Ve .IP "\s-1DEBUG_FORMAT\s0" 4 .IX Item "DEBUG_FORMAT" Change the format of messages inserted when \s-1DEBUG\s0 has \s-1DEBUG_DIRS\s0 set on. This essentially the same thing as setting the format using the \s-1DEBUG\s0 directive. .IP "\s-1DEFAULT\s0" 4 .IX Item "DEFAULT" The name of a default template file to use if the passed one is not found. .IP "\s-1DELIMITER\s0" 4 .IX Item "DELIMITER" String to use to split \s-1INCLUDE_PATH\s0 with. Default is :. It is more straight forward to just send \s-1INCLUDE_PATH\s0 an arrayref of paths. .IP "\s-1DUMP\s0" 4 .IX Item "DUMP" Configures the behavior of the \s-1DUMP\s0 tag. May be set to 0, a hashref, or another true value. Default is true. .Sp If set to 0, all \s-1DUMP\s0 directives will do nothing. This is useful if you would like to turn off the \s-1DUMP\s0 directives under some environments. .Sp \&\s-1IF\s0 set to a true value (or undefined) then \s-1DUMP\s0 directives will operate. .Sp If set to a hashref, the values of the hash can be used to configure the operation of the \s-1DUMP\s0 directives. The following are the values that can be set in this hash. .RS 4 .IP "EntireStash" 4 .IX Item "EntireStash" Default 1. If set to 0, then the \s-1DUMP\s0 directive will not print the entire contents of the stash when a \s-1DUMP\s0 directive is called without arguments. .IP "handler" 4 .IX Item "handler" Defaults to an internal coderef. If set to a coderef, the \s-1DUMP\s0 directive will pass the arguments to be dumped and expects a string with the dumped data. This gives complete control over the dump process. .Sp 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. .Sp Note 2: If you would like the name of the variable to be dumped, include the string '$VAR1' and the \s-1DUMP\s0 directive will interpolate the value. For example, to dump all output as \s-1YAML \-\s0 you could do the following: .Sp .Vb 6 \& DUMP => { \& handler => sub { \& require YAML; \& return "\e$VAR1 =\en".YAML::Dump(shift); \& }, \& } .Ve .IP "header" 4 .IX Item "header" Default 1. Controls whether a header is printed for each \s-1DUMP\s0 directive. The header contains the file and line number the \s-1DUMP\s0 directive was called from. If set to 0 the headers are disabled. .IP "html" 4 .IX Item "html" Defaults to 1 if \f(CW$ENV\fR{'\s-1REQUEST_METHOD\s0'} is set \- 0 otherwise. If set to 1, then the output of the \s-1DUMP\s0 directive is passed to the html filter and encased in \*(L"pre\*(R" tags. If set to 0 no html encoding takes place. .IP "Sortkeys, Useqq, Ident, Pad, etc" 4 .IX Item "Sortkeys, Useqq, Ident, Pad, etc" Any of the Data::Dumper configuration items may be passed. .RE .RS 4 .RE .IP "\s-1ENCODING\s0" 4 .IX Item "ENCODING" 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 \s-1ENCODING\s0 and text from the template. .Sp This item can also be set using [% \s-1CONFIG ENCODING\s0 => encoding %] before calling \s-1INCLUDE\s0 or \s-1PROCESS\s0 directives to change encodings on the fly. .IP "\s-1END_TAG\s0" 4 .IX Item "END_TAG" Set a string to use as the closing delimiter for \s-1TT. \s0 Default is \*(L"%]\*(R". .IP "\s-1ERROR\s0" 4 .IX Item "ERROR" 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 \s-1TRY/CATCH/THROW\s0 directives (see those directives for more information). .Sp .Vb 3 \& my $t = Template::Alloy\->new({ \& ERROR => \*(Aqgeneral/catch_all_errors.html\*(Aq, \& }); \& \& my $t = Template::Alloy\->new({ \& ERROR => { \& default => \*(Aqgeneral/catch_all_errors.html\*(Aq, \& foo => \*(Aqcatch_all_general_foo_errors.html\*(Aq, \& \*(Aqfoo.bar\*(Aq => \*(Aqcatch_foo_bar_errors.html\*(Aq, \& }, \& }); .Ve .Sp Note that the \s-1ERROR\s0 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 \s-1PRE_PROCESS, POST_PROCESS,\s0 and \s-1WRAPPER\s0 configuration items. .IP "\s-1ERRORS\s0" 4 .IX Item "ERRORS" Same as the \s-1ERROR\s0 configuration item. Both may be used interchangeably. .IP "\s-1EVAL_PERL\s0" 4 .IX Item "EVAL_PERL" Boolean. Default false. If set to a true value, \s-1PERL\s0 and \s-1RAWPERL\s0 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 \s-1EVAL_PERL\s0 value also allows the perl and evalperl filters to be used. .IP "\s-1FILTERS\s0" 4 .IX Item "FILTERS" Allow for passing in \s-1TT\s0 style filters. .Sp .Vb 5 \& 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(\e$str) || die $obj\->error; .Ve .Sp Would print: .Sp .Vb 3 \& 1 (11111) \& 2 (22222) \& 3 (33333) .Ve .Sp 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. .IP "\s-1GLOBAL_CACHE\s0" 4 .IX Item "GLOBAL_CACHE" Default 0. If true, documents will be cached in \f(CW$Template::Alloy::GLOBAL_CACHE\fR. It may also be passed a hashref, in which case the documents will be cached in the passed hashref. .Sp The \s-1TT,\s0 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 \&\s-1CACHE\s0 configuration is the same as setting \s-1GLOBAL_CACHE.\s0 .IP "\s-1INCLUDE_PATH\s0" 4 .IX Item "INCLUDE_PATH" A string or an arrayref or coderef that returns an arrayref that contains directories to look for files included by processed templates. Defaults to \*(L".\*(R" (the current directory). .IP "\s-1INCLUDE_PATHS\s0" 4 .IX Item "INCLUDE_PATHS" Non-TT item. Same as \s-1INCLUDE_PATH\s0 but only takes an arrayref. If not specified then \s-1INCLUDE_PATH\s0 is turned into an arrayref and stored in \s-1INCLUDE_PATHS.\s0 Overrides \s-1INCLUDE_PATH.\s0 .IP "\s-1INTERPOLATE\s0" 4 .IX Item "INTERPOLATE" Boolean. Specifies whether variables in text portions of the template will be interpolated. For example, the \f(CW$variable\fR and ${var.value} would be substituted with the appropriate values from the variable cache (if \s-1INTERPOLATE\s0 is on). .Sp .Vb 1 \& [% IF 1 %]The variable $variable had a value ${var.value}[% END %] .Ve .IP "\s-1LOAD_PERL\s0" 4 .IX Item "LOAD_PERL" Indicates if the \s-1USE\s0 directive can fall back and try and load a perl module if the indicated module was not found in the \s-1PLUGIN_BASE\s0 path. See the \&\s-1USE\s0 directive. This configuration has no bearing on the \s-1COMPILE_PERL\s0 directive used to indicate using compiled perl documents. .IP "\s-1MAX_EVAL_RECURSE \s0(Alloy only)" 4 .IX Item "MAX_EVAL_RECURSE (Alloy only)" Will use \f(CW$Template::Alloy::MAX_EVAL_RECURSE\fR if not present. Default is 50. Prevents runaway on the following: .Sp .Vb 1 \& [% f = "[% f|eval %]" %][% f|eval %] .Ve .IP "\s-1MAX_MACRO_RECURSE \s0(Alloy only)" 4 .IX Item "MAX_MACRO_RECURSE (Alloy only)" Will use \f(CW$Template::Alloy::MAX_MACRO_RECURSE\fR if not present. Default is 50. Prevents runaway on the following: .Sp .Vb 1 \& [% MACRO f BLOCK %][% f %][% END %][% f %] .Ve .IP "\s-1NAMESPACE\s0" 4 .IX Item "NAMESPACE" No Template::Namespace::Constants support. Hashref of hashrefs representing constants that will be folded into the template at compile time. .Sp .Vb 3 \& Template::Alloy\->new(NAMESPACE => {constants => { \& foo => \*(Aqbar\*(Aq, \& }}); .Ve .Sp Is the same as .Sp .Vb 3 \& Template::Alloy\->new(CONSTANTS => { \& foo => \*(Aqbar\*(Aq, \& }); .Ve .Sp Any number of hashes can be added to the \s-1NAMESPACE\s0 hash. .IP "\s-1NEGATIVE_STAT_TTL \s0(Not in \s-1TT\s0)" 4 .IX Item "NEGATIVE_STAT_TTL (Not in TT)" Defaults to \s-1STAT_TTL\s0 which defaults to \f(CW$STAT_TTL\fR which defaults to 1. .Sp Similar to \s-1STAT_TTL \-\s0 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. .IP "\s-1NO_INCLUDES\s0" 4 .IX Item "NO_INCLUDES" Default false. If true, calls to \s-1INCLUDE, PROCESS, WRAPPER\s0 and \s-1INSERT\s0 will fail. This option is also available when using the process method. .IP "\s-1OUTPUT\s0" 4 .IX Item "OUTPUT" Alternate way of passing in the output location for processed templates. If process is not passed an output argument, it will look for this value. .Sp See the process method for a listing of possible values. .IP "\s-1OUTPUT_PATH\s0" 4 .IX Item "OUTPUT_PATH" Base path for files written out via the process method or via the redirect and file filters. See the redirect virtual method and the process method for more information. .IP "\s-1PLUGINS\s0" 4 .IX Item "PLUGINS" A hashref of mappings of plugin modules. .Sp .Vb 4 \& PLUGINS => { \& Iterator => \*(AqTemplate::Plugin::Iterator\*(Aq, \& DBI => \*(AqMyDBI\*(Aq, \& }, .Ve .Sp See the \s-1USE\s0 directive for more information. .IP "\s-1PLUGIN_BASE\s0" 4 .IX Item "PLUGIN_BASE" Default value is Template::Plugin. The base module namespace that template plugins will be looked for. See the \s-1USE\s0 directive for more information. May be either a single namespace, or an arrayref of namespaces. .IP "\s-1POST_CHOMP\s0" 4 .IX Item "POST_CHOMP" Set the type of chomping at the ending of a tag. See the section on chomping for more information. .IP "\s-1POST_PROCESS\s0" 4 .IX Item "POST_PROCESS" Only available via when using the process interface. .Sp A list of templates to be processed and appended to the content after the main template. During this processing the \*(L"template\*(R" namespace will contain the name of the main file being processed. .Sp This is useful for adding a global footer to all templates. .IP "\s-1PRE_CHOMP\s0" 4 .IX Item "PRE_CHOMP" Set the type of chomping at the beginning of a tag. See the section on chomping for more information. .IP "\s-1PRE_DEFINE\s0" 4 .IX Item "PRE_DEFINE" Same as the \s-1VARIABLES\s0 configuration item. .IP "\s-1PRE_PROCESS\s0" 4 .IX Item "PRE_PROCESS" Only available via when using the process interface. .Sp A list of templates to be processed before and pre-pended to the content before the main template. During this processing the \*(L"template\*(R" namespace will contain the name of the main file being processed. .Sp This is useful for adding a global header to all templates. .IP "\s-1PROCESS\s0" 4 .IX Item "PROCESS" Only available via when using the process interface. .Sp Specify a file to use as the template rather than the one passed in to the \->process method. .IP "\s-1RECURSION\s0" 4 .IX Item "RECURSION" Boolean. Default false. Indicates that \s-1INCLUDED\s0 or \s-1PROCESSED\s0 files can refer to each other in a circular manner. Be careful about recursion. .IP "\s-1RELATIVE\s0" 4 .IX Item "RELATIVE" Boolean. Default false. If true, allows filenames to be specified that are relative to the currently running process. .IP "\s-1SEMICOLONS\s0" 4 .IX Item "SEMICOLONS" 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. .IP "\s-1SHOW_UNDEFINED_INTERP \s0(Not in \s-1TT\s0)" 4 .IX Item "SHOW_UNDEFINED_INTERP (Not in TT)" Default false (default true in Velocity). If \s-1INTERPOLATE\s0 is true, interpolated dollar variables that return undef will be removed. With \&\s-1SHOW_UNDEFINED_INTERP\s0 set, undef values will leave the variable there. .Sp .Vb 3 \& [% CONFIG INTERPOLATE => 1 %] \& [% SET foo = 1 %][% SET bar %] \& ($foo)($bar) ($!foo)($!bar) .Ve .Sp Would print: .Sp .Vb 1 \& (1)() (1)() .Ve .Sp But the following: .Sp .Vb 3 \& [% CONFIG INTERPOLATE => 1, SHOW_UNDEFINED_INTERP => 1 %] \& [% SET foo = 1 %][% SET bar %] \& ($foo)($bar) ($!foo)($!bar) .Ve .Sp Would print: .Sp .Vb 1 \& (1)($bar) (1)() .Ve .Sp Note that you can use an exclamation point directly after the dollar to make the variable silent. This is similar to how Velocity works. .IP "\s-1START_TAG\s0" 4 .IX Item "START_TAG" Set a string or regular expression to use as the opening delimiter for \s-1TT. \s0 Default is \*(L"[%\*(R". You should be sure that the tag does not include grouping parens or \&\s-1INTERPOLATE\s0 will not function properly. .IP "\s-1STASH\s0" 4 .IX Item "STASH" 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 \s-1STASH\s0 object. The \s-1STASH\s0 option is only available when using the process method. .IP "\s-1STAT_TTL\s0" 4 .IX Item "STAT_TTL" Defaults to \f(CW$STAT_TTL\fR 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. .IP "\s-1STREAM\s0" 4 .IX Item "STREAM" Defaults to false. If set to true, generated template content will be printed to the currently selected filehandle (default is \s-1STDOUT\s0) as soon as it is ready \- there will be no buffering of the output. .Sp The Stream role uses the Play role's directives (non\-compiled_perl). .Sp All directives and configuration work, except for the following exceptions: .RS 4 .IP "\s-1CLEAR\s0 directive" 4 .IX Item "CLEAR directive" Because the output is not buffered \- the \s-1CLEAR\s0 directive would have no effect. The \s-1CLEAR\s0 directive will throw an error when \s-1STREAM\s0 is on. .IP "\s-1TRIM\s0 configuration" 4 .IX Item "TRIM configuration" Because the output is not buffered \- trim operations cannot be played on the output buffers. .IP "\s-1WRAPPER\s0 configuration/directive" 4 .IX Item "WRAPPER configuration/directive" The \s-1WRAPPER\s0 configuration and directive items effectively turn off \&\s-1STREAM\s0 since the \s-1WRAPPERS\s0 are generated in reverse order and because the content is inserted into the middle of the \s-1WRAPPERS. WRAPPERS\s0 will still work, they just won't stream. .IP "\s-1VARIOUS\s0 errors" 4 .IX Item "VARIOUS errors" Because the template is streaming, items that cause errors my result in partially printed pages \- since the error would occur part way through the print. .RE .RS 4 .Sp All output is printed directly to the currently selected filehandle (defaults to \s-1STDOUT\s0) via the CORE::print function. Any output parameter passed to process or process_simple will be ignored. .Sp If you would like the output to go to another handle, you will need to select that handle, process the template, and re-select \s-1STDOUT.\s0 .RE .IP "\s-1STRICT\s0" 4 .IX Item "STRICT" 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 \s-1TRY\s0 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 \*(L"use strict.\*(R" .Sp When this occurs the strict_throw method is called. .Sp See the \s-1STRICT_THROW\s0 configuration for additional options. .Sp Similar functionality could be implemented using \s-1UNDEFINED_ANY.\s0 .Sp The \s-1STRICT\s0 configuration item can be passed to new or it may also be set during runtime using the \s-1CONFIG\s0 directive. Once set though it cannot be disabled for the duration of the current template and sub components. For example you could call [% \s-1CONFIG STRICT\s0 => 1 %] in header.tt and strict mode would be enabled for the header.tt and any sub templates processed by header.tt. .IP "\s-1STRICT_THROW \s0(not in \s-1TT\s0)" 4 .IX Item "STRICT_THROW (not in TT)" Default undef. Can be set to a subroutine which will be called when \&\s-1STRICT\s0 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. .Sp .Vb 4 \& my $ta = Template::Alloy\->new({ \& STRICT => 1, \& STRICT_THROW => sub { \& my ($ta, $err_type, $msg, $args) = @_; \& \& return if $args\->{\*(Aqcomponent\*(Aq} eq \*(Aqheader.tt\*(Aq \& && $args\->{\*(Aqtemplate\*(Aq} eq \*(Aqmain.html\*(Aq \& && $args\->{\*(Aqname\*(Aq} eq \*(Aqfoo.bar(1)\*(Aq; # stringified identity name \& \& $ta\->throw($err_type, $msg); # all other undefined variables die \& }, \& }); .Ve .IP "\s-1SYNTAX \s0(not in \s-1TT\s0)" 4 .IX Item "SYNTAX (not in TT)" Defaults to \*(L"cet\*(R". Indicates the syntax that will be used for parsing included templates or eval'ed strings. You can use the \s-1CONFIG\s0 directive to change the \s-1SYNTAX\s0 on the fly (it will not affect the syntax of the document currently being parsed). .Sp The syntax may be passed in upper or lower case. .Sp The available choices are: .Sp .Vb 8 \& 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. .Ve .Sp 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. .Sp The following is a sample of HTML::Template interface usage parsing a Template::Toolkit style document. .Sp .Vb 4 \& my $obj = Template::Alloy\->new(filename => \*(Aqmy/template.tt\*(Aq \& syntax => \*(Aqcet\*(Aq); \& $obj\->param(\e%swap); \& print $obj\->output; .Ve .Sp The following is a sample of Template::Toolkit interface usage parsing a HTML::Template::Expr style document. .Sp .Vb 2 \& my $obj = Template::Alloy\->new(SYNTAX => \*(Aqhte\*(Aq); \& $obj\->process(\*(Aqmy/template.ht\*(Aq, \e%swap); .Ve .Sp You can use the define_syntax method to add another custom syntax to the list of available options. .IP "\s-1TAG_STYLE\s0" 4 .IX Item "TAG_STYLE" Allow for setting the type of tag delimiters to use for parsing the \s-1TT.\s0 See the \s-1TAGS\s0 directive for a listing of the available types. .IP "\s-1TRIM\s0" 4 .IX Item "TRIM" Remove leading and trailing whitespace from blocks and templates. This operation is performed after all enclosed template tags have been executed. .IP "\s-1UNDEFINED_ANY\s0" 4 .IX Item "UNDEFINED_ANY" This is not a \s-1TT\s0 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 \*(L"undefined\*(R" method of Template::Stash. It allows for the \*(L"auto-defining\*(R" of a variable for use in the template. It is suggested that \s-1UNDEFINED_GET\s0 be used instead as \s-1UNDEFINED_ANY\s0 is a little to general in defining variables. .Sp You can also sub class the module and override the undefined_any method. .IP "\s-1UNDEFINED_GET\s0" 4 .IX Item "UNDEFINED_GET" This is not a \s-1TT\s0 configuration option. This option expects to be a code ref that will be called if a variable is undefined during a call to \s-1GET.\s0 It is passed the variable identity array as a single argument. This is more useful than \s-1UNDEFINED_ANY\s0 in that it is only called during a \s-1GET\s0 directive rather than in embedded expressions (such as [% a || b || c %]). .Sp You can also sub class the module and override the undefined_get method. .IP "V1DOLLAR" 4 .IX Item "V1DOLLAR" This allows for some compatibility with \s-1TT1\s0 templates. The only real behavior change is that [% \f(CW$foo\fR %] becomes the same as [% foo %]. The following is a basic table of changes invoked by using V1DOLLAR. .Sp .Vb 10 \& 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}" .Ve .IP "V2EQUALS" 4 .IX Item "V2EQUALS" Default 1 in the \s-1TT\s0 syntax, defaults to 0 in the HTML::Template syntax. .Sp If set to 1 then \*(L"==\*(R" is an alias for \*(L"eq\*(R" and \*(L"!= is an alias for \&\*(R"ne". .Sp .Vb 2 \& [% CONFIG V2EQUALS => 1 %][% (\*(Aq7\*(Aq == \*(Aq7.0\*(Aq) || 0 %] \& [% CONFIG V2EQUALS => 0 %][% (\*(Aq7\*(Aq == \*(Aq7.0\*(Aq) || 0 %] \& \& Prints \& \& 0 \& 1 .Ve .IP "V2PIPE" 4 .IX Item "V2PIPE" Restores the behavior of the pipe operator to be compatible with \s-1TT2.\s0 .Sp With V2PIPE = 1 .Sp .Vb 3 \& [%\- 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 .Ve .Sp With V2PIPE = 0 (default) .Sp .Vb 3 \& [%\- 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 .Ve .IP "\s-1VARIABLES\s0" 4 .IX Item "VARIABLES" 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 \s-1VARIABLES\s0 for the types of information that can be passed in. .IP "\s-1VMETHOD_FUNCTIONS\s0" 4 .IX Item "VMETHOD_FUNCTIONS" Defaults to 1. All scalar virtual methods are available as top level functions as well. This is not true of \s-1TT2. \s0 In Template::Alloy the following are equivalent: .Sp .Vb 2 \& [% "abc".length %] \& [% length("abc") %] .Ve .Sp You may set \s-1VMETHOD_FUNCTIONS\s0 to 0 to disable this behavior. .IP "\s-1WRAPPER\s0" 4 .IX Item "WRAPPER" Only available via when using the process interface. .Sp Operates similar to the \s-1WRAPPER\s0 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). .Sp .Vb 3 \& my $t = Template::Alloy\->new( \& WRAPPER => [\*(Aqmy/wrappers/outer.html\*(Aq, \*(Aqmy/wrappers/inner.html\*(Aq], \& ); .Ve .Sp Content generated by the \s-1PRE_PROCESS\s0 and \s-1POST_PROCESS\s0 will come before and after (respectively) the content generated by the \s-1WRAPPER\s0 configuration item. .Sp See the \s-1WRAPPER\s0 directive for more examples of how wrappers are constructed. .SH "CONFIGURATION (HTML::Template STYLE)" .IX Header "CONFIGURATION (HTML::Template STYLE)" 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 \s-1HT\s0 documentation. Many of the variables mentioned in the \s-1TT CONFIGURATION\s0 section apply here as well. Unless noted, these items only apply when using the output method. .PP Items may be passed in upper or lower case. All passed items are resolved to upper case. .PP These variables should be passed to the \*(L"new\*(R" constructor. .PP .Vb 9 \& my $obj = Template::Alloy\->new( \& type => \*(Aqfilename\*(Aq, \& source => \*(Aqmy/template.ht\*(Aq, \& die_on_bad_params => 1, \& loop_context_vars => 1, \& global_vars => 1 \& post_chomp => "=", \& pre_chomp => "\-", \& ); .Ve .IP "\s-1TYPE\s0" 4 .IX Item "TYPE" Can be one of filename, filehandle, arrayref, or scalarref. Indicates what type of input is in the \*(L"source\*(R" configuration item. .IP "\s-1SOURCE\s0" 4 .IX Item "SOURCE" Stores where to read the input file. The type is specified in the \*(L"type\*(R" configuration item. .IP "\s-1FILENAME\s0" 4 .IX Item "FILENAME" Indicates a filename to read the template from. Same as putting the filename in the \*(L"source\*(R" item and setting \*(L"type\*(R" to \*(L"filename\*(R". .Sp Must be set to enable caching. .IP "\s-1FILEHANDLE\s0" 4 .IX Item "FILEHANDLE" Should contain an open filehandle to read the template from. Same as putting the filehandle in the \*(L"source\*(R" item and setting \*(L"type\*(R" to \*(L"filehandle\*(R". .Sp Will not be cached. .IP "\s-1ARRAYREF\s0" 4 .IX Item "ARRAYREF" Should contain an arrayref whose values are the lines of the template. Same as putting the arrayref in the \*(L"source\*(R" item and setting \*(L"type\*(R" to \*(L"arrayref\*(R". .Sp Will not be cached. .IP "\s-1SCALARREF\s0" 4 .IX Item "SCALARREF" Should contain an reference to a scalar that contains the template. Same as putting the scalar ref in the \*(L"source\*(R" item and setting \*(L"type\*(R" to \*(L"scalarref\*(R". .Sp Will not be cached. .IP "\s-1CACHE\s0" 4 .IX Item "CACHE" 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. .IP "\s-1BLIND_CACHE\s0" 4 .IX Item "BLIND_CACHE" Same as with cache enabled, but will not check if the document has been modified. .IP "\s-1FILE_CACHE\s0" 4 .IX Item "FILE_CACHE" If set to 1, will cache the compiled document on the file system. If true, file_cache_dir must be set. .IP "\s-1FILE_CACHE_DIR\s0" 4 .IX Item "FILE_CACHE_DIR" The directory where to store cached documents when file_cache is true. This is similar to the \s-1TT\s0 compile_dir option. .IP "\s-1DOUBLE_FILE_CACHE\s0" 4 .IX Item "DOUBLE_FILE_CACHE" Uses a combination of file_cache and cache. .IP "\s-1PATH\s0" 4 .IX Item "PATH" Same as \s-1INCLUDE_PATH\s0 when using the process method. .IP "\s-1ASSOCIATE\s0" 4 .IX Item "ASSOCIATE" May be a single \s-1CGI\s0 object or an arrayref of objects. The params from these objects will be added to the params during the output call. .IP "\s-1CASE_SENSITIVE\s0" 4 .IX Item "CASE_SENSITIVE" Allow passed variables set through the param method, or the associate configuration to be used case sensitively. Default is off. It is highly suggested that this be set to 1. .IP "\s-1LOOP_CONTEXT_VARS\s0" 4 .IX Item "LOOP_CONTEXT_VARS" Default false. When true, calls to the loop directive will create the following variables that give information about the current iteration of the loop: .Sp .Vb 5 \& _\|_first_\|_ \- True on first iteration only \& _\|_last_\|_ \- True on last iteration only \& _\|_inner_\|_ \- True on any iteration that isn\*(Aqt first or last \& _\|_odd_\|_ \- True on odd iterations \& _\|_counter_\|_ \- The iteration count .Ve .Sp These variables are also available to LOOPs run under \&\s-1TT\s0 syntax if loop_context_vars is set and if \s-1QR_PRIVATE\s0 is set to 0. .IP "\s-1GLOBAL_VARS.\s0" 4 .IX Item "GLOBAL_VARS." Default true in \s-1HTE\s0 mode. Default false in \s-1HT. \s0 Allows top level variables to be used in LOOPs. When false, only variables defined in the current \s-1LOOP\s0 iteration hashref will be available. .IP "\s-1DEFAULT_ESCAPE\s0" 4 .IX Item "DEFAULT_ESCAPE" Controls the type of escape used on named variables in \s-1TMPL_VAR\s0 directives. Can be one of \s-1HTML, URL,\s0 or \s-1JS. \s0 The values of \&\s-1TMPL_VAR\s0 directives will be encoded with this type unless they specify their own type via an \s-1ESCAPE\s0 attribute. .Sp You may alternately use the \s-1AUTO_FILTER\s0 directive which can be any of the item vmethod filters (you must use lower case when specifying the \s-1AUTO_FILTER\s0 directive). The \s-1AUTO_FILTER\s0 directive will also be applied to \s-1TMPL_VAR EXPR\s0 and \s-1TMPL_GET\s0 items while \&\s-1DEFAULT_ESCAPE\s0 only applies to \s-1TMPL_VAR NAME\s0 items. .IP "\s-1NO_TT\s0" 4 .IX Item "NO_TT" Default false in 'hte' syntax. Default true in 'ht' syntax. If true, no extended \s-1TT\s0 directives will be allowed. .Sp The output method uses 'hte' syntax by default. .SH "SEMI PUBLIC METHODS" .IX Header "SEMI PUBLIC METHODS" The following list of methods are other interesting methods of Alloy that may be re-implemented by subclasses of Alloy. .ie n .IP """exception""" 4 .el .IP "\f(CWexception\fR" 4 .IX Item "exception" Creates an exception object blessed into the package listed in Template::Alloy::Exception. .ie n .IP """execute_tree""" 4 .el .IP "\f(CWexecute_tree\fR" 4 .IX Item "execute_tree" Executes a parsed tree (returned from parse_tree) .ie n .IP """play_expr""" 4 .el .IP "\f(CWplay_expr\fR" 4 .IX Item "play_expr" 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. .ie n .IP """include_filename""" 4 .el .IP "\f(CWinclude_filename\fR" 4 .IX Item "include_filename" Takes a file path, and resolves it into the full filename using paths from \s-1INCLUDE_PATH\s0 or \s-1INCLUDE_PATHS.\s0 .ie n .IP """_insert""" 4 .el .IP "\f(CW_insert\fR" 4 .IX Item "_insert" Resolves the file passed, and then returns its contents. .ie n .IP """list_filters""" 4 .el .IP "\f(CWlist_filters\fR" 4 .IX Item "list_filters" Dynamically loads the filters list from Template::Filters when a filter is used that does not have a native implementation in Alloy. .ie n .IP """load_template""" 4 .el .IP "\f(CWload_template\fR" 4 .IX Item "load_template" Given a filename or a string reference will return a \*(L"document\*(R" hashref hash that contains the parsed tree. .Sp .Vb 1 \& my $doc = $self\->load_template($file); # errors die .Ve .Sp This method handles the in-memory caching of the document. .ie n .IP """load_tree""" 4 .el .IP "\f(CWload_tree\fR" 4 .IX Item "load_tree" Given the \*(L"document\*(R" hashref, will either load the parsed \s-1AST\s0 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 \s-1AST\s0 happens here. .ie n .IP """load_perl""" 4 .el .IP "\f(CWload_perl\fR" 4 .IX Item "load_perl" Only used if \s-1COMPILE_PERL\s0 is true (default is false). .Sp Given the \*(L"document\*(R" hashref, will either load the compiled perl from file (if configured to do so), or will load the \s-1AST\s0 using \*(L"load_tree\*(R", 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. .ie n .IP """parse_tree""" 4 .el .IP "\f(CWparse_tree\fR" 4 .IX Item "parse_tree" Parses the passed string ref with the appropriate template syntax. .Sp See Template::Alloy::Parse for more details. .ie n .IP """parse_expr""" 4 .el .IP "\f(CWparse_expr\fR" 4 .IX Item "parse_expr" Parses the passed string ref for a variable or expression. .Sp See Template::Alloy::Parse for more details. .ie n .IP """parse_args""" 4 .el .IP "\f(CWparse_args\fR" 4 .IX Item "parse_args" See Template::Alloy::Parse for more details. .ie n .IP """set_variable""" 4 .el .IP "\f(CWset_variable\fR" 4 .IX Item "set_variable" Used to set a variable. Expects a variable identity array and the value to set. It will autovifiy as necessary. .ie n .IP """strict_throw""" 4 .el .IP "\f(CWstrict_throw\fR" 4 .IX Item "strict_throw" Called during processing of template when \s-1STRICT\s0 configuration is set and an uninitialized variable is met. Arguments are the variable identity reference. Will call \s-1STRICT_THROW\s0 configuration item if set, otherwise will call throw with a useful message. .ie n .IP """throw""" 4 .el .IP "\f(CWthrow\fR" 4 .IX Item "throw" Creates an exception object from the arguments and dies. .ie n .IP """undefined_any""" 4 .el .IP "\f(CWundefined_any\fR" 4 .IX Item "undefined_any" 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 \s-1UNDEFINED_ANY\s0 configuration variable. Also, you can try using the \s-1DEBUG\s0 => 'undef', configuration option which will throw an error on undefined variables. .ie n .IP """undefined_get""" 4 .el .IP "\f(CWundefined_get\fR" 4 .IX Item "undefined_get" Called when a variable is undefined during a \s-1GET\s0 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 \s-1UNDEFINED_GET\s0 configuration variable. .SH "OTHER UTILITY METHODS" .IX Header "OTHER UTILITY METHODS" The following is a brief list of other methods used by Alloy. Generally, these shouldn't be overwritten by subclasses. .ie n .IP """ast_string""" 4 .el .IP "\f(CWast_string\fR" 4 .IX Item "ast_string" Returns perl code representation of a variable. .ie n .IP """context""" 4 .el .IP "\f(CWcontext\fR" 4 .IX Item "context" Used to create a \*(L"pseudo\*(R" context object that allows for portability of \s-1TT\s0 plugins, filters, and perl blocks that need a context object. Uses the Template::Alloy::Context class. .ie n .IP """debug_node""" 4 .el .IP "\f(CWdebug_node\fR" 4 .IX Item "debug_node" Used to get debug info on a directive if \s-1DEBUG_DIRS\s0 is set. .ie n .IP """get_line_number_by_index""" 4 .el .IP "\f(CWget_line_number_by_index\fR" 4 .IX Item "get_line_number_by_index" Used to turn string index position into line number .ie n .IP """interpolate_node""" 4 .el .IP "\f(CWinterpolate_node\fR" 4 .IX Item "interpolate_node" Used for parsing text nodes for dollar variables when interpolate is on. .ie n .IP """play_operator""" 4 .el .IP "\f(CWplay_operator\fR" 4 .IX Item "play_operator" Provided by the Operator role. Allows for playing an operator \s-1AST.\s0 .Sp See Template::Alloy::Operator for more details. .ie n .IP """apply_precedence""" 4 .el .IP "\f(CWapply_precedence\fR" 4 .IX Item "apply_precedence" Provided by the Parse role. Allows for parsed operator array to be translated to a tree based upon operator precedence. .ie n .IP """_process""" 4 .el .IP "\f(CW_process\fR" 4 .IX Item "_process" Called by process and the \s-1PROCESS, INCLUDE\s0 and other directives. .ie n .IP """slurp""" 4 .el .IP "\f(CWslurp\fR" 4 .IX Item "slurp" Reads contents of passed filename \- throws file exception on error. .ie n .IP """split_paths""" 4 .el .IP "\f(CWsplit_paths\fR" 4 .IX Item "split_paths" Used to split \s-1INCLUDE_PATH\s0 or other directives if an arrayref is not passed. .ie n .IP """tt_var_string""" 4 .el .IP "\f(CWtt_var_string\fR" 4 .IX Item "tt_var_string" Returns a template toolkit representation of a variable. .ie n .IP """_vars""" 4 .el .IP "\f(CW_vars\fR" 4 .IX Item "_vars" Return a reference to the current stash of variables. This is currently only used by the pseudo context object and may disappear at some point. .SH "THANKS" .IX Header "THANKS" Thanks to Andy Wardley for creating Template::Toolkit. .PP Thanks to Sam Tregar for creating HTML::Template. .PP Thanks to David Lowe for creating Text::Tmpl. .PP Thanks to the Apache Velocity guys. .PP Thanks to Ben Grimm for a patch to allow passing a parsed document to the \->process method. .PP Thanks to David Warring for finding a parse error in \s-1HTE\s0 syntax. .PP Thanks to Carl Franks for adding the base \s-1ENCODING\s0 support. .SH "AUTHOR" .IX Header "AUTHOR" Paul Seamons .SH "LICENSE" .IX Header "LICENSE" This module may be distributed under the same terms as Perl itself.