diff options
| author | Andreas Brachold <vdr07@deltab.de> | 2007-11-11 06:55:13 +0000 |
|---|---|---|
| committer | Andreas Brachold <vdr07@deltab.de> | 2007-11-11 06:55:13 +0000 |
| commit | 3282be229999dc36c197b264d63063a18d136331 (patch) | |
| tree | 98a42db29d955b39e7bed1b599fdcc56c3a29de9 /lib/Template/Manual/Variables.pod | |
| parent | cfdd733c17cfa4f1a43b827a656e9e53cc2524ac (diff) | |
| download | xxv-3282be229999dc36c197b264d63063a18d136331.tar.gz xxv-3282be229999dc36c197b264d63063a18d136331.tar.bz2 | |
* Update installation list with required modules
* Remove unused/doubled provided external perl moduls
Diffstat (limited to 'lib/Template/Manual/Variables.pod')
| -rw-r--r-- | lib/Template/Manual/Variables.pod | 868 |
1 files changed, 0 insertions, 868 deletions
diff --git a/lib/Template/Manual/Variables.pod b/lib/Template/Manual/Variables.pod deleted file mode 100644 index e8d998c..0000000 --- a/lib/Template/Manual/Variables.pod +++ /dev/null @@ -1,868 +0,0 @@ -#============================================================= -*-perl-*- -# -# Template::Manual::Variables -# -# DESCRIPTION -# This section describes the different ways in which Perl data can be -# bound to template variables and accessed via Template Toolkit -# directives. -# -# AUTHOR -# Andy Wardley <abw@andywardley.com> -# -# COPYRIGHT -# Copyright (C) 1996-2001 Andy Wardley. All Rights Reserved. -# Copyright (C) 1998-2001 Canon Research Centre Europe Ltd. -# -# This module is free software; you can redistribute it and/or -# modify it under the same terms as Perl itself. -# -# REVISION -# -# -#======================================================================== - - -#------------------------------------------------------------------------ -# IMPORTANT NOTE -# This documentation is generated automatically from source -# templates. Any changes you make here may be lost. -# -# The 'docsrc' documentation source bundle is available for download -# from http://www.template-toolkit.org/docs.html and contains all -# the source templates, XML files, scripts, etc., from which the -# documentation for the Template Toolkit is built. -#------------------------------------------------------------------------ - -=head1 NAME - -Template::Manual::Variables - Template variables and code bindings - -=head1 DESCRIPTION - -This section describes the different ways in which Perl data can be -bound to template variables and accessed via Template Toolkit -directives. - -=head2 Template Variables - -A reference to a hash array may be passed as the second argument to -the process() method, containing definitions of template variables. -The VARIABLES (a.k.a. PRE_DEFINE) option can also be used to pre-define -variables for all templates processed by the object. - - my $tt = Template->new({ - VARIABLES => { - version => 3.14, - release => 'Sahara', - }, - }); - - my $vars = { - serial_no => 271828, - }; - - $tt->process('myfile', $vars); - -'myfile': - - This is version [% version %] ([% release %]). - Serial number: [% serial_no %] - -output: - - This is version 3.14 (Sahara) - Serial number: 271828 - -Variable names may contain any alphanumeric characters or underscores. -They may be lower, upper or mixed case although the usual convention -is to use lower case. The case I<is> significant however, and 'foo', -'Foo' and 'FOO' are all different variables. Upper case variable -names are permitted, but not recommended due to a possible conflict -with an existing or future reserved word. As of version 2.00, these -are: - - GET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER - IF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE - USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META - TRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP - CLEAR TO STEP AND OR NOT MOD DIV END - - -The variable values may be of virtually any Perl type, including -simple scalars, references to lists, hash arrays, subroutines or -objects. The Template Toolkit will automatically apply the correct -procedure to accessing these values as they are used in the template. - -Example: - - my $vars = { - article => 'The Third Shoe', - person => { - id => 314, - name => 'Mr. Blue', - email => 'blue@nowhere.org', - }, - primes => [ 2, 3, 5, 7, 11, 13 ], - wizard => sub { return join(' ', 'Abracadabra!', @_) }, - cgi => CGI->new('mode=submit&debug=1'), - }; - -template: - - [% article %] - - [% person.id %]: [% person.name %] <[% person.email %]> - - [% primes.first %] - [% primes.last %], including [% primes.3 %] - [% primes.size %] prime numbers: [% primes.join(', ') %] - - [% wizard %] - [% wizard('Hocus Pocus!') %] - - [% cgi.param('mode') %] - -output: - - The Third Shoe - - 314: Mr. Blue <blue@nowhere.org> - - 2 - 13, including 7 - 6 prime numbers: 2, 3, 5, 7, 11, 13 - - Abracadabra! - Abracadabra! Hocus Pocus! - - submit - -=head2 Scalar Values - -Regular scalar variables are accessed by simply specifying their name. -As these are just entries in the top-level variable hash they can be -considered special cases of hash array referencing as described below, -with the main namespace hash automatically implied. - - [% article %] - -=head2 Hash Array References - -Members of hash arrays are accessed by specifying the hash reference -and key separated by the dot '.' operator. - - my $vars = { - 'home' => 'http://www.myserver.com/homepage.html', - 'page' => { - 'this' => 'mypage.html', - 'next' => 'nextpage.html', - 'prev' => 'prevpage.html', - }, - }; - -template: - - <a href="[% home %]">Home</a> - <a href="[% page.prev %]">Previous Page</a> - <a href="[% page.next %]">Next Page</a> - -output: - - <a href="http://www.myserver.com/homepage.html">Home</a> - <a href="prevpage.html">Previous Page</a> - <a href="nextpage.html">Next Page</a> - -Any key in a hash which starts with a '_' or '.' character will be -considered private and cannot be evaluated or updated from within a -template. The undefined value will be returned for any such variable -accessed which the Template Toolkit will silently ignore (unless the -DEBUG option is enabled). - - my $vars = { - message => 'Hello World!', - _secret => "On the Internet, no-one knows you're a dog", - thing => { - public => 123, - _private => 456, - '.hidden' => 789, - }, - }; - -template: - - [% message %] # outputs "Hello World!" - [% _secret %] # no output - [% thing.public %] # outputs "123" - [% thing._private %] # no output - [% thing..hidden %] # ERROR: unexpected token (..) - -To access a hash entry using a key stored in another variable, prefix -the key variable with '$' to have it interpolated before use (see -L<Variable Interpolation>). - - [% pagename = 'next' %] - [% page.$pagename %] # same as [% page.next %] - -When you assign to a variable that contains multiple namespace -elements (i.e. it has one or more '.' characters in the name), -any hashes required to represent intermediate namespaces will be -created automatically. In this following example, the 'product' -variable automatically springs into life as a hash array unless -otherwise defined. - - [% product.id = 'XYZ-2000' - product.desc = 'Bogon Generator' - product.price = 666 - %] - - The [% product.id %] [% product.desc %] - costs $[% product.price %].00 - -output: - - The XYZ-2000 Bogon Generator - costs $666.00 - -You can use Perl's familiar '{' ... '}' construct to explicitly create -a hash and assign it to a variable. Note that commas are optional -between key/value pairs and '=' can be used in place of '=E<gt>'. - - [% product = { - id => 'XYZ-2000', - desc => 'Bogon Generator', - price => 666, - } - %] - -=head2 List References - -Items in lists are also accessed by use of the dot operator. - - my $vars = { - 'people' => [ 'Tom', 'Dick', 'Larry' ], - }; - -template: - - [% people.0 %] # Tom - [% people.1 %] # Dick - [% people.2 %] # Larry - -The FOREACH directive can be used to iterate through items in a list. - - [% FOREACH person = people %] - Hello [% person %] - [% END %] - -output: - - Hello Tom - Hello Dick - Hello Larry - -Lists can be constructed in-situ using the regular anonymous list -'[' ... ']' construct. Commas between items are optional. - - [% cols = [ 'red', 'green', 'blue' ] %] - - [% FOREACH c = cols %] - ... - -or: - - [% FOREACH c = [ 'red', 'green', 'blue' ] %] - ... - -You can also create simple numerical sequences using the familiar '..' -operator: - - [% n = [ 1 .. 4 ] %] # n is [ 1, 2, 3, 4 ] - - [% x = 4 - y = 8 - z = [x..y] # z is [ 4, 5, 6, 7, 8 ] - %] - -=head2 Subroutines - -Template variables can contain references to Perl subroutines. When -the variable is used, the Template Toolkit will automatically call the -subroutine, passing any additional arguments specified. The return -value from the subroutine is used as the variable value and inserted -into the document output. - - my $vars = { - wizard => sub { return join(' ', 'Abracadabra!', @_) }, - }; - -template: - - [% wizard %] # Abracadabra! - [% wizard('Hocus Pocus!') %] # Abracadabra! Hocus Pocus! - - -=head2 Objects - -Template variables can also contain references to Perl objects. -Methods are called using the dot operator to specify the method -against the object variable. Additional arguments can be specified -as with subroutines. - - use CGI; - - ... - - my $vars = { - # hard coded CGI params for purpose of example - cgi => CGI->new('mode=submit&debug=1'), - }; - -template: - - [% FOREACH p = cgi.param %] # returns list of param keys - [% p %] => [% cgi.param(p) %] # fetch each param value - [% END %] - -output: - - mode => submit - debug => 1 - -Object methods can also be called as lvalues. That is, they can appear on -the left side of an assignment. The method will be called passing the -assigning value as an argument. - - [% myobj.method = 10 %] - -equivalent to: - - [% myobj.method(10) %] - -=head2 Parameters and Return Values - -Subroutines and methods will be passed any arguments specified in the -template. Any template variables in the argument list will first be -evaluated and their resultant values passed to the code. - - my $vars = { - mycode => sub { return 'received ' . join(', ', @_) }, - }; - -template: - - [% foo = 10 %] - [% mycode(foo, 20) %] # received 10, 20 - -Named parameters may also be specified. These are automatically collected -into a single hash array which is passed by reference as the B<last> -parameter to the sub-routine. Named parameters can be specified using -either '=E<gt>' or '=' and can appear anywhere in the argument list. - - my $vars = { - myjoin => \&myjoin, - }; - - sub myjoin { - # look for hash ref as last argument - my $params = ref $_[-1] eq 'HASH' ? pop : { }; - return join($params->{ joint } || ' + ', @_); - } - -template: - - [% myjoin(10, 20, 30) %] - [% myjoin(10, 20, 30, joint = ' - ' %] - [% myjoin(joint => ' * ', 10, 20, 30 %] - -output: - - 10 + 20 + 30 - 10 - 20 - 30 - 10 * 20 * 30 - -Parenthesised parameters may be added to any element of a variable, -not just those that are bound to code or object methods. At present, -parameters will be ignored if the variable isn't "callable" but are -supported for future extensions. Think of them as "hints" to that -variable, rather than just arguments passed to a function. - - [% r = 'Romeo' %] - [% r(100, 99, s, t, v) %] # outputs "Romeo" - -User code should return a value for the variable it represents. This -can be any of the Perl data types described above: a scalar, or -reference to a list, hash, subroutine or object. Where code returns a -list of multiple values the items will automatically be folded into a -list reference which can be accessed as per normal. - - my $vars = { - # either is OK, first is recommended - items1 => sub { return [ 'foo', 'bar', 'baz' ] }, - items2 => sub { return ( 'foo', 'bar', 'baz' ) }, - }; - -template: - - [% FOREACH i = items1 %] - ... - [% END %] - - [% FOREACH i = items2 %] - ... - [% END %] - -=head2 Error Handling - -Errors can be reported from user code by calling die(). Errors raised -in this way are caught by the Template Toolkit and converted to -structured exceptions which can be handled from within the template. -A reference to the exception object is then available as the 'error' -variable. - - my $vars = { - barf => sub { - die "a sick error has occurred\n"; - }, - }; - -template: - - [% TRY %] - [% barf %] # calls sub which throws error via die() - [% CATCH %] - [% error.info %] # outputs "a sick error has occurred\n" - [% END %] - -Error messages thrown via die() are converted to exceptions of type -'undef'. Exceptions of user-defined types can be thrown by calling -die() with a reference to a Template::Exception object. - - use Template::Exception; - - ... - - my $vars = { - login => sub { - ... - die Template::Exception->new('badpwd', - 'password too silly'); - }, - }; - -template: - - [% TRY %] - [% login %] - [% CATCH badpwd %] - Bad password: [% error.info %] - [% CATCH %] - Some other '[% error.type %]' error: [% error.info %] - [% END %] - -The exception types 'stop' and 'return' are used to implement the -STOP and RETURN directives. Throwing an exception as: - - die (Template::Exception->new('stop')); - -has the same effect as the directive: - - [% STOP %] - -Subroutines and methods can also raise errors by returning a list or -reference to a list containing the undefined value (undef) followed by -an exception object or error message. This is supported for backwards -compatibility with version 1 but may be deprecated in some future -version. - - my $vars = { - # currently equivalent - barf => sub { - die "I'm sorry Dave, I can't do that"; - }, - yack => sub { - return (undef, "I'm sorry Dave, I can't do that"); - }, - }; - -=head2 Virtual Methods - -The Template Toolkit implements a number of "virtual methods" which -can be applied to scalars, hashes or lists. For example: - - [% mylist = [ 'foo', 'bar', 'baz' ] %] - [% newlist = mylist.sort %] - -Here 'mylist' is a regular reference to a list, and 'sort' is -a virtual method that returns a new list of the items in sorted -order. You can chain multiple virtual methods together. For -example: - - [% mylist.sort.join(', ') %] - -Here the 'join' virtual method is called to join the sorted list into -a single string, generating the following output: - - bar, baz, foo - -See L<Template::Manual::VMethods> for details of all the virtual -methods available. - -=head2 Variable Interpolation - -The Template Toolkit uses '$' consistently to indicate that a variable -should be interpolated in position. Most frequently, you see this in -double-quoted strings: - - [% fullname = "$honorific $firstname $surname" %] - -Or embedded in plain text when the INTERPOLATE option is set: - - Dear $honorific $firstname $surname, - -The same rules apply within directives. If a variable is prefixed -with a '$' then it is replaced with its value before being used. The -most common use is to retrieve an element from a hash where the key is -stored in a variable. - - [% uid = 'abw' %] - [% userlist.$uid %] # same as 'userlist.abw' - -Curly braces can be used to delimit interpolated variable names where -necessary. - - [% userlist.${me.id}.name %] - -Directives such as INCLUDE, PROCESS, etc., that accept a template name -as the first argument, will automatically quote it for convenience. - - [% INCLUDE foo/bar.txt %] - -equivalent to: - - [% INCLUDE "foo/bar.txt" %] - -To INCLUDE a template whose name is stored in a variable, simply -prefix the variable name with '$' to have it interpolated. - - [% myfile = 'header' %] - [% INCLUDE $myfile %] - -equivalent to: - - [% INCLUDE header %] - -Note also that a variable containing a reference to a Template::Document -object can also be processed in this way. - - my $vars = { - header => Template::Document->new({ ... }), - }; - -template: - - [% INCLUDE $header %] - -=head2 Local and Global Variables - -Any simple variables that you create, or any changes you make to -existing variables, will only persist while the template is being -processed. The top-level variable hash is copied before processing -begins and any changes to variables are made in this copy, leaving the -original intact. The same thing happens when you INCLUDE another -template. The current namespace hash is cloned to prevent any -variable changes made in the included template from interfering with -existing variables. The PROCESS option bypasses the localisation step -altogether making it slightly faster, but requiring greater attention -to the possibility of side effects caused by creating or changing any -variables within the processed template. - - [% BLOCK change_name %] - [% name = 'bar' %] - [% END %] - - [% name = 'foo' %] - [% INCLUDE change_name %] - [% name %] # foo - [% PROCESS change_name %] - [% name %] # bar - -Dotted compound variables behave slightly differently because the -localisation process is only skin deep. The current variable -namespace hash is copied, but no attempt is made to perform a -deep-copy of other structures within it (hashes, arrays, objects, -etc). A variable referencing a hash, for example, will be copied to -create a new reference but which points to the same hash. Thus, the -general rule is that simple variables (undotted variables) are -localised, but existing complex structures (dotted variables) are not. - - [% BLOCK all_change %] - [% x = 20 %] # changes copy - [% y.z = 'zulu' %] # changes original - [% END %] - - [% x = 10 - y = { z => 'zebra' } - %] - [% INCLUDE all_change %] - [% x %] # still '10' - [% y.z %] # now 'zulu' - - -If you create a complex structure such as a hash or list reference -within a local template context then it will cease to exist when -the template is finished processing. - - [% BLOCK new_stuff %] - [% # define a new 'y' hash array in local context - y = { z => 'zulu' } - %] - [% END %] - - [% x = 10 %] - [% INCLUDE new_stuff %] - [% x %] # outputs '10' - [% y %] # nothing, y is undefined - -Similarly, if you update an element of a compound variable which -I<doesn't> already exists then a hash will be created automatically -and deleted again at the end of the block. - - [% BLOCK new_stuff %] - [% y.z = 'zulu' %] - [% END %] - -However, if the hash I<does> already exist then you will modify the -original with permanent effect. To avoid potential confusion, it is -recommended that you don't update elements of complex variables from -within blocks or templates included by another. - -If you want to create or update truly global variables then you can -use the 'global' namespace. This is a hash array automatically created -in the top-level namespace which all templates, localised or otherwise -see the same reference to. Changes made to variables within this -hash are visible across all templates. - - [% global.version = 123 %] - -=head2 Compile Time Constant Folding - -In addition to variables that get resolved each time a template is -processed, you can also define variables that get resolved just once -when the template is compiled. This generally results in templates -processing faster because there is less work to be done. - -To define compile-time constants, specify a CONSTANTS hash as a -constructor item as per VARIABLES. The CONSTANTS hash can contain any -kind of complex, nested, or dynamic data structures, just like regular -variables. - - my $tt = Template->new({ - CONSTANTS => { - version => 3.14, - release => 'skyrocket', - col => { - back => '#ffffff', - fore => '#000000', - }, - myobj => My::Object->new(), - mysub => sub { ... }, - joint => ', ', - }, - }); - -Within a template, you access these variables using the 'constants' -namespace prefix. - - Version [% constants.version %] ([% constants.release %]) - - Background: [% constants.col.back %] - -When the template is compiled, these variable references are replaced -with the corresponding value. No further variable lookup is then -required when the template is processed. - -You can call subroutines, object methods, and even virtual methods on -constant variables. - - [% constants.mysub(10, 20) %] - [% constants.myobj(30, 40) %] - [% constants.col.keys.sort.join(', ') %] - -One important proviso is that any arguments you pass to subroutines -or methods must also be literal values or compile time constants. - -For example, these are both fine: - - # literal argument - [% constants.col.keys.sort.join(', ') %] - - # constant argument - [% constants.col.keys.sort.join(constants.joint) %] - -But this next example will raise an error at parse time because -'joint' is a runtime variable and cannot be determined at compile -time. - - # ERROR: runtime variable argument! - [% constants.col.keys.sort.join(joint) %] - -The CONSTANTS_NAMESPACE option can be used to provide a different -namespace prefix for constant variables. For example: - - my $tt = Template->new({ - CONSTANTS => { - version => 3.14, - # ...etc... - }, - CONSTANTS_NAMESPACE => 'const', - }); - -Constants would then be referenced in templates as: - - [% const.version %] - -=head2 Special Variables - -A number of special variables are automatically defined by the Template -Toolkit. - -=over 4 - -=item template - -The 'template' variable contains a reference to the main template -being processed, in the form of a Template::Document object. This -variable is correctly defined within PRE_PROCESS, PROCESS and -POST_PROCESS templates, allowing standard headers, footers, etc., to -access metadata items from the main template. The 'name' and -'modtime' metadata items are automatically provided, giving the -template name and modification time in seconds since the epoch. - -Note that the 'template' variable always references the top-level -template, even when processing other template components via INCLUDE, -PROCESS, etc. - -=item component - -The 'component' variable is like 'template' but always contains a -reference to the current, innermost template component being processed. -In the main template, the 'template' and 'component' variable will -reference the same Template::Document object. In any other template -component called from the main template, the 'template' variable -will remain unchanged, but 'component' will contain a new reference -to the current component. - -This example should demonstrate the difference: - - $template->process('foo') - || die $template->error(), "\n"; - -'foo': - - [% template.name %] # foo - [% component.name %] # foo - [% PROCESS footer %] - -'footer': - - [% template.name %] # foo - [% component.name %] # footer - -=item loop - -Within a FOREACH loop, the 'loop' variable references the Template::Iterator -object responsible for controlling the loop. - - [% FOREACH item = [ 'foo', 'bar', 'baz' ] -%] - [% "Items:\n" IF loop.first -%] - [% loop.count %]/[% loop.size %]: [% item %] - [% END %] - -=item error - -Within a CATCH block, the 'error' variable contains a reference to the -Template::Exception object thrown from within the TRY block. The -'type' and 'info' methods can be called or the variable itself can -be printed for automatic stringification into a message of the form -"$type error - $info". See L<Template::Exception> for further details. - - [% TRY %] - ... - [% CATCH %] - [% error %] - [% END %] - -=item content - -The WRAPPER method captures the output from a template block and then -includes a named template, passing the captured output as the 'content' -variable. - - [% WRAPPER box %] - Be not afeard; the isle is full of noises, - Sounds and sweet airs, that give delight and hurt not. - [% END %] - - [% BLOCK box %] - <table border=1> - <tr> - <td> - [% content %] - </td> - </tr> - </table> - [% END %] - -=back - -=head2 Compound Variables - -Compound 'dotted' variables may contain any number of separate -elements. Each element may evaluate to any of the permitted variable -types and the processor will then correctly use this value to evaluate -the rest of the variable. Arguments may be passed to any of the -intermediate elements. - - [% myorg.people.sort('surname').first.fullname %] - -Intermediate variables may be used and will behave entirely as expected. - - [% sorted = myorg.people.sort('surname') %] - [% sorted.first.fullname %] - -This simplified dotted notation has the benefit of hiding the -implementation details of your data. For example, you could implement -a data structure as a hash array one day and then change it to an -object the next without requiring any change to the templates. - -=head1 AUTHOR - -Andy Wardley E<lt>abw@andywardley.comE<gt> - -L<http://www.andywardley.com/|http://www.andywardley.com/> - - - - -=head1 VERSION - -Template Toolkit version 2.13, released on 30 January 2004. - -=head1 COPYRIGHT - - Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved. - Copyright (C) 1998-2002 Canon Research Centre Europe Ltd. - -This module is free software; you can redistribute it and/or -modify it under the same terms as Perl itself. - - - -=cut - -# Local Variables: -# mode: perl -# perl-indent-level: 4 -# indent-tabs-mode: nil -# End: -# -# vim: expandtab shiftwidth=4: |
