[Templates-svn] r1094 - in trunk/lib/Template: . Manual
svn@template-toolkit.org
svn@template-toolkit.org
Author: abw
Date: 2007-06-05 20:17:56 +0100 (Tue, 05 Jun 2007)
New Revision: 1094
Modified:
trunk/lib/Template/FAQ.pod
trunk/lib/Template/Manual/Config.pod
trunk/lib/Template/Manual/Credits.pod
trunk/lib/Template/Manual/Directives.pod
trunk/lib/Template/Manual/Internals.pod
trunk/lib/Template/Manual/Intro.pod
trunk/lib/Template/Manual/Plugins.pod
trunk/lib/Template/Manual/Variables.pod
trunk/lib/Template/Toolkit.pod
trunk/lib/Template/Tools.pod
Log:
POD updates
Modified: trunk/lib/Template/FAQ.pod
===================================================================
--- trunk/lib/Template/FAQ.pod 2007-05-30 10:45:24 UTC (rev 1093)
+++ trunk/lib/Template/FAQ.pod 2007-06-05 19:17:56 UTC (rev 1094)
@@ -15,54 +15,57 @@
# modify it under the same terms as Perl itself.
#========================================================================
-
-#------------------------------------------------------------------------
-# WARNING
-# This documentation hasn't been updated in ages...
-#------------------------------------------------------------------------
-
=head1 NAME
Template::FAQ - Frequently Asked Questions about the Template Toolkit
-=head1 DESCRIPTION
-
=head1 Template Toolkit Language
=head2 Why doesn't [% a = b IF c %] work as expected?
-Because the parser interprets it as
+There's a limitation in the TT2 parser which means that the following code
+doesn't work as you might expect:
+ [% a = b IF c %]
+
+The parser interprets it as an attempt to set C<a> to the result of
+C<b IF c>, like this:
+
[% a = (b IF c) %]
-Do this instead:
+If you want to set C<a = b> only if C<c> is true, then do this instead:
[% SET a = b IF c %]
+The explcit C<SET> keyword gives the parser the clue it needs to do the
+right thing.
+
+NOTE: this will be fixed in TT3
+
=head2 If I'm using TT to write out a TT template, is there a good way to escape [% and %]?
-You can do this:
+You can do something like this:
- [% stag = "[\%"
- etag = "%\]"
- %]
+ [% stag = "[\%"
+ etag = "%\]"
+ %]
and then:
- [% stag; 'hello'; etag %]
+ [% stag; 'hello'; etag %]
-Or something like:
+Or you can use the C<TAGS> directive, like so:
- [% TAGS [- -] %]
- [- INCLUDE foo -] # is a directive
- [% INCLUDE foo %] # not a directive, just plain text, passed through
+ [% TAGS [- -] %]
+ [- INCLUDE foo -] # is a directive
+ [% INCLUDE foo %] # not a directive
=head2 How do I iterate over a hash?
-This is covered in the L<Template::Manual::VMethods|VMethods> section
-of the manual page. A list of all the keys that are in the hash can
-be obtained with the 'keys' virtual method. You can then iterate
-over that list and by looking up each key in turn get the value.
+This is covered in the L<Template::Manual::VMethods> section of the
+manual. A list of all the keys that are in the hash can be obtained with the
+C<keys> virtual method. You can then iterate over that list and by looking up
+each key in turn get the value.
[% FOREACH key = product.keys %]
[% key %] => [% product.$key %]
@@ -74,20 +77,20 @@
Order the data into rows:
- Steve Karen Jeff
- Brooklyn Nantucket Fairfax
- NY MA VA
-
+ Steve Karen Jeff
+ Brooklyn Nantucket Fairfax
+ NY MA VA
+
[% USE table(data, rows=3) %]
-
+
Then ask for each column
-
+
[% FOREACH column = table.cols %]
-
+
And then print each item in the column going across the output rows
-
+
[% FOREACH item = column %]
- <td>[% item %]</td>
+ <td>[% item %]</td>
[% END %]
=head2 Accessing Cookies
@@ -109,30 +112,28 @@
=head2 Can I serve templates from a database?
Short answer: yes, Chris Nandor has done this for Slash. You need to
-subclass Template::Provider. See the mailing list archives for further
+subclass L<Template::Provider>. See the mailing list archives for further
info.
=head2 Can I fetch templates via http?
-To do the job properly, you should sublcass Template::Provider to
-Template::Provider::HTTP and use a PREFIX_MAP option to bind the
-'http' template prefix to that particular provider (you may want to
-go digging around in the F<Changes> file around version 2.01 for
-more info on PREFIX_MAP - it may not be properly documented anywhere
-else...yet!). e.g. (untested due to lack of existing HTTP Provider
-- patches welcome!).
+To do the job properly, you should subclass L<Template::Provider> to
+C<Template::Provider::HTTP> and use a C<PREFIX_MAP> option to bind the C<http>
+template prefix to that particular provider (you may want to go digging around
+in the F<Changes> file around version 2.01 for more info on C<PREFIX_MAP> - it
+may not be properly documented anywhere else...yet!). e.g.
use Template::Provider::HTTP;
-
+
my $file = Template::Provider( INCLUDE_PATH => [...] );
my $http = Template::Provider::HTTP->new(...);
my $tt2 = Template->new({
- LOAD_TEMPLATES => [ $file, $http ],
- PREFIX_MAP => {
- file => '0', # file:foo.html
- http => '1', # http:foo.html
- default => '0', # foo.html => file:foo.html
- }
+ LOAD_TEMPLATES => [ $file, $http ],
+ PREFIX_MAP => {
+ file => '0', # file:foo.html
+ http => '1', # http:foo.html
+ default => '0', # foo.html => file:foo.html
+ }
});
Now a template specified as:
@@ -150,57 +151,15 @@
[% INCLUDE dbi:foo.html %]
-But similarly, alas, we don't yet have a DBI provider as part of the
-Template Toolkit. There has been some talk on the mailing list about
-efforts to develop DBI and/or HTTP providers but as yet no-one has
-stepped forward to take up the challenge...
+Alas, we don't yet have a DBI provider as part of the Template Toolkit. There
+has been some talk on the mailing list about efforts to develop DBI and/or
+HTTP providers but as yet no-one has stepped forward to take up the
+challenge...
-In the mean time, Craig's post from the mailing list has some useful
-pointers on how to acheive this using existing modules:
+In the mean time, Craig Barrat's post from the mailing list has some useful
+pointers on how to acheive this using existing modules. See
+L<http://tt2.org/pipermail/templates/2001-May/000954.html>
- To: Adam Theo <adamtheo@theoretic.com>
- From: Craig Barratt <craig@arraycomm.com>
- Date: Fri, 18 May 2001 17:06:59 -0700
-
- > i was wondering if there is anyway to fetch a file using http:// or
- > ftp:// and include that?
-
- Here's one way. Set the LOAD_PERL option:
-
- use Template;
-
- my $template = Template->new({
- LOAD_PERL => 1
- });
- $template->process("example.tt", { stdout => *STDOUT })
- || die $template->error();
-
- and then use LWP::UserAgent and HTTP::Request:
-
- [%
- USE ua = LWP.UserAgent;
- ua.proxy("http", "http://your_proxy/");
- USE req = HTTP.Request("GET", "http://www.cpan.org");
- ua.request(req).content;
- -%]
-
- For FTP use Net::FTP:
-
- [%
- USE ftp = Net.FTP("ftp.cpan.org");
- x = ftp.login("anonymous", "me@here.there");
- x = ftp.cwd("/");
- x = ftp.get("welcome.msg", stdout);
- x = ftp.quit;
- -%]
-
- Normally ftp.get would write the file into the current directory.
- Instead we pass stdout as a second argument so that it is written
- to stdout. We set stdout to STDOUT in the variables we pass to
- process.
-
- Craig
-
=head1 Miscellaneous
=head2 How can I find out the name of the main template being processed?
@@ -262,13 +221,12 @@
human consumption.
[% USE Date %]
-
[% template.name %] last modified [% Date.format(template.modtime) %]
=head2 How can I configure variables on a per-request basis?
-One easy way to acheive this is to define a single PRE_PROCESS template which
-loads in other configuration files based on variables defined or other
+One easy way to acheive this is to define a single C<PRE_PROCESS> template
+which loads in other configuration files based on variables defined or other
conditions.
For example, my setup usually looks something like this:
@@ -279,7 +237,7 @@
[% DEFAULT style = 'text'
section = template.section or 'home';
-
+
PROCESS config/site
+ config/urls
+ config/macros
@@ -295,21 +253,21 @@
config/style/basic:
[% style = {
- name = style # save existing 'style' var as 'style.name'
+ name = style # save existing 'style' var as 'style.name'
- # define various other style variables....
+ # define various other style variables....
col = {
- back => '#ffffff'
- text => '#000000'
- # ...etc...
- }
+ back => '#ffffff'
+ text => '#000000'
+ # ...etc...
+ }
- logo = {
- # ...etc...
- }
+ logo = {
+ # ...etc...
+ }
- # ...etc...
- }
+ # ...etc...
+ }
%]
Each source template can declare which section it's in via a META
@@ -319,7 +277,6 @@
title = 'General Information'
section = 'info'
%]
-
...
This controls which section configuration file gets loaded to set various
@@ -328,29 +285,26 @@
config/section/info:
[% section = {
- name = section # save 'section' var as 'section.name'
- title = 'Information'
- menu = [ ... ]
- # ...etc...
- }
+ name = section # save 'section' var as 'section.name'
+ title = 'Information'
+ menu = [ ... ]
+ # ...etc...
+ }
%]
This illustrates the basic principal but you can extend it to perform
pretty much any kind of per-document initialisation that you require.
-=head1 AUTHOR
+=head1 Questions About This FAQ
-Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/>
+=head2 Why is this FAQ so short?
-=head1 COPYRIGHT
+Because we don't have anyone maintaining it.
-Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
+=head2 Can I help?
-This module is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
+Yes please :-)
-
-
=cut
# Local Variables:
Modified: trunk/lib/Template/Manual/Config.pod
===================================================================
--- trunk/lib/Template/Manual/Config.pod 2007-05-30 10:45:24 UTC (rev 1093)
+++ trunk/lib/Template/Manual/Config.pod 2007-06-05 19:17:56 UTC (rev 1094)
@@ -98,8 +98,8 @@
extraneous whitespace. Both are disabled by default.
my $template = Template-E<gt>new({
- PRE_CHOMP =E<gt> 1,
- POST_CHOMP =E<gt> 1,
+ PRE_CHOMP => 1,
+ POST_CHOMP => 1,
});
With C<PRE_CHOMP> set to C<1>, the newline and whitespace preceding a directive
@@ -180,14 +180,14 @@
you can use 'C<+>' to disable any chomping options (i.e. leave the
whitespace intact) on a per-directive basis.
- [% FOREACH user = userlist %]
+ [% FOREACH user IN userlist %]
User: [% user +%]
[% END %]
With C<POST_CHOMP> set to C<CHOMP_ONE>, the above example would be parsed as
if written:
- [% FOREACH user = userlist %]User: [% user %]
+ [% FOREACH user IN userlist %]User: [% user %]
[% END %]
For reference, the C<PRE_CHOMP> and C<POST_CHOMP> configuration options may be
@@ -452,7 +452,7 @@
});
If a non-existant template is requested through the Template
-L<Template#process()|process()> method, or by an C<INCLUDE>, C<PROCESS> or
+L<process()|Template#process()> method, or by an C<INCLUDE>, C<PROCESS> or
C<WRAPPER> directive, then the C<DEFAULT> template will instead be processed, if
defined. Note that the C<DEFAULT> template is not used when templates are
specified with absolute or relative filenames, or as a reference to a input
@@ -477,7 +477,7 @@
The C<AUTO_RESET> option is set by default and causes the local C<BLOCKS>
cache for the L<Template::Context> object to be reset on each call to the
-Template L<Template#process()|process()> method. This ensures that any C<BLOCK>s
+Template L<process()|Template#process()> method. This ensures that any C<BLOCK>s
defined within a template will only persist until that template is finished
processing. This prevents C<BLOCK>s defined in one processing request from
interfering with other independent requests subsequently processed by the same
@@ -487,7 +487,7 @@
for the L<Template::Context> object. Subsequent C<BLOCK> definitions in
templates will over-ride these but they will be reinstated on each reset if
C<AUTO_RESET> is enabled (default), or if the L<Template::Context>
-L<Template::Context#reset()|reset()> method is called.
+L<reset()|Template::Context#reset()> method is called.
=head2 RECURSION
@@ -623,7 +623,7 @@
The following options are used to specify any additional templates that should
be processed before, after, around or instead of the template passed as the
-first argument to the L<Template> L<Template#process()|process()> method.
+first argument to the L<Template> L<process()|Template#process()> method.
These options can be perform various useful tasks such as adding standard
headers or footers to all pages, wrapping page output in other templates,
pre-defining variables or performing initialisation or cleanup tasks,
@@ -632,7 +632,7 @@
The task of processing the template is delegated internally to the
L<Template::Service> module which, unsurprisingly, also has a
-L<Template::Service#process()|process()> method. Any templates defined by the
+L<process()|Template::Service#process()> method. Any templates defined by the
C<PRE_PROCESS> option are processed first and any output generated is added to
the output buffer. Then the main template is processed, or if one or more
C<PROCESS> templates are defined then they are instead processed in turn. In this
@@ -748,7 +748,7 @@
The C<PROCESS> option may be set to contain the name(s) of template files
(relative to C<INCLUDE_PATH>) which should be processed instead of the main
-template passed to the L<Template> L<Template#process()|process()> method.
+template passed to the L<Template> L<process()|Template#process()> method.
This can be used to apply consistent wrappers around all templates, similar to
the use of C<PRE_PROCESS> and C<POST_PROCESS> templates.
@@ -970,7 +970,7 @@
},
});
-In this example, any template processed by the L<$template> object, or
+In this example, any template processed by the C<$template> object, or
other templates or code called from within, can raise a C<user.login>
exception and have the service redirect to the F<user/login.html>
template. Similarly, a C<user.passwd> exception has a specific
@@ -982,7 +982,7 @@
[% THROW user.login 'no user id: please login' %]
-or by calling the L<Template::Context#throw()|throw()> method on the
+or by calling the L<throw()|Template::Context#throw()> method on the
current L<Template::Context> object,
$context->throw('user.passwd', 'Incorrect Password');
@@ -1014,7 +1014,7 @@
in C<RAWPERL> blocks and will throw a 'C<file>' exception.
When using compiled templates (see
-L<Caching_and_Compiling_Options>),
+L<Caching and Compiling Options>),
the C<EVAL_PERL> has an affect when the template is compiled, and again
when the templates is subsequently processed, possibly in a different
context to the one that compiled it.
@@ -1110,7 +1110,7 @@
}
The default C<OUTPUT> location be overridden by passing a third parameter to
-the L<Template> L<Template#process()|process()> method. This can be specified
+the L<Template> L<process()|Template#process()> method. This can be specified
as any of the above argument types.
$t->process($file, $vars, "/tmp/foo");
@@ -1125,7 +1125,7 @@
The C<OUTPUT_PATH> allows a directory to be specified into which output
files should be written. An output file can be specified by the
C<OUTPUT> option, or passed by name as the third parameter to the
-L<Template> L<Template#process()|process()> method.
+L<Template> L<process()|Template#process()> method.
my $template = Template->new({
INCLUDE_PATH => "/tmp/src",
@@ -1440,12 +1440,12 @@
match the case exactly.
The C<USE> directive is used to create plugin objects and does so by calling
-the L<Template::Context#plugin()|plugin()> method on the current
+the L<plugin()|Template::Context#plugin()> method on the current
L<Template::Context> object. If the plugin name is defined in the C<PLUGINS>
hash then the corresponding Perl module is loaded via C<require()>. The
-context then calls the L<Template::Plugin#load()|load()> class method which
+context then calls the L<load()|Template::Plugin#load()> class method which
should return the class name (default and general case) or a prototype object
-against which the L<Template::Plugin#new()|new()> method can be called to
+against which the L<new()|Template::Plugin#new()> method can be called to
instantiate individual plugin objects.
If the plugin name is not defined in the C<PLUGINS> hash then the
@@ -1486,7 +1486,7 @@
If you don't want the default C<Template::Plugin> namespace added to the
end of the C<PLUGIN_BASE>, then set the C<$Template::Plugins::PLUGIN_BASE>
-variable to a false value before calling the L<Template> L<Template#new()|new()>
+variable to a false value before calling the L<new()|Template> L<Template#new()>
constructor method. This is shown in the example below where the
C<Foo> plugin is located as C<My::Plugin::Foo> or C<Your::Plugin::Foo> but not
as C<Template::Plugin::Foo>.
@@ -1522,12 +1522,12 @@
Plugins loaded using the C<PLUGINS> or C<PLUGIN_BASE> receive a reference to
the current context object as the first argument to the
-L<Template::Plugin#new()|new()> constructor. Modules loaded using C<LOAD_PERL>
+L<new()|Template::Plugin#new()> constructor. Modules loaded using C<LOAD_PERL>
are assumed to not conform to the plugin interface. They must provide a C<new()>
class method for instantiating objects but it will not receive a reference to
the context as the first argument.
-Plugin modules should provide a L<Template::Plugin#load()|load()> class method
+Plugin modules should provide a L<load()|Template::Plugin#load()> class method
(or inherit the default one from the L<Template::Plugin> base class) which is
called the first time the plugin is loaded. Regular Perl modules need not. In
all other respects, regular Perl objects and Template Toolkit plugins are
@@ -1561,7 +1561,7 @@
});
Additional filters can be specified at any time by calling the
-L<Template::Context#define_filter()|define_filter()> method on the current
+L<define_filter()|Template::Context#define_filter()> method on the current
L<Template::Context> object. The method accepts a filter name, a reference to a
filter subroutine and an optional flag to indicate if the filter is dynamic.
@@ -1644,10 +1644,10 @@
named template may refer to a locally defined C<BLOCK> or a file relative to
the C<INCLUDE_PATH> (or an absolute or relative path if the appropriate
C<ABSOLUTE> or C<RELATIVE> options are set). If a C<BLOCK> definition can't be
-found (see the L<Template::Context> L<Template::Context#template()|template()>
+found (see the L<Template::Context> L<template()|Template::Context#template()>
method for a discussion of C<BLOCK> locality) then each of the
C<LOAD_TEMPLATES> provider objects is queried in turn via the
-L<Template::Provider#fetch()|fetch()> method to see if it can supply the
+L<fetch()|Template::Provider#fetch()> method to see if it can supply the
required template.
Each provider can return a compiled template, an error, or decline to service
@@ -1670,12 +1670,12 @@
=head2 LOAD_PLUGINS
The C<LOAD_PLUGINS> options can be used to specify a list of provider objects
-(i.e. they implement the L<Template::Plugins#fetch()|fetch()> method) which
+(i.e. they implement the L<fetch()|Template::Plugins#fetch()> method) which
are responsible for loading and instantiating template plugin objects. The
-L<Template::Context> L<Template::Context#plugin()|plugin()> method queries
+L<Template::Context> L<plugin()|Template::Context#plugin()> method queries
each provider in turn in a "Chain of Responsibility" as per the
-L<Template::Context#template()|template()> and
-L<Template::Context#filter()|filter()> methods.
+L<template()|Template::Context#template()> and
+L<filter()|Template::Context#filter()> methods.
my $template = Template->new({
LOAD_PLUGINS => [
@@ -1697,12 +1697,12 @@
=head2 LOAD_FILTERS
The C<LOAD_FILTERS> option can be used to specify a list of provider objects
-(i.e. they implement the L<Template::Filters#fetch()|fetch()> method) which
+(i.e. they implement the L<fetch()|Template::Filters#fetch()> method) which
are responsible for returning and/or creating filter subroutines. The
-L<Template::Context> L<Template::Context#filter()|filter()> method queries
+L<Template::Context> L<filter()|Template::Context#filter()> method queries
each provider in turn in a "Chain of Responsibility" as per the
-L<Template::Context#template()|template()> and
-L<Template::Context#plugin()|plugin()> methods.
+L<template()|Template::Context#template()> and
+L<plugin()|Template::Context#plugin()> methods.
my $template = Template->new({
LOAD_FILTERS => [
@@ -1747,12 +1747,12 @@
"compiled" template documents. Template subroutines make callbacks into the
context object to access Template Toolkit functionality, for example, to to
C<INCLUDE> or C<PROCESS> another template
-(L<Template::Context#include()|include()> and
-L<Template::Context#process()|process()> methods, respectively), to C<USE> a
-plugin (L<Template::Context#plugin()|plugin()>) or instantiate a filter
-(L<Template::Context#filter()|filter()>) or to access the stash
-(L<Template::Context#stash()|stash()>) which manages variable definitions via
-the L<Template::Stash#get()|get()> and L<Template::Stash#set()|set()> methods.
+(L<include()|Template::Context#include()> and
+L<process()|Template::Context#process()> methods, respectively), to C<USE> a
+plugin (L<plugin()|Template::Context#plugin()>) or instantiate a filter
+(L<filter()|Template::Context#filter()>) or to access the stash
+(L<stash()|Template::Context#stash()>) which manages variable definitions via
+the L<get()|Template::Stash#get()> and L<set()|Template::Stash#set()> methods.
my $template = Template->new({
CONTEXT => MyOrg::Template::Context->new({ ... }),
Modified: trunk/lib/Template/Manual/Credits.pod
===================================================================
--- trunk/lib/Template/Manual/Credits.pod 2007-05-30 10:45:24 UTC (rev 1093)
+++ trunk/lib/Template/Manual/Credits.pod 2007-06-05 19:17:56 UTC (rev 1094)
@@ -58,10 +58,8 @@
=head1 AUTHOR
-Andy Wardley E<lt>abw@wardley.orgE<gt>
+Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/>
-L<http://wardley.org/>
-
=head1 COPYRIGHT
Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
@@ -69,7 +67,7 @@
The Template Toolkit is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
-=head1 CONTRIBUTORS
+=head1 CONTRIBUTORS
Many people have contributed ideas, inspiration, fixes and features to
the Template Toolkit. Their efforts continue to be very much appreciated.
@@ -86,12 +84,12 @@
Simon Luff, Andy Maas, Paul Makepeace, Gervase Markham, Sergey Martynoff,
Simon Matthews, Robert McArthur, Craig McLane, Myk Melez, Eugene Miretskiy,
Tatsuhiko Miyagawa, Bill Moseley, Keith G. Murphy, Chris Nandor, Leslie
-Michael Orchard, Paul Orrock, Steve Peters, Briac Pilpré, Yuri Pimenov, Martin
-Portman, Slaven Rezic, Jess Robinson, Josh Rosenbaum, Christian Schaffner,
-Mike Schilli, Randal L. Schwartz, Paul Seamons, Paul Sharpe, Ville Skyttä,
-Barrie Slaymaker, Doug Steinwand, Michael Stevens, Autrijus Tang, Drew Taylor,
-Swen Thuemmler, Richard Tietjen, Stathy G. Touloumis, Jim Vaughan, Simon
-Wilcox, Chris Winters
+Michael Orchard, Paul Orrock, Steve Peters, Briac PilprE<eacute>, Yuri
+Pimenov, Martin Portman, Slaven Rezic, Jess Robinson, Josh Rosenbaum,
+Christian Schaffner, Mike Schilli, Randal L. Schwartz, Paul Seamons, Paul
+Sharpe, Ville SkyttE<auml>, Barrie Slaymaker, Doug Steinwand, Michael Stevens,
+Autrijus Tang, Drew Taylor, Swen Thuemmler, Richard Tietjen, Stathy G.
+Touloumis, Jim Vaughan, Simon Wilcox, Chris Winters
=cut
Modified: trunk/lib/Template/Manual/Directives.pod
===================================================================
--- trunk/lib/Template/Manual/Directives.pod 2007-05-30 10:45:24 UTC (rev 1093)
+++ trunk/lib/Template/Manual/Directives.pod 2007-06-05 19:17:56 UTC (rev 1094)
@@ -619,15 +619,12 @@
The C<FOREACH> directive will iterate through the items in a list, processing
the enclosed block for each one.
- my $vars = {
- foo => 'Foo',
- items => [ 'one', 'two', 'three' ],
- };
-
-template:
-
+ [% foo = 'Foo'
+ items = [ 'one', 'two', 'three' ]
+ %]
+
Things:
- [% FOREACH thing = [ foo 'Bar' "$foo Baz" ] %]
+ [% FOREACH thing IN [ foo 'Bar' "$foo Baz" ] %]
* [% thing %]
[% END %]
@@ -658,9 +655,9 @@
* Foo
* Foo Bar
-You can use also use C<IN> instead of C<=> if you prefer.
+You can use also use C<=> instead of C<IN> if you prefer.
- [% FOREACH crook IN government %]
+ [% FOREACH i = items %]
When the C<FOREACH> directive is used without specifying a target variable,
any iterated values which are hash references will be automatically
@@ -911,7 +908,7 @@
The C<FILTERS> option, described in L<Template::Manual::Config>, allows custom
filters to be defined when a Template object is instantiated. The
-L<Template::Context#define_filter()|define_filter()> method allows further
+L<define_filter()|Template::Context#define_filter()> method allows further
filters to be defined at any time.
When using a filter, it is possible to assign an alias to it for
@@ -1003,7 +1000,7 @@
restoring the previous variable state. If you want to define a filter which
persists for the lifetime of the processor, or define additional dynamic
filter factories, then you can call the
-L<Template::Context#define_filter()|define_filter()> method on the current
+L<define_filter()|Template::Context#define_filter()> method on the current
L<Template::Context> object.
See L<Template::Manual::Filters> for a complete list of available filters,
@@ -1134,7 +1131,7 @@
You can use this approach to create multiple plugin objects with
different configurations. This example shows how the
-L<Template::Plugin::Format|format> plugin is used to create
+L<format|Template::Plugin::Format> plugin is used to create
sub-routines bound to variables for formatting text as per C<printf()>.
[% USE bold = format('<b>%s</b>') %]
@@ -1147,7 +1144,7 @@
<b>This is bold</b>
<i>This is italic</i>
-This next example shows how the L<Template::Plugin::URL|URL> plugin can be
+This next example shows how the L<URL|Template::Plugin::URL> plugin can be
used to build dynamic URLs from a base part and optional query parameters.
[% USE mycgi = URL('/cgi-bin/foo.pl', debug=1) %]
@@ -1159,7 +1156,7 @@
<a href="/cgi-bin/foo.pl?debug=1">...
<a href="/cgi-bin/foo.pl?mode=submit&debug=1">...
-The L<Template::Plugin::CGI|CGI> plugin is an example of one which delegates
+The L<CGI|Template::Plugin::CGI> plugin is an example of one which delegates
to another Perl module. In this this case, to Lincoln Stein's C<CGI> module.
All of the methods provided by the C<CGI> module are available via the plugin.
@@ -1415,8 +1412,8 @@
} };
...
-As with C<PERL> blocks, the L<Template::Context|$context> and
-L<Template::Stash|$stash> references are pre-defined and available for use
+As with C<PERL> blocks, the L<$context|Template::Context> and
+L<$stash|Template::Stash> references are pre-defined and available for use
within C<RAWPERL> code.
=head1 Exception Handling and Flow Control
@@ -1537,9 +1534,9 @@
default C<CATCH> handler) may be caught by enclosing C<TRY> blocks which can
be nested indefinitely across multiple templates. If the error isn't caught at
any level then processing will stop and the Template
-L<Template#process()|process()> method will return a false value to the
+L<process()|Template#process()> method will return a false value to the
caller. The relevant L<Template::Exception> object can be retrieved by calling
-the L<Template#error()|error()> method.
+the L<error()|Template#error()> method.
[% TRY %]
...
@@ -1745,7 +1742,7 @@
If you're writing a plugin, or some extension code that has the current
L<Template::Context> in scope (you can safely skip this section if this means
nothing to you) then you can also raise an exception by calling the context
-L<Template::Context#throw()|throw()> method. You can pass it an
+L<throw()|Template::Context#throw()> method. You can pass it an
L<Template::Exception> object reference, a pair of C<($type, $info)>
parameters or just an C<$info> string to create an exception of 'C<undef>' type.
@@ -1781,7 +1778,7 @@
and return to the template from which it was called, resuming processing at
the point immediately after the C<INCLUDE>, C<PROCESS> or C<WRAPPER>
directive. If there is no enclosing template then the Template
-L<Template#process()|process()> method will return to the calling code with a
+L<process()|Template#process()> method will return to the calling code with a
true value.
Before
@@ -1804,7 +1801,7 @@
The C<STOP> directive can be used to indicate that the processor should stop
gracefully without processing any more of the template document. This is a
-planned stop and the Template L<Template#process()|process()> method will
+planned stop and the Template L<process()|Template#process()> method will
return a B<true> value to the caller. This indicates that the template was
processed successfully according to the directives within it.
@@ -1935,7 +1932,7 @@
[% TAGS html %]
<!-- INCLUDE header -->
-See the L<Template::Manual::Config#TAGS|TAGS> and L<Template::Manual::Config#TAG_STYLE|TAG_STYLE>
+See the L<TAGS|Template::Manual::Config#TAGS> and L<TAG_STYLE|Template::Manual::Config#TAG_STYLE>
configuration options for further details.
=head2 DEBUG
Modified: trunk/lib/Template/Manual/Internals.pod
===================================================================
--- trunk/lib/Template/Manual/Internals.pod 2007-05-30 10:45:24 UTC (rev 1093)
+++ trunk/lib/Template/Manual/Internals.pod 2007-06-05 19:17:56 UTC (rev 1094)
@@ -17,6 +17,15 @@
Template::Manual::Internals - Template Toolkit internals
+=head1 Introduction
+
+This section of the documentation is aimed at developers wishing to
+know more about how the Template Toolkit works on the inside in order
+to extend or adapt it to their own needs.
+
+If that doesn't sound like you then you probably don't need to read this.
+There is no test afterwards.
+
=head1 Outside Looking In
The L<Template> module is simply a front end module which creates and
@@ -53,11 +62,11 @@
For the most part, the job of a service is really just one of scheduling and
dispatching. It receives a request in the form of a call to its
-L<Template::Service#process()|process()> method and schedules the named
+L<process()|Template::Service#process()> method and schedules the named
template specified as an argument, and possibly several other templates
(C<PRE_PROCESS>, etc) to be processed in order. It doesn't actually process
the templates itself, but instead makes a
-L<Template::Context#process()|process()> call against a L<Template::Context>
+L<process()|Template::Context#process()> call against a L<Template::Context>
object.
L<Template::Context> is the runtime engine for the Template Toolkit -
@@ -74,24 +83,24 @@
templates into executable Perl code (but more on that later).
Thankfully, all of this complexity is hidden away behind a simple
-L<Template::Context#template()|template()> method. You call it passing a
+L<template()|Template::Context#template()> method. You call it passing a
template name as an argument, and it returns a compiled template in the form
of a L<Template::Document> object, or otherwise raises an exception.
A L<Template::Document> is a thin object wrapper around a compiled template
-subroutine. The object implements a L<Template::Document#process()|process()>
+subroutine. The object implements a L<process()|Template::Document#process()>
method which performs a little bit of housekeeping and then calls the template
subroutine. The object also defines template metadata (defined in C<[% META
-... %]> directives) and has a L<Template::Document#block()|block()> method
+... %]> directives) and has a L<block()|Template::Document#block()> method
which returns a hash of any additional C<[% BLOCK xxxx %]> definitions found
in the template source.
So the context fetches a compiled document via its own
-L<Template::Context#template()|template()> method and then gets ready to
+L<template()|Template::Context#template()> method and then gets ready to
process it. It first updates the stash (the place where template variables get
defined - more on that shortly) to set any template variable definitions
specified as the second argument by reference to hash array. Then, it calls
-the document L<Template::Document#process()|process()> method, passing a
+the document L<process()|Template::Document#process()> method, passing a
reference to itself, the context object, as an argument. In doing this, it
provides itself as an object against which template code can make callbacks to
access runtime resources and Template Toolkit functionality.
@@ -190,7 +199,7 @@
features of the Template Toolkit.
We described earlier how the L<Template::Service> object calls on
-L<Template::Context> to handle a L<Template::Context#process()|process()>
+L<Template::Context> to handle a L<process()|Template::Context#process()>
request from the I<outside>. We can make a similar request on a context to
process a template, but from within the code of another template. This is a
call from the I<inside>.
@@ -213,12 +222,12 @@
Template variables are stored in, and managed by a L<Template::Stash> object.
This is a blessed hash array in which template variables are defined. The
-object wrapper provides L<Template::Stash#get()|get()> and
-L<Template::Stash#set()|set()> method which implement all the
+object wrapper provides L<get()|Template::Stash#get()> and
+L<set()|Template::Stash#set()> method which implement all the
I<magical.variable.features> of the Template Toolkit.
Each context object has its own stash, a reference to which can be returned by
-the appropriately named L<Template::Context#stash()|stash()> method. So to
+the appropriately named L<stash()|Template::Context#stash()> method. So to
print the value of some template variable, or for example, to represent the
following source template:
@@ -232,7 +241,7 @@
return '<title>' . $stash->get('title') . '</title>';
}
-The stash L<Template::Stash#get()|get()> method hides the details of the
+The stash L<get()|Template::Stash#get()> method hides the details of the
underlying variable types, automatically calling code references, checking
return values, and performing other such tricks. If 'C<title>' happens to be
bound to a subroutine then we can specify additional parameters as a list
@@ -262,7 +271,7 @@
[% foo.bar %]
$stash->get([ 'foo', 0, 'bar', 0 ]);
-The L<Template::Stash#set()|set()> method works in a similar way. It takes a
+The L<set()|Template::Stash#set()> method works in a similar way. It takes a
variable name and a variable value which should be assigned to it.
[% x = 10 %]
@@ -274,8 +283,8 @@
So the stash gives us access to template variables and the context provides
the higher level functionality.
-Alongside the L<Template::Context#process()|process()> method lies the
-L<Template::Context#include()|include()> method. Just as with the C<PROCESS> /
+Alongside the L<process()|Template::Context#process()> method lies the
+L<include()|Template::Context#include()> method. Just as with the C<PROCESS> /
C<INCLUDE> directives, the key difference is in variable localisation. Before
processing a template, the C<process()> method simply updates the stash to set
any new variable definitions, overwriting any existing values. In contrast,
@@ -288,7 +297,7 @@
the C<include()> method restores the previous variable state by I<decloning> the
stash.
-The context also provides an L<Template::Context#insert()|insert()> method to
+The context also provides an L<insert()|Template::Context#insert()> method to
implement the C<INSERT> directive, but no C<wrapper()> method. This functionality
can be implemented by rewriting the Perl code and calling C<include()>.
@@ -302,8 +311,8 @@
Other than the template processing methods C<process()>, C<include()> and
C<insert()>, the context defines methods for fetching plugin objects,
-L<Template::Context#plugin()|plugin()>, and filters,
-L<Template::Context#filter()|filter()>.
+L<plugin()|Template::Context#plugin()>, and filters,
+L<filter()|Template::Context#filter()>.
# TT USE directive
[% USE foo = Bar(10) %]
Modified: trunk/lib/Template/Manual/Intro.pod
===================================================================
--- trunk/lib/Template/Manual/Intro.pod 2007-05-30 10:45:24 UTC (rev 1093)
+++ trunk/lib/Template/Manual/Intro.pod 2007-06-05 19:17:56 UTC (rev 1094)
@@ -58,7 +58,7 @@
single module with a simple interface. It loads the other modules as required
and instantiates a default set of objects to handle subsequent template
processing requests. Configuration parameters may be passed to the L<Template>
-constructor method, L<Template#new()|new()>, which are then used to
+constructor method, L<new()|Template#new()>, which are then used to
configure the generate object.
use Template;
@@ -68,7 +68,7 @@
INTERPOLATE => 1,
}) || die "$Template::ERROR\n";
-The L<Template> object implements a L<Template#process()|process()> method for
+The L<Template> object implements a L<process()|Template#process()> method for
processing template files or text. The name of the input template (or various
other sources) is passed as the first argument, followed by a reference to a
hash array of variable definitions for substitution in the template.
@@ -82,10 +82,10 @@
$tt->process('letters/overdrawn', $vars)
|| die $tt->error(), "\n";
-The L<Template#process()|process()> method returns a true value (C<1>) on success
+The L<process()|Template#process()> method returns a true value (C<1>) on success
and prints the template output to C<STDOUT>, by default. On error, the
-L<Template#process()|process()> method returns a false value (C<undef>).
-The L<Template#error()|error()> method can then be called to retrieve
+L<process()|Template#process()> method returns a false value (C<undef>).
+The L<error()|Template#error()> method can then be called to retrieve
details of the error.
=head1 Component Based Content Construction
Modified: trunk/lib/Template/Manual/Plugins.pod
===================================================================
--- trunk/lib/Template/Manual/Plugins.pod 2007-05-30 10:45:24 UTC (rev 1093)
+++ trunk/lib/Template/Manual/Plugins.pod 2007-06-05 19:17:56 UTC (rev 1094)
@@ -26,7 +26,7 @@
=head2 Autoformat
-The L<Template::Plugin::Autoformat|Autoformat> plugin is an interface to
+The L<Autoformat|Template::Plugin::Autoformat> plugin is an interface to
Damian Conway's L<Text::Autoformat> Perl module which provides advanced text
wrapping and formatting. See L<Template::Plugin::Autoformat> and
L<Text::Autoformat> for further details.
@@ -41,7 +41,7 @@
=head2 CGI
-The L<Template::Plugin::CGI|CGI> plugin is a wrapper around Lincoln Stein's
+The L<CGI|Template::Plugin::CGI> plugin is a wrapper around Lincoln Stein's
CGI.pm module. The plugin is distributed with the Template Toolkit (see
L<Template::Plugin::CGI>) and the L<CGI> module itself is distributed with
recent versions Perl, or is available from CPAN.
@@ -80,7 +80,7 @@
=head2 Date
-The L<Template::Plugin::Date|Date> plugin provides an easy way to generate
+The L<Date|Template::Plugin::Date> plugin provides an easy way to generate
formatted time and date strings by delegating to the L<POSIX> C<strftime()>
routine. See L<Template::Plugin::Date> and L<POSIX> for further details.
@@ -91,7 +91,7 @@
=head2 Directory
-The L<Template::Plugin::Directory|Directory> plugin provides a simple
+The L<Directory|Template::Plugin::Directory> plugin provides a simple
interface to a directory and the files within it. See
L<Template::Plugin::Directory> for further details.
@@ -106,12 +106,12 @@
=head2 DBI
The C<DBI> plugin is no longer distributed as part of the Template Toolkit
-(as of version 2.15). It is now available as a separate C<Template-Plugin-DBI>
+(as of version 2.15). It is now available as a separate L<Template::DBI>
distribution from CPAN.
=head2 Dumper
-The L<Template::Plugin::Dumper|Dumper> plugin provides an interface to the
+The L<Dumper|Template::Plugin::Dumper> plugin provides an interface to the
Data::Dumper module. See L<Template::Plugin::Dumper> and L<Data::Dumper> for
futher details.
@@ -120,7 +120,7 @@
=head2 File
-The L<Template::Plugin::File|File> plugin provides a general abstraction for
+The L<File|Template::Plugin::File> plugin provides a general abstraction for
files and can be used to fetch information about specific files within a
filesystem. See L<Template::Plugin::File> for further details.
@@ -159,7 +159,7 @@
=head2 Format
-The L<Template::Plugin::Format|Format> plugin provides a simple way to format
+The L<Format|Template::Plugin::Format> plugin provides a simple way to format
text according to a C<printf()>-like format. See L<Template::Plugin::Format> for
further details.
@@ -169,11 +169,11 @@
=head2 GD
The C<GD> plugins are no longer part of the core Template Toolkit distribution.
-They are now available in a separate L<Template-GD|Template-GD> distribution.
+They are now available from CPAN in a separate L<Template::GD> distribution.
=head2 HTML
-The L<Template::Plugin::HTML|HTML> plugin is very basic, implementing a few
+The L<HTML|Template::Plugin::HTML> plugin is very basic, implementing a few
useful methods for generating HTML. It is likely to be extended in the future
or integrated with a larger project to generate HTML elements in a generic way.
@@ -186,7 +186,7 @@
=head2 Iterator
-The L<Template::Plugin::Iterator|Iterator> plugin provides a way to create a
+The L<Iterator|Template::Plugin::Iterator> plugin provides a way to create a
L<Template::Iterator> object to iterate over a data set. An iterator is
created automatically by the C<FOREACH> directive and is aliased to the C<loop>
variable. This plugin allows an iterator to be explicitly created with a given
@@ -218,7 +218,7 @@
=head2 String
-The L<Template::Plugin::String|String> plugin implements an object-oriented
+The L<String|Template::Plugin::String> plugin implements an object-oriented
interface for manipulating strings. See L<Template::Plugin::String> for
further details.
@@ -232,7 +232,7 @@
=head2 Table
-The L<Template::Plugin::Table|Table> plugin allows you to format a list of
+The L<Table|Template::Plugin::Table> plugin allows you to format a list of
data items into a virtual table by specifying a fixed number of rows or
columns, with an optional overlap. See L<Template::Plugin::Table> for further
details.
@@ -245,7 +245,7 @@
=head2 URL
-The L<Template::Plugin::URL|URL> plugin provides a simple way of contructing
+The L<URL|Template::Plugin::URL> plugin provides a simple way of contructing
URLs from a base part and a variable set of parameters. See
L<Template::Plugin::URL> for further details.
@@ -259,7 +259,7 @@
=head2 Wrap
-The L<Template::Plugin::Wrap|Wrap> plugin uses the L<Text::Wrap> module to
+The L<Wrap|Template::Plugin::Wrap> plugin uses the L<Text::Wrap> module to
provide simple paragraph formatting. See L<Template::Plugin::Wrap> and
L<Text::Wrap> for further details.
@@ -276,7 +276,7 @@
The C<XML::DOM>, C<XML::RSS>, C<XML::Simple> and C<XML::XPath> plugins are no
longer distributed with the Template Toolkit as of version 2.15
-They are now available in a separate L<Template-XML|Template-XML> distribution.
+They are now available in a separate L<Template::XML> distribution.
=cut
Modified: trunk/lib/Template/Manual/Variables.pod
===================================================================
--- trunk/lib/Template/Manual/Variables.pod 2007-05-30 10:45:24 UTC (rev 1093)
+++ trunk/lib/Template/Manual/Variables.pod 2007-06-05 19:17:56 UTC (rev 1094)
@@ -20,7 +20,7 @@
=head1 Template Variables
A reference to a hash array may be passed as the second argument to the
-L<Template#process()|process()> method, containing definitions of template
+L<process()|Template#process()> method, containing definitions of template
variables. The C<VARIABLES> (a.k.a. C<PRE_DEFINE>) option can also be used to
pre-define variables for all templates processed by the object.
Modified: trunk/lib/Template/Toolkit.pod
===================================================================
--- trunk/lib/Template/Toolkit.pod 2007-05-30 10:45:24 UTC (rev 1093)
+++ trunk/lib/Template/Toolkit.pod 2007-06-05 19:17:56 UTC (rev 1094)
@@ -56,7 +56,7 @@
=head1 Documentation
-The documentation for the Template Toolkit is organised into four sections.
+The documentation for the Template Toolkit is organised into five sections.
The L<Template::Manual> contains detailed information about using the Template
Toolkit. It gives examples of its use and includes a full reference of the
@@ -102,6 +102,9 @@
web content. The second is L<Template::Tutorial::Datafile> on using the
Template Toolkit to generate other data formats including XML.
+The final section of the manual is L<Template::FAQ> which contains answers
+to some of the Frequently Asked Questions about the Template Toolkit.
+
All of the documentation is also provided in HTML format in the
F<docs> sub-directory of the Template Toolkit distribution. You can
also read it online at the Template Toolkit web site:
Modified: trunk/lib/Template/Tools.pod
===================================================================
--- trunk/lib/Template/Tools.pod 2007-05-30 10:45:24 UTC (rev 1093)
+++ trunk/lib/Template/Tools.pod 2007-06-05 19:17:56 UTC (rev 1094)
@@ -28,7 +28,7 @@
=head2 tpage
-The L<Template::Tools::tpage|tpage> script can be used to process
+The L<tpage|Template::Tools::tpage> script can be used to process
a single template using the Template Toolkit.
$ tpage --define msg="Hello World" greeting.tt2
@@ -42,7 +42,7 @@
=head2 ttree
-The L<Template::Tools::ttree|ttree> script can be used to process
+The L<ttree|Template::Tools::ttree> script can be used to process
an entire directory of templates.
$ ttree --src /path/to/templates --dest /path/to/output