[Templates-svn] r1083 - in trunk/lib/Template: . Manual Tools Tutorial
svn@template-toolkit.org
svn@template-toolkit.org
Author: abw
Date: 2007-05-26 18:25:27 +0100 (Sat, 26 May 2007)
New Revision: 1083
Modified:
trunk/lib/Template/Manual/Plugins.pod
trunk/lib/Template/Plugin.pm
trunk/lib/Template/Tools/tpage.pod
trunk/lib/Template/Tools/ttree.pod
trunk/lib/Template/Tutorial/Web.pod
Log:
more documentation updates
Modified: trunk/lib/Template/Manual/Plugins.pod
===================================================================
--- trunk/lib/Template/Manual/Plugins.pod 2007-05-26 15:43:31 UTC (rev 1082)
+++ trunk/lib/Template/Manual/Plugins.pod 2007-05-26 17:25:27 UTC (rev 1083)
@@ -169,7 +169,7 @@
=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> distribution.
+They are now available in a separate L<Template::GD|Template-GD> distribution.
=head2 HTML
@@ -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> distribution.
+They are now available in a separate L<Template::XML|Template-XML> distribution.
=cut
Modified: trunk/lib/Template/Plugin.pm
===================================================================
--- trunk/lib/Template/Plugin.pm 2007-05-26 15:43:31 UTC (rev 1082)
+++ trunk/lib/Template/Plugin.pm 2007-05-26 17:25:27 UTC (rev 1083)
@@ -13,7 +13,7 @@
# COPYRIGHT
# Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
#
-# This module is free software; you can redistribute it and/or
+# This module is free software; you can redistribute it an/or
# modify it under the same terms as Perl itself.
#
#============================================================================
@@ -339,7 +339,7 @@
$self->{ _SERVER }->add_to_cache(@_);
}
-When the plugin is loaded, a L<MyServer> instance is created. The L<new()>
+When the plugin is loaded, a C<MyServer> instance is created. The L<new()>
method is called against this object which instantiates and returns a C<MyClient>
object, primed to communicate with the creating C<MyServer>.
Modified: trunk/lib/Template/Tools/tpage.pod
===================================================================
--- trunk/lib/Template/Tools/tpage.pod 2007-05-26 15:43:31 UTC (rev 1082)
+++ trunk/lib/Template/Tools/tpage.pod 2007-05-26 17:25:27 UTC (rev 1083)
@@ -43,27 +43,18 @@
Andy Wardley E<lt>abw@wardley.orgE<gt>
-L<http://wardley.org/|http://wardley.org/>
+L<http://wardley.org/>
-
-
-
-=head1 VERSION
-
-2.68, distributed as part of the
-Template Toolkit version 2.19, released on 27 April 2007.
-
=head1 COPYRIGHT
- Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
+Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
-
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
=head1 SEE ALSO
-L<ttree|Template::Tools::ttree>
+L<Template::Tools::ttree|ttree>
=cut
Modified: trunk/lib/Template/Tools/ttree.pod
===================================================================
--- trunk/lib/Template/Tools/ttree.pod 2007-05-26 15:43:31 UTC (rev 1082)
+++ trunk/lib/Template/Tools/ttree.pod 2007-05-26 17:25:27 UTC (rev 1083)
@@ -1,15 +1,3 @@
-
-#------------------------------------------------------------------------
-# 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::Tools::ttree - Process entire directory trees of templates
@@ -304,29 +292,23 @@
=head1 AUTHORS
-Andy Wardley E<lt>abw@andywardley.comE<gt>
+Andy Wardley E<lt>abw@wardley.orgE<gt>
-L<http://www.andywardley.com/|http://www.andywardley.com/>
+L<http://www.wardley.org>
With contributions from Dylan William Hardison (support for
dependencies), Bryce Harrington (C<absolute> and C<relative> options),
Mark Anderson (C<suffix> and C<debug> options), Harald Joerg and Leon
Brocard who gets everywhere, it seems.
-=head1 VERSION
-
-2.68, distributed as part of the
-Template Toolkit version 2.19, released on 27 April 2007.
-
=head1 COPYRIGHT
- Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
+Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
-
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
=head1 SEE ALSO
-L<tpage|Template::Tools::tpage>
+L<Template::Tools::tpage|tpage>
Modified: trunk/lib/Template/Tutorial/Web.pod
===================================================================
--- trunk/lib/Template/Tutorial/Web.pod 2007-05-26 15:43:31 UTC (rev 1082)
+++ trunk/lib/Template/Tutorial/Web.pod 2007-05-26 17:25:27 UTC (rev 1083)
@@ -3,7 +3,7 @@
# Template::Tutorial::Web
#
# DESCRIPTION
-
+# Tutorial on generating web content with the Template Toolkit
#
# AUTHOR
# Andy Wardley <abw@wardley.org>
@@ -14,264 +14,267 @@
# 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::Tutorial::Web - Generating Web Content Using the Template Toolkit
-=head1 DESCRIPTION
+=head1 Overview
-This tutorial document provides a introduction to the Template Toolkit
-and demonstrates some of the typical ways it may be used for
-generating web content. It covers the generation of static pages from
-templates using the L<tpage|Template::Tools::tpage> and
-L<ttree|Template::Tools::ttree> scripts and then goes on to
-show dynamic content generation using CGI scripts and Apache/mod_perl
-handlers.
+This tutorial document provides a introduction to the Template Toolkit and
+demonstrates some of the typical ways it may be used for generating web
+content. It covers the generation of static pages from templates using the
+L<Template::Tools::tpage|tpage> and L<Template::Tools::ttree|ttree> scripts
+and then goes on to show dynamic content generation using CGI scripts and
+Apache/mod_perl handlers.
-Various features of the Template Toolkit are introduced and described
-briefly and explained by use of example. For further information,
-see L<Template>, L<Template::Manual> and the various sections within
-it. e.g.
+Various features of the Template Toolkit are introduced and described briefly
+and explained by use of example. For further information, see L<Template>,
+L<Template::Manual> and the various sections within it. e.g
- perldoc Template # Template.pm module usage
- perldoc Template::Manual # index to manual
+ perldoc Template # Template.pm module usage
+ perldoc Template::Manual # index to manual
perldoc Template::Manual::Config # e.g. configuration options
-The documentation is now also distributed in HTML format (or rather,
-in the form of HTML templates). See the 'docs' sub-directory of the
-distribution for further information on building the HTML documentation.
+The documentation is now also distributed in HTML format in the
+F<docs> sub-directory of the Template Toolkit distribution.
-If you're already reading this as part of the HTML documentation, then
-you don't need to worry about all that. You can have a seat, sit back.
- back and enjoy the rest of the tutorial...
+You can also read it online at the Template Toolkit web site:
-=head1 INTRODUCTION
+ http://template-toolkit.org/docs/tutorial/Web.html
+=head1 Introduction
+
The Template Toolkit is a set of Perl modules which collectively
-implement a template processing system. In this context, a template
-is a text document containing special markup tags called 'directives'.
-A directive is an instruction for the template processor to perform
-some action and substitute the result into the document in place of
-the original directive. Directives include those to define or insert
-a variable value, iterate through a list of values (FOREACH), declare
-a conditional block (IF/UNLESS/ELSE), include and process another template
-file (INCLUDE) and so on.
+implement a template processing system.
-In all other respects, the document is a plain text file and may
-contain any other content (e.g. HTML, XML, RTF, LaTeX, etc). Directives
-are inserted in the document within the special markup tags which are
-'[%' and '%]' by default, but can be changed via the module
-configuration options. Here's an example of an HTML document with
-additional Template Toolkit directives.
+A template is a text document with special markup tags embedded in it.
+By default, the Template Toolkit uses 'C<[%>' and 'C<%]>' to denote
+the start and end of a tag. Here's an example:
- [% INCLUDE header
- title = 'This is an HTML example'
- %]
+ [% INCLUDE header %]
+
+ People of [% planet %], your attention please.
+
+ This is [% captain %] of the
+ Galactic Hyperspace Planning Council.
+
+ As you will no doubt be aware, the plans
+ for development of the outlying regions
+ of the Galaxy require the building of a
+ hyperspatial express route through your
+ star system, and regrettably your planet
+ is one of those scheduled for destruction.
+
+ The process will take slightly less than
+ [% time %].
+
+ Thank you.
+
+ [% INCLUDE footer %]
- <h1>Some Interesting Links</h1>
+Tags can contain simple I<variables> (like C<planet> and C<captain>) and more
+complex I<directives> that start with an upper case keyword (like C<INCLUDE>).
+A directive is an instruction that tells the template processor to perform
+some action, like processing another template (C<header> and C<footer> in this
+example) and inserting the output into the current template. In fact, the
+simple variables we mentioned are actually C<GET> directives, but the C<GET>
+keyword is optional.
- [% webpages = [
- { url => 'http://foo.org', title => 'The Foo Organisation' }
- { url => 'http://bar.org', title => 'The Bar Organisation' }
- ]
- %]
+ People of [% planet %], your attention please. # short form
+ People of [% GET planet %], your attention please. # long form
- Links:
- <ul>
- [% FOREACH link = webpages %]
- <li><a href="[% link.url %]">[% link.title %]</a>
- [% END %]
- </ul>
+Other directives include C<SET> to set a variable value (the C<SET> keyword is
+also optional), C<FOREACH> to iterate through a list of values, and C<IF>,
+C<UNLESS>, C<ELSIF> and C<ELSE> to declare conditional blocks.
- [% INCLUDE footer %]
+The Template Toolkit processes all I<text> files equally, regardless of what
+kind of content they contain. So you can use TT to generate HTML, XML, CSS,
+Javascript, Perl, RTF, LaTeX, or any other text-based format. In this tutorial,
+however, we'll be concentrating on generating HTML for web pages.
-This example shows how the INCLUDE directive is used to load and process
-separate 'header' and 'footer' template files, including the output in
-the current document. These files might look like this:
+=head1 Generating Static Web Content
-header:
+Here's an example of a template used to generate an HTML document.
- <html>
- <head>
- <title>[% title %]</title>
- </head>
+ [% INCLUDE header
+ title = 'This is an HTML example';
+
+ pages = [
+ { url = 'http://foo.org'
+ title = 'The Foo Organisation'
+ }
+ { url = 'http://bar.org'
+ title = 'The Bar Organisation'
+ }
+ ]
+ %]
+ <h1>Some Interesting Links</h1>
+ <ul>
+ [% FOREACH page IN pages %]
+ <li><a href="[% page.url %]">[% page.title %]</a>
+ [% END %]
+ </ul>
- <body bgcolor="#ffffff">
+ [% INCLUDE footer %]
-footer:
+This example shows how the C<INCLUDE> directive is used to load and process
+separate 'C<header>' and 'C<footer>' template files, including the output in
+the current document. These files might look something like this:
- <hr>
+header:
- <center>
- © Copyright 2000 Me, Myself, I
- </center>
+ <html>
+ <head>
+ <title>[% title %]</title>
+ </head>
+ <body>
- </body>
+footer:
+
+ <div class="copyright">
+ © Copyright 2007 Arthur Dent
+ </div>
+ </body>
</html>
-The example also uses the FOREACH directive to iterate through the
-'webpages' list to build a table of links. In this example, we have
-defined this list within the template to contain a number of hash references,
-each containing a 'url' and 'title' member. The FOREACH directive
-iterates through the list, aliasing 'link' to each item (hash ref).
-The B<[% link.url %]> and B<[% link.title %]> directives then access
-the individual values in the hash and insert them into the document.
+The example also uses the C<FOREACH> directive to iterate through the
+'C<pages>' list to build a table of links. In this example, we have defined
+this list within the template to contain a number of hash references, each
+containing a 'C<url>' and 'C<title>' member. The C<FOREACH> directive iterates
+through the list, aliasing 'C<page>' to each item (in this case, hash array
+references). The C<[% page.url %]> and C<[% page.title %]> directives then
+access the individual values in the hash ararys and insert them into the
+document.
-The following sections show other ways in which data can be defined for
-use in a template.
+=head2 Using tpage
-=head1 GENERATING STATIC PAGES
+Having created a template file we can now process it to generate some real
+output. The quickest and easiest way to do this is to use the
+L<Template::Tools::tpage|tpage> script. This is provided as part of the
+Template Toolkit and should be installed in your usual Perl bin directory.
-Having created a template file we can now process it to generate some
-real output. The quickest and easiest way to do this is to use the
-F<tpage> script. This is provided as part of the Template Toolkit and
-should be installed in your usual Perl bin directory.
-
-Assuming you saved your template file as 'mypage.html', you would run
+Assuming you saved your template file as F<example.html>, you would run
the command:
- tpage mypage.html
+ $ tpage example.html
-This will process the template file, sending the output to STDOUT
-(i.e. whizzing past you on the screen). You may want to redirect the
-output to a file but be careful not to specify the same name as the
-template file, or you'll overwrite it. You may want to use one prefix
-for your templates such as '.atml' (for 'Another Template Markup
-Language', perhaps?) and the regular '.html' for the output files
-(assuming you're creating HTML, that is). Alternatively, you might
-redirect the output to another directory. e.g.
+This will process the template file, sending the output to C<STDOUT> (i.e.
+whizzing past you on the screen). You may want to redirect the output to a
+file but be careful not to specify the same name as the template file, or
+you'll overwrite it. You may want to use one prefix for your templates (e.g.
+'C<.tt>') and another (e.g. 'C<.html>') for the output files.
- tpage mypage.atml > mypage.html
- tpage templates/mypage.html > html/mypage.html
+ $ tpage example.tt > example.html
-The B<tpage> script is very basic and only really intended to give you
-an easy way to process a template without having to write any Perl code.
-A much more flexible tool is B<ttree>, described below, but for now let's
-look at the output generated by processing the above example (some
-whitespace removed for brevity):
+Or you can redirect the output to another directory. e.g.
+ $ tpage templates/example.tt > html/example.html
+
+The output generated would look like this:
+
<html>
- <head>
- <title>This is an HTML example</title>
- </head>
-
- <body bgcolor="#ffffff">
-
- <h1>Some Interesting Links</h1>
-
- Links:
- <ul>
- <li><a href="http://foo.org">The Foo Organsiation</a>
- <li><a href="http://bar.org">The Bar Organsiation</a>
- </ul>
-
- <hr>
-
- <center>
- © Copyright 2000 Me, Myself, I
- </center>
-
- </body>
+ <head>
+ <title>This is an HTML example</title>
+ </head>
+ <body>
+ <h1>Some Interesting Links</h1>
+ <ul>
+ <li><a href="http://foo.org">The Foo Organsiation</a>
+ <li><a href="http://bar.org">The Bar Organsiation</a>
+ </ul>
+ <div class="copyright">
+ © Copyright 2007 Arthur Dent
+ </div>
+ </body>
</html>
The F<header> and F<footer> template files have been included (assuming
you created them and they're in the current directory) and the link data
has been built into an HTML list.
-The F<ttree> script, also distributed as part of the Template Toolkit,
-provides a more flexible way to process template documents. The first
-time you run the script, it will ask you if it should create a
-configuration file, usually called '.ttreerc' in your home directory.
-Answer 'y' to have it create the file.
+=head2 Using ttree
-The F<ttree> documentation describes how you can change the location
-of this file and also explains the syntax and meaning of the various
-options in the file. Comments are written to the sample configuration
-file which should also help.
+The L<Template::Tools::tpage|tpage> script gives you a simple and easy way to
+process a single template without having to write any Perl code. The
+L<Template::Tools::ttree|ttree> script, also distributed as part of the
+Template Toolkit, provides a more flexible way to process a number of template
+documents in one go.
- perldoc ttree
- ttree -h
+The first time you run the script, it will ask you if it should create a
+configuration file (F<.ttreerc>) in your home directory. Answer C<y> to have
+it create the file.
-In brief, the configuration file describes the directories in which
-template files are to be found (src), where the corresponding output
-should be written to (dest), and any other directories (lib) that may
-contain template files that you plan to INCLUDE into your source
-documents. You can also specify processing options (such as 'verbose'
-and 'recurse') and provide regular expression to match files that you
-don't want to process (ignore, accept) or should be copied instead of
-processed (copy).
+The L<Template::Tools::ttree|ttree> documentation describes how you can change
+the location of this file and also explains the syntax and meaning of the
+various options in the file. Comments are written to the sample configuration
+file which should also help.
+In brief, the configuration file describes the directories in which template
+files are to be found (C<src>), where the corresponding output should be
+written to (C<dest>), and any other directories (C<lib>) that may contain
+template files that you plan to C<INCLUDE> into your source documents. You can
+also specify processing options (such as C<verbose> and C<recurse>) and provide
+regular expression to match files that you don't want to process (C<ignore>,
+C<accept>)> or should be copied instead of being processed as templates (C<copy>).
+
An example F<.ttreerc> file is shown here:
$HOME/.ttreerc:
+
verbose
recurse
-
+
# this is where I keep other ttree config files
cfg = ~/.ttree
-
+
src = ~/websrc/src
lib = ~/websrc/lib
dest = ~/public_html/test
-
+
ignore = \b(CVS|RCS)\b
ignore = ^#
You can create many different configuration files and store them
-in the directory specified in the 'cfg' option, shown above. You then
-add the C<-f filename> option to F<ttree> to have it read that file.
+in the directory specified in the C<cfg> option, shown above. You then
+add the C<-f filename> option to C<ttree> to have it read that file.
-When you run the script, it compares all the files in the 'src' directory
-(including those in sub-directories if the 'recurse' option is set), with
-those in the 'dest' directory. If the destination file doesn't exist or
+When you run the script, it compares all the files in the C<src> directory
+(including those in sub-directories if the C<recurse> option is set), with
+those in the C<dest> directory. If the destination file doesn't exist or
has an earlier modification time than the corresponding source file, then
the source will be processed with the output written to the destination
file. The C<-a> option forces all files to be processed, regardless of
modification times.
-The script I<doesn't> process any of the files in the 'lib' directory,
-but it does add it to the INCLUDE_PATH for the template processor so
-that it can locate these files via an INCLUDE or PROCESS directive.
-Thus, the 'lib' directory is an excellent place to keep template elements
-such as header, footers, etc., that aren't complete documents in their
-own right.
+The script I<doesn't> process any of the files in the C<lib> directory, but it
+does add it to the C<INCLUDE_PATH> for the template processor so that it can
+locate these files via an C<INCLUDE>, C<PROCESS> or C<WRAPPER> directive.
+Thus, the C<lib> directory is an excellent place to keep template elements
+such as header, footers, etc., that aren't complete documents in their own
+right.
You can also specify various Template Toolkit options from the configuration
-file. Consult the B<ttree> documentation and help summary (C<ttree -h>)
-for full details. e.g.
+file. Consult the L<Template::Tools::ttree|ttree> documentation and help
+summary (C<ttree -h>) for full details. e.g.
$HOME/.ttreerc:
+
pre_process = config
interpolate
post_chomp
-The 'pre_process' option allows you to specify a template file which
+The C<pre_process> option allows you to specify a template file which
should be processed before each file. Unsurprisingly, there's also a
-'post_process' option to add a template after each file. In the
-fragment above, we have specified that the 'config' template should be
-used as a prefix template. We can create this file in the 'lib'
+C<post_process> option to add a template after each file. In the
+fragment above, we have specified that the C<config> template should be
+used as a prefix template. We can create this file in the C<lib>
directory and use it to define some common variables, including those
web page links we defined earlier and might want to re-use in other
templates. We could also include an HTML header, title, or menu bar
in this file which would then be prepended to each and every template
-file, but for now we'll keep all that in a separate 'header' file.
+file, but for now we'll keep all that in a separate C<header> file.
$lib/config:
@@ -286,59 +289,59 @@
]
%]
-Assuming you've created or copied the 'header' and 'footer' files from the
-earlier example into your 'lib' directory, you can now start to create
-web pages like the following in your 'src' directory and process them
-with F<ttree>.
+Assuming you've created or copied the C<header> and C<footer> files from the
+earlier example into your C<lib> directory, you can now start to create
+web pages like the following in your C<src> directory and process them
+with C<ttree>.
$src/newpage.html:
[% INCLUDE header
title = 'Another Template Toolkit Test Page'
%]
-
- <a href="[% home %]">Home</a>
- <a href="mailto:[% email %]">Email</a>
-
+
+ <a href="[% home %]">Home</a>
+ <a href="mailto:[% email %]">Email</a>
+
[% IF graphics %]
- <img src="[% images %]/logo.gif" align=right width=60 height=40>
+ <img src="[% images %]/logo.gif" align=right width=60 height=40>
[% END %]
-
+
[% INCLUDE footer %]
Here we've shown how pre-defined variables can be used as flags to
-enable certain feature (e.g. 'graphics') and to specify common items
+enable certain feature (e.g. C<graphics>) and to specify common items
such as an email address and URL's for the home page, images directory
and so on. This approach allows you to define these values once so
that they're consistent across all pages and can easily be changed to
new values.
-When you run B<ttree>, you should see output similar to the following
+When you run F<ttree>, you should see output similar to the following
(assuming you have the verbose flag set).
- ttree 1.14 (Template Toolkit version 1.02a)
-
- Source: /home/abw/websrc/src
- Destination: /home/abw/public_html/test
- Include Path: [ /home/abw/websrc/lib ]
- Ignore: [ \b(CVS|RCS)\b, ^# ]
- Copy: [ ]
- Accept: [ * ]
-
+ ttree 2.9 (Template Toolkit version 2.20)
+
+ Source: /home/abw/websrc/src
+ Destination: /home/abw/public_html/test
+ Include Path: [ /home/abw/websrc/lib ]
+ Ignore: [ \b(CVS|RCS)\b, ^# ]
+ Copy: [ ]
+ Accept: [ * ]
+
+ newpage.html
-The '+' before 'newpage.html' shows that the file was processed, with
-the output being written to the destination directory. If you run the
-same command again, you'll see the following line displayed instead
-showing a '-' and giving a reason why the file wasn't processed.
+The C<+> in front of the C<newpage.html> filename shows that the file was
+processed, with the output being written to the destination directory. If you
+run the same command again, you'll see the following line displayed instead
+showing a C<-> and giving a reason why the file wasn't processed.
- newpage.html (not modified)
-It has detected a 'newpage.html' in the destination directory which is
+It has detected a C<newpage.html> in the destination directory which is
more recent than that in the source directory and so hasn't bothered
to waste time re-processing it. To force all files to be processed,
use the C<-a> option. You can also specify one or more filenames as
-command line arguments to F<ttree>:
+command line arguments to C<ttree>:
tpage newpage.html
@@ -347,75 +350,69 @@
$dest/newpage.html:
<html>
- <head>
- <title>Another Template Toolkit Test Page</title>
- </head>
-
- <body bgcolor="#ffffff">
+ <head>
+ <title>Another Template Toolkit Test Page</title>
+ </head>
+ <body>
- <a href="~/abw/index.html">Home</a>
- <a href="mailto:abw@wardley.org">Email me</a>
-
- <img src="~/abw/images/logo.gif" align=right width=60 height=40>
+ <a href="~/abw/index.html">Home</a>
+ <a href="mailto:abw@wardley.org">Email me</a>
+ <img src="~/abw/images/logo.gif" align=right width=60 height=40>
- <hr>
-
- <center>
- © Copyright 2000 Me, Myself, I
- </center>
-
- </body>
+ <div class="copyright">
+ © Copyright 2007 Arthur Dent
+ </div>
+ </body>
</html>
-You can add as many documents as you like to the 'src' directory and
-F<ttree> will apply the same process to them all. In this way, it is
+You can add as many documents as you like to the C<src> directory and
+C<ttree> will apply the same process to them all. In this way, it is
possible to build an entire tree of static content for a web site with
a single command. The added benefit is that you can be assured of
consistency in links, header style, or whatever else you choose to
implement in terms of common templates elements or variables.
-=head1 DYNAMIC CONTENT GENERATION VIA CGI SCRIPT
+=head1 Dynamic Content Generation Via CGI Script
-The L<Template|Template> module provides a simple front-end to the Template
-Toolkit for use in CGI scripts and Apache/mod_perl handlers. Simply
-'use' the Template module, create an object instance with the new()
-method and then call the process() method on the object, passing the
-name of the template file as a parameter. The second parameter passed
-is a reference to a hash array of variables that we want made available
-to the template:
+The L<Template> module provides a simple front-end to the Template Toolkit for
+use in CGI scripts and Apache/mod_perl handlers. Simply C<use> the L<Template>
+module, create an object instance with the L<new()> method and then call the
+L<process()> method on the object, passing the name of the template file as a
+parameter. The second parameter passed is a reference to a hash array of
+variables that we want made available to the template:
- #!/usr/bin/perl -w
-
+ #!/usr/bin/perl
use strict;
+ use warnings;
use Template;
-
+
my $file = 'src/greeting.html';
my $vars = {
message => "Hello World\n"
};
-
+
my $template = Template->new();
-
+
$template->process($file, $vars)
- || die "Template process failed: ", $template->error(), "\n";
+ || die "Template process failed: ", $template->error(), "\n";
So that our scripts will work with the same template files as our earlier
examples, we'll can add some configuration options to the constructor to
tell it about our environment:
my $template->new({
- # where to find template files
- INCLUDE_PATH => '/home/abw/websrc/src:/home/abw/websrc/lib',
- # pre-process lib/config to define any extra values
- PRE_PROCESS => 'config',
+ # where to find template files
+ INCLUDE_PATH => ['/home/abw/websrc/src', '/home/abw/websrc/lib'],
+ # pre-process lib/config to define any extra values
+ PRE_PROCESS => 'config',
});
-Note that here we specify the 'config' file as a PRE_PROCESS option.
+Note that here we specify the C<config> file as a C<PRE_PROCESS> option.
This means that the templates we process can use the same global
variables defined earlier for our static pages. We don't have to
replicate their definitions in this script. However, we can supply
additional data and functionality specific to this script via the hash
-of variables that we pass to the process() method.
+of variables that we pass to the C<process()> method.
These entries in this hash may contain simple text or other values,
references to lists, others hashes, sub-routines or objects. The Template
@@ -424,42 +421,42 @@
Here's a more detailed example to look over. Amongst the different
template variables we define in C<$vars>, we create a reference to a
-CGI object and a 'get_user_projects' sub-routine.
+L<CGI> object and a C<get_user_projects()> sub-routine.
- #!/usr/bin/perl -w
-
+ #!/usr/bin/perl
use strict;
+ use warnings;
use Template;
use CGI;
-
+
$| = 1;
print "Content-type: text/html\n\n";
-
+
my $file = 'userinfo.html';
my $vars = {
'version' => 3.14,
- 'days' => [ qw( mon tue wed thu fri sat sun ) ],
- 'worklist' => \&get_user_projects,
+ 'days' => [ qw( mon tue wed thu fri sat sun ) ],
+ 'worklist' => \&get_user_projects,
'cgi' => CGI->new(),
- 'me' => {
+ 'me' => {
'id' => 'abw',
'name' => 'Andy Wardley',
- },
+ },
};
-
+
sub get_user_projects {
- my $user = shift;
- my @projects = ... # do something to retrieve data
- return \@projects;
+ my $user = shift;
+ my @projects = ... # do something to retrieve data
+ return \@projects;
}
-
+
my $template = Template->new({
- INCLUDE_PATH => '/home/abw/websrc/src:/home/abw/websrc/lib',
- PRE_PROCESS => 'config',
+ INCLUDE_PATH => '/home/abw/websrc/src:/home/abw/websrc/lib',
+ PRE_PROCESS => 'config',
});
-
+
$template->process($file, $vars)
- || die $template->error();
+ || die $template->error();
Here's a sample template file that we might create to build the output
for this script.
@@ -469,27 +466,26 @@
[% INCLUDE header
title = 'Template Toolkit CGI Test'
%]
-
+
<a href="mailto:[% email %]">Email [% me.name %]</a>
-
+
<p>This is version [% version %]</p>
-
+
<h3>Projects</h3>
<ul>
- [% FOREACH project = worklist(me.id) %]
+ [% FOREACH project IN worklist(me.id) %]
<li> <a href="[% project.url %]">[% project.name %]</a>
[% END %]
</ul>
-
+
[% INCLUDE footer %]
-This example shows how we've separated the Perl implementation (code) from
-the presentation (HTML) which not only makes them easier to maintain in
-isolation, but also allows the re-use of existing template elements
-such as headers and footers, etc. By using template to create the
-output of your CGI scripts, you can give them the same consistency
-as your static pages built via L<ttree|Template::Tools::ttree> or
-other means.
+This example shows how we've separated the Perl implementation (code) from the
+presentation (HTML). This not only makes them easier to maintain in isolation,
+but also allows the re-use of existing template elements such as headers and
+footers, etc. By using template to create the output of your CGI scripts, you
+can give them the same consistency as your static pages built via
+L<Template::Tools::ttree|ttree> or other means.
Furthermore, we can modify our script so that it processes any one of a
number of different templates based on some condition. A CGI script to
@@ -501,33 +497,31 @@
application and then choose one or other template to generate the
desired output for the application state.
-=head1 DYNAMIC CONTENT GENERATION VIA APACHE/MOD_PERL HANDLER
+=head1 Dynamic Content Generation Via Apache/Mod_Perl Handler
-B<NOTE:> the Apache::Template module is now available from CPAN
-and provides a simple and easy to use Apache/mod_perl interface to the
-Template Toolkit. It's only in it's first release (0.01) at the time
-of writing and it currently only offers a fairly basic facility, but
-it implements most, if not all of what is described below, and it
-avoids the need to write your own handler. However, in many cases,
-you'll want to write your own handler to customise processing for your
-own need, and this section will show you how to get started.
+B<NOTE:> the L<Apache::Template> module is available from CPAN and provides a
+simple and easy to use Apache/mod_perl interface to the Template Toolkit.
+Although basic, it implements most, if not all of what is described below, and
+it avoids the need to write your own handler. However, in many cases, you'll
+want to write your own handler to customise processing for your own need, and
+this section will show you how to get started.
-The Template module can be used in a similar way from an Apache/mod_perl
-handler. Here's an example of a typical Apache F<httpd.conf> file:
+The L<Template> module can be used from an Apache/mod_perl handler. Here's an
+example of a typical Apache F<httpd.conf> file:
PerlModule CGI;
PerlModule Template
PerlModule MyOrg::Apache::User
-
+
PerlSetVar websrc_root /home/abw/websrc
-
+
<Location /user/bin>
SetHandler perl-script
PerlHandler MyOrg::Apache::User
</Location>
-This defines a location called '/user/bin' to which all requests will
-be forwarded to the handler() method of the MyOrg::Apache::User
+This defines a location called C</user/bin> to which all requests will
+be forwarded to the C<handler()> method of the C<MyOrg::Apache::User>
module. That module might look something like this:
package MyOrg::Apache::User;
@@ -541,97 +535,94 @@
$VERSION = 1.59;
sub handler {
- my $r = shift;
-
- my $websrc = $r->dir_config('websrc_root')
- or return fail($r, SERVER_ERROR,
- "'websrc_root' not specified");
-
- my $template = Template->new({
- INCLUDE_PATH => "$websrc/src/user:$websrc/lib",
- PRE_PROCESS => 'config',
- OUTPUT => $r, # direct output to Apache request
- });
-
- my $params = {
- uri => $r->uri,
- cgi => CGI->new,
- };
-
- # use the path_info to determine which template file to process
- my $file = $r->path_info;
- $file =~ s[^/][];
-
- $r->content_type('text/html');
- $r->send_http_header;
-
- $template->process($file, $params)
- || return fail($r, SERVER_ERROR, $template->error());
-
- return OK;
+ my $r = shift;
+
+ my $websrc = $r->dir_config('websrc_root')
+ or return fail($r, SERVER_ERROR,
+ "'websrc_root' not specified");
+
+ my $template = Template->new({
+ INCLUDE_PATH => "$websrc/src/user:$websrc/lib",
+ PRE_PROCESS => 'config',
+ OUTPUT => $r, # direct output to Apache request
+ });
+
+ my $params = {
+ uri => $r->uri,
+ cgi => CGI->new,
+ };
+
+ # use the path_info to determine which template file to process
+ my $file = $r->path_info;
+ $file =~ s[^/][];
+
+ $r->content_type('text/html');
+ $r->send_http_header;
+
+ $template->process($file, $params)
+ || return fail($r, SERVER_ERROR, $template->error());
+
+ return OK;
}
sub fail {
- my ($r, $status, $message) = @_;
- $r->log_reason($message, $r->filename);
- return $status;
+ my ($r, $status, $message) = @_;
+ $r->log_reason($message, $r->filename);
+ return $status;
}
-The handler accepts the request and uses it to determine the 'websrc_root'
-value from the config file. This is then used to define an INCLUDE_PATH
-for a new Template object. The URI is extracted from the request and a
-CGI object is created. These are both defined as template variables.
+The handler accepts the request and uses it to determine the C<websrc_root>
+value from the config file. This is then used to define an C<INCLUDE_PATH>
+for a new L<Template> object. The URI is extracted from the request and a
+L<CGI> object is created. These are both defined as template variables.
-The name of the template file itself is taken from the PATH_INFO element
+The name of the template file itself is taken from the C<PATH_INFO> element
of the request. In this case, it would comprise the part of the URL
-coming after '/user/bin', e.g for '/user/bin/edit', the template file
-would be 'edit' located in "$websrc/src/user". The headers are sent
+coming after C</user/bin>, e.g for C</user/bin/edit>, the template file
+would be C<edit> located in C<$websrc/src/user>. The headers are sent
and the template file is processed. All output is sent directly to the
-print() method of the Apache request object.
+C<print()> method of the Apache request object.
-=head1 USING PLUGINS TO EXTEND FUNCTIONALITY
+=head1 Using Plugins to Extend Functionality
As we've already shown, it is possible to bind Perl data and functions
to template variables when creating dynamic content via a CGI script
or Apache/mod_perl process. The Template Toolkit also supports a
plugin interface which allows you define such additional data and/or
functionality in a separate module and then load and use it as
-required with the USE directive.
+required with the C<USE> directive.
The main benefit to this approach is that you can load the extension into
any template document, even those that are processed "statically" by
-F<tpage> or F<ttree>. You I<don't> need to write a Perl wrapper to
+C<tpage> or C<ttree>. You I<don't> need to write a Perl wrapper to
explicitly load the module and make it available via the stash.
-Let's demonstrate this principle using the DBI plugin written by Simon
-Matthews E<lt>sam@knowledgepool.comE<gt>. You can create this
-template in your 'src' directory and process it using F<ttree> to see
-the results. Of course, this example relies on the existence of the
-appropriate SQL database but you should be able to adapt it to your
-own resources, or at least use it as a demonstrative example of what's
-possible.
+Let's demonstrate this principle using the C<DBI> plugin written by Simon
+Matthews (available from CPAN). You can create this template in your C<src>
+directory and process it using C<ttree> to see the results. Of course, this
+example relies on the existence of the appropriate SQL database but you should
+be able to adapt it to your own resources, or at least use it as a
+demonstrative example of what's possible.
[% INCLUDE header
- title = 'User Info'
+ title = 'User Info'
%]
[% USE DBI('dbi:mSQL:mydbname') %]
<table border=0 width="100%">
- <tr>
- <th>User ID</th>
- <th>Name</th>
- <th>Email</th>
- </tr>
-
- [% FOREACH user = DBI.query('SELECT * FROM user ORDER BY id') %]
- <tr>
- <td>[% user.id %]</td>
- <td>[% user.name %]</td>
- <td>[% user.email %]</td>
- </tr>
+ <tr>
+ <th>User ID</th>
+ <th>Name</th>
+ <th>Email</th>
+ </tr>
+ [% FOREACH user IN DBI.query('SELECT * FROM user ORDER BY id') %]
+ <tr>
+ <td>[% user.id %]</td>
+ <td>[% user.name %]</td>
+ <td>[% user.email %]</td>
+ </tr>
[% END %]
-
</table>
[% INCLUDE footer %]
@@ -639,77 +630,54 @@
A plugin is simply a Perl module in a known location and conforming to
a known standard such that the Template Toolkit can find and load it
automatically. You can create your own plugin by inheriting from the
-F<Template::Plugin> module.
+L<Template::Plugin> module.
-Here's an example which defines some data items ('foo' and 'people')
-and also an object method ('bar'). We'll call the plugin 'FooBar' for
-want of a better name and create it in the 'MyOrg::Template::Plugin::FooBar'
-package. We've added a 'MyOrg' to the regular 'Template::Plugin::*' package
+Here's an example which defines some data items (C<foo> and C<people>)
+and also an object method (C<bar>). We'll call the plugin C<FooBar> for
+want of a better name and create it in the C<MyOrg::Template::Plugin::FooBar>
+package. We've added a C<MyOrg> to the regular C<Template::Plugin::*> package
to avoid any conflict with existing plugins.
-You can create a module stub using the Perl utlity F<h2xs>:
-
- h2xs -A -X -n MyOrg::Template::Plugin::FooBar
-
-This will create a directory structure representing the package name
-along with a set of files comprising your new module. You can then
-edit FooBar.pm to look something like this:
-
package MyOrg::Template::Plugin::FooBar;
-
- use Template::Plugin;
- use vars qw( $VERSION );
- use base qw( Template::Plugin );
-
- $VERSION = 1.23;
-
+ use base 'Template::Plugin'
+ our $VERSION = 1.23;
+
sub new {
my ($class, $context, @params) = @_;
-
- bless {
- _CONTEXT => $context,
+
+ bless {
+ _CONTEXT => $context,
foo => 25,
people => [ 'tom', 'dick', 'harry' ],
- }, $class;
+ }, $class;
}
-
+
sub bar {
- my ($self, @params) = @_;
- # ...do something...
- return $some_value;
+ my ($self, @params) = @_;
+ # ...do something...
+ return $some_value;
}
-The plugin constructor new() receives the class name as the first
-parameter, as is usual in Perl, followed by a reference to something
-called a Template::Context object. You don't need to worry too much
-about this at the moment, other than to know that it's the main
-processing object for the Template Toolkit. It provides access to the
-functionality of the processor and some plugins may need to
-communicate with it. We don't at this stage, but we'll save the
-reference anyway in the '_CONTEXT' member. The leading underscore is
-a convention which indicates that this item is private and the
-Template Toolkit won't attempt to access this member. The other
-members defined, 'foo' and 'people' are regular data items which will be
-made available to templates using this plugin. Following the context
-reference are passed any additional parameters specified with the
-USE directive, such as the data source parameter, 'dbi:mSQL:mydbname',
-that we used in the earlier DBI example.
+The plugin constructor C<new()> receives the class name as the first
+parameter, as is usual in Perl, followed by a reference to something called a
+L<Template::Context> object. You don't need to worry too much about this at
+the moment, other than to know that it's the main processing object for the
+Template Toolkit. It provides access to the functionality of the processor and
+some plugins may need to communicate with it. We don't at this stage, but
+we'll save the reference anyway in the C<_CONTEXT> member. The leading
+underscore is a convention which indicates that this item is private and the
+Template Toolkit won't attempt to access this member. The other members
+defined, C<foo> and C<people> are regular data items which will be made
+available to templates using this plugin. Following the context reference are
+passed any additional parameters specified with the USE directive, such as the
+data source parameter, C<dbi:mSQL:mydbname>, that we used in the earlier DBI
+example.
-If you used F<h2xs> to create the module stub then you'll already
-have a Makefile.PL and you can incite the familiar incantation to
-build and install it. Don't forget to add some tests to test.pl!
-
- perl Makefile.PL
- make
- make test
- make install
-
If you don't or can't install it to the regular place for your Perl
modules (perhaps because you don't have the required privileges) then
you can set the PERL5LIB environment variable to specify another location.
-If you're using F<ttree> then you can add the following line to your
-configuration file instead. This has the effect of add '/path/to/modules'
-to the @INC array to a similar end.
+If you're using C<ttree> then you can add the following line to your
+configuration file instead.
$HOME/.ttreerc:
@@ -722,14 +690,14 @@
plugin_base = 'MyOrg::Template::Plugin'
-If you're writing Perl code to control the Template modules directly,
+If you're writing Perl code to control the L<Template> modules directly,
then this value can be passed as a configuration parameter when you
create the module.
use Template;
-
+
my $template = Template->new({
- PLUGIN_BASE => 'MyOrg::Template::Plugin'
+ PLUGIN_BASE => 'MyOrg::Template::Plugin'
});
Now we can create a template which uses this plugin:
@@ -737,20 +705,20 @@
[% INCLUDE header
title = 'FooBar Plugin Test'
%]
-
+
[% USE FooBar %]
-
+
Some values available from this plugin:
[% FooBar.foo %] [% FooBar.bar %]
-
+
The users defined in the 'people' list:
[% FOREACH uid = FooBar.people %]
* [% uid %]
[% END %]
-
+
[% INCLUDE footer %]
-The 'foo', 'bar' and 'people' items of the FooBar plugin are
+The C<foo>, C<bar>, and C<people> items of the FooBar plugin are
automatically resolved to the appropriate data items or method calls
on the underlying object.
@@ -765,25 +733,15 @@
Andy Wardley E<lt>abw@wardley.orgE<gt>
-L<http://wardley.org/|http://wardley.org/>
+L<http://wardley.org/>
-
-
-
-=head1 VERSION
-
-Template Toolkit version 2.19, released on 27 April 2007.
-
=head1 COPYRIGHT
- Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
+Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
-
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
-
-
=cut
# Local Variables: