[% TAGS [** **] -%]
=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
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
the command:
tpage mypage.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.
tpage mypage.atml > mypage.html
tpage templates/mypage.html > html/mypage.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):
<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>
</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.
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.
perldoc ttree
ttree -h
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).
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.
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
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.
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.
$HOME/.ttreerc:
pre_process = config
interpolate
post_chomp
The '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'
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.
$lib/config:
[% root = '~/abw'
home = "$root/index.html"
images = "$root/images"
email = 'abw@kfs.org'
graphics = 1
webpages = [
{ url => 'http://foo.org', title => 'The Foo Organsiation' }
{ url => 'http://bar.org', title => 'The Bar Organsiation' }
]
%]
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>.
$src/newpage.html:
[% INCLUDE header
title = 'Another Template Toolkit Test Page'
%]
<a href="[% home %]">Home</a>
<a href="mailto:[% email %]">Email</a>
[% IF graphics %]
<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
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
(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: [ * ]
+ 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.
- newpage.html (not modified)
It has detected a '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>:
tpage newpage.html
This is what the destination page looks like.
$dest/newpage.html:
<html>
<head>
<title>Another Template Toolkit Test Page</title>
</head>
<body bgcolor="#ffffff">
<a href="~/abw/index.html">Home</a>
<a href="mailto:abw@kfs.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>
</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
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.