Edit:
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Template::Tutorial::Web 3"
.TH Template::Tutorial::Web 3 "2014-04-23" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Template::Tutorial::Web \- Generating Web Content Using the Template Toolkit
.SH "Overview"
.IX Header "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
tpage and ttree scripts
and then goes on to show dynamic content generation using \s-1CGI\s0 scripts and
Apache/mod_perl handlers.
.PP
Various features of the Template Toolkit are introduced and described briefly
and explained by use of example. For further information, see Template,
Template::Manual and the various sections within it. e.g
.PP
.Vb 3
\& perldoc Template # Template.pm module usage
\& perldoc Template::Manual # index to manual
\& perldoc Template::Manual::Config # e.g. configuration options
.Ve
.PP
The documentation is also available in \s-1HTML\s0 format to read online, or download
from the Template Toolkit web site:
.PP
.Vb 1
\& http://template\-toolkit.org/docs/
.Ve
.SH "Introduction"
.IX Header "Introduction"
The Template Toolkit is a set of Perl modules which collectively
implement a template processing system.
.PP
A template is a text document with special markup tags embedded in it.
By default, the Template Toolkit uses '\f(CW\*(C`[%\*(C'\fR' and '\f(CW\*(C`%]\*(C'\fR' to denote
the start and end of a tag. Here's an example:
.PP
.Vb 1
\& [% 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 %]
.Ve
.PP
Tags can contain simple \fIvariables\fR (like \f(CW\*(C`planet\*(C'\fR and \f(CW\*(C`captain\*(C'\fR) and more
complex \fIdirectives\fR that start with an upper case keyword (like \f(CW\*(C`INCLUDE\*(C'\fR).
A directive is an instruction that tells the template processor to perform
some action, like processing another template (\f(CW\*(C`header\*(C'\fR and \f(CW\*(C`footer\*(C'\fR in this
example) and inserting the output into the current template. In fact, the
simple variables we mentioned are actually \f(CW\*(C`GET\*(C'\fR directives, but the \f(CW\*(C`GET\*(C'\fR
keyword is optional.
.PP
.Vb 2
\& People of [% planet %], your attention please. # short form
\& People of [% GET planet %], your attention please. # long form
.Ve
.PP
Other directives include \f(CW\*(C`SET\*(C'\fR to set a variable value (the \f(CW\*(C`SET\*(C'\fR keyword is
also optional), \f(CW\*(C`FOREACH\*(C'\fR to iterate through a list of values, and \f(CW\*(C`IF\*(C'\fR,
\&\f(CW\*(C`UNLESS\*(C'\fR, \f(CW\*(C`ELSIF\*(C'\fR and \f(CW\*(C`ELSE\*(C'\fR to declare conditional blocks.
.PP
The Template Toolkit processes all \fItext\fR files equally, regardless of what
kind of content they contain. So you can use \s-1TT\s0 to generate \s-1HTML, XML, CSS,\s0
Javascript, Perl, \s-1RTF,\s0 LaTeX, or any other text-based format. In this tutorial,
however, we'll be concentrating on generating \s-1HTML\s0 for web pages.
.SH "Generating Static Web Content"
.IX Header "Generating Static Web Content"
Here's an example of a template used to generate an \s-1HTML\s0 document.
.PP
.Vb 2
\& [% INCLUDE header
\& title = \*(AqThis is an HTML example\*(Aq;
\&
\& pages = [
\& { url = \*(Aqhttp://foo.org\*(Aq
\& title = \*(AqThe Foo Organisation\*(Aq
\& }
\& { url = \*(Aqhttp://bar.org\*(Aq
\& title = \*(AqThe Bar Organisation\*(Aq
\& }
\& ]
\& %]
\& /usr/local/share/man/man3/Template::Tutorial::Web.3pm (34118B)
Some Interesting Links
\&-
\& [% FOREACH page IN pages %]
\&
- [% page.title %] \& [% END %] \&
\& © Copyright 2007 Arthur Dent
\&
\&
\&
.Ve
.PP
The example also uses the \f(CW\*(C`FOREACH\*(C'\fR directive to iterate through the
\&'\f(CW\*(C`pages\*(C'\fR' 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 '\f(CW\*(C`url\*(C'\fR' and '\f(CW\*(C`title\*(C'\fR' member. The \f(CW\*(C`FOREACH\*(C'\fR directive iterates
through the list, aliasing '\f(CW\*(C`page\*(C'\fR' to each item (in this case, hash array
references). The \f(CW\*(C`[% page.url %]\*(C'\fR and \f(CW\*(C`[% page.title %]\*(C'\fR directives then
access the individual values in the hash arrays and insert them into the
document.
.SS "Using tpage"
.IX Subsection "Using tpage"
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
tpage script. This is provided as part of the
Template Toolkit and should be installed in your usual Perl bin directory.
.PP
Assuming you saved your template file as \fIexample.html\fR, you would run
the command:
.PP
.Vb 1
\& $ tpage example.html
.Ve
.PP
This will process the template file, sending the output to \f(CW\*(C`STDOUT\*(C'\fR (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.
\&'\f(CW\*(C`.tt\*(C'\fR') and another (e.g. '\f(CW\*(C`.html\*(C'\fR') for the output files.
.PP
.Vb 1
\& $ tpage example.tt > example.html
.Ve
.PP
Or you can redirect the output to another directory. e.g.
.PP
.Vb 1
\& $ tpage templates/example.tt > html/example.html
.Ve
.PP
The output generated would look like this:
.PP
.Vb 10
\&
\&
\& Some Interesting Links
\&-
\&
- The Foo Organsiation \&
- The Bar Organsiation \&
\& © Copyright 2007 Arthur Dent
\&
\&
\&
.Ve
.PP
The \fIheader\fR and \fIfooter\fR 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 \s-1HTML\s0 list.
.SS "Using ttree"
.IX Subsection "Using ttree"
The tpage script gives you a simple and easy way to
process a single template without having to write any Perl code. The
\& [% END %]
\&
\& [% INCLUDE footer %]
.Ve
.PP
Here we've shown how pre-defined variables can be used as flags to
enable certain feature (e.g. \f(CW\*(C`graphics\*(C'\fR) and to specify common items
such as an email address and \s-1URL\s0'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.
.PP
When you run \fIttree\fR, you should see output similar to the following
(assuming you have the verbose flag set).
.PP
.Vb 1
\& 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: [ \eb(CVS|RCS)\eb, ^# ]
\& Copy: [ ]
\& Accept: [ * ]
\&
\& + newpage.html
.Ve
.PP
The \f(CW\*(C`+\*(C'\fR in front of the \f(CW\*(C`newpage.html\*(C'\fR 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 \f(CW\*(C`\-\*(C'\fR and giving a reason why the file wasn't processed.
.PP
.Vb 1
\& \- newpage.html (not modified)
.Ve
.PP
It has detected a \f(CW\*(C`newpage.html\*(C'\fR 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 \f(CW\*(C`\-a\*(C'\fR option. You can also specify one or more filenames as
command line arguments to \f(CW\*(C`ttree\*(C'\fR:
.PP
.Vb 1
\& tpage newpage.html
.Ve
.PP
This is what the destination page looks like.
.PP
\&\f(CW$dest\fR/newpage.html:
.PP
.Vb 5
\&
\&
\& 
\&
\&
\& © Copyright 2007 Arthur Dent
\&
\&
\&
.Ve
.PP
You can add as many documents as you like to the \f(CW\*(C`src\*(C'\fR directory and
\&\f(CW\*(C`ttree\*(C'\fR 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.
.SH "Dynamic Content Generation Via CGI Script"
.IX Header "Dynamic Content Generation Via CGI Script"
The Template module provides a simple front-end to the Template Toolkit for
use in \s-1CGI\s0 scripts and Apache/mod_perl handlers. Simply \f(CW\*(C`use\*(C'\fR the Template
module, create an object instance with the \fInew()\fR method and then call the
\&\fIprocess()\fR 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:
.PP
.Vb 4
\& #!/usr/bin/perl
\& use strict;
\& use warnings;
\& use Template;
\&
\& my $file = \*(Aqsrc/greeting.html\*(Aq;
\& my $vars = {
\& message => "Hello World\en"
\& };
\&
\& my $template = Template\->new();
\&
\& $template\->process($file, $vars)
\& || die "Template process failed: ", $template\->error(), "\en";
.Ve
.PP
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:
.PP
.Vb 6
\& my $template\->new({
\& # where to find template files
\& INCLUDE_PATH => [\*(Aq/home/abw/websrc/src\*(Aq, \*(Aq/home/abw/websrc/lib\*(Aq],
\& # pre\-process lib/config to define any extra values
\& PRE_PROCESS => \*(Aqconfig\*(Aq,
\& });
.Ve
.PP
Note that here we specify the \f(CW\*(C`config\*(C'\fR file as a \f(CW\*(C`PRE_PROCESS\*(C'\fR 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 \f(CW\*(C`process()\*(C'\fR method.
.PP
These entries in this hash may contain simple text or other values,
references to lists, others hashes, sub-routines or objects. The Template
Toolkit will automatically apply the correct procedure to access these
different types when you use the variables in a template.
.PP
Here's a more detailed example to look over. Amongst the different
template variables we define in \f(CW$vars\fR, we create a reference to a
\&\s-1CGI\s0 object and a \f(CW\*(C`get_user_projects()\*(C'\fR sub-routine.
.PP
.Vb 5
\& #!/usr/bin/perl
\& use strict;
\& use warnings;
\& use Template;
\& use CGI;
\&
\& $| = 1;
\& print "Content\-type: text/html\en\en";
\&
\& my $file = \*(Aquserinfo.html\*(Aq;
\& my $vars = {
\& \*(Aqversion\*(Aq => 3.14,
\& \*(Aqdays\*(Aq => [ qw( mon tue wed thu fri sat sun ) ],
\& \*(Aqworklist\*(Aq => \e&get_user_projects,
\& \*(Aqcgi\*(Aq => CGI\->new(),
\& \*(Aqme\*(Aq => {
\& \*(Aqid\*(Aq => \*(Aqabw\*(Aq,
\& \*(Aqname\*(Aq => \*(AqAndy Wardley\*(Aq,
\& },
\& };
\&
\& sub get_user_projects {
\& my $user = shift;
\& my @projects = ... # do something to retrieve data
\& return \e@projects;
\& }
\&
\& my $template = Template\->new({
\& INCLUDE_PATH => \*(Aq/home/abw/websrc/src:/home/abw/websrc/lib\*(Aq,
\& PRE_PROCESS => \*(Aqconfig\*(Aq,
\& });
\&
\& $template\->process($file, $vars)
\& || die $template\->error();
.Ve
.PP
Here's a sample template file that we might create to build the output
for this script.
.PP
\&\f(CW$src\fR/userinfo.html:
.PP
.Vb 3
\& [% INCLUDE header
\& title = \*(AqTemplate Toolkit CGI Test\*(Aq
\& %]
\&
\& Email [% me.name %]
\&
\& This is version [% version %]
\& \&Projects
\&-
\& [% FOREACH project IN worklist(me.id) %]
\&
- [% project.name %] \& [% END %] \&
| User ID | \&Name | \&|
|---|---|---|
| [% user.id %] | \&[% user.name %] | \&[% user.email %] | \&