Using Template Toolkit for Web Pages
Using Template Toolkit for Web Pages
Although having templates for the generation of static web pages offer many advantages, these would be moot if it were not quite easy to generate the HTML pages from the template files. This document discusses the mechanics of doing this.
First off, a brief detour describing the structure of directories in the PCS web document tree. Under each directory, there may be the special directories
The tt directory is where all the templates for the Perl Template Toolkit based web pages are. The templates therein should all end in an .tt extension. This directory does not need to be read by the web server, and the web server should not have read access to it. This directory should also contain an RCS subdirectory for storing past version history with the revision control system.
The m4 directory is the same as the tt directory, but the m4 based templates are stored here, with an .m4 extension.
Depending on when the content directory was created, it may have just a tt directory, just a m4 directory, or both. If it has neither, the HTML files are not template created.
The index-files directory may exist in some directories with
tt subdirectories. It is used to hold the .idx
files associated with the Template Toolkit created HTML files containing data
about how the page should be indexed. It should be readable by
phys:cron-pcswww-indexing but not by the web server.
The Makefile is typically just a symlink to the one in the parent directory, until one reaches the top of the PCS document tree.
If you are creating a new directory in the document structure, just create
the directory, along with tt and tt/RCS
subdirectories, and ln -s ../Makefile to make a symlink to the
makefile in the parent directory.
The good news is that this is all taken care of by the Makefile. Even the complications from having two systems for templating.
Generally, once you create a template in the tt subdirectory,
or edit an existing template in either the tt or m4
directories, you only need to return to the content directory and type
make. All template files in both directories are examined, and
if the corresponding HTML file is missing or older than the template, the
template will be processed to create the HTML file. For tt files with indexing
topics, the index-files directory will be created if needed and
the page specific .idx will be regenerated (The Master Index
files will not be updated until the nightly collection of all the individual
.idx files. )
On rare occasions, e.g. if changes were made to the base template
definitions but not the file specific content, the make command
may fail to regenerate a page you want regenerated (as it thinks there is no
need to). The program can be easily coerced into doing that for an individual
file by either using the touch command on the template file,
or by deleting the HTML file, and re-running make.
If you want to regenerate all the pages on the web (at least all PCS pages),
or all pages under a certain directory, you could run make in
each directory. But the scripts make_all_web_pages.pl and
force_make_all_web_pages.pl in the
/dept/phys/htdocs/tt-html-stuff will do that for you. Just run
the relevant script followed by the path to the top of the directory tree
you want to regenerate pages under (it defaults to the directory you are in),
and it will go through and run the make command in each subdirectory. The
force_make_all_web_pages.pl version actually touches each template
file first, forcing the html page to be regenerated, where as the other version
only regenerates pages that are out of date relative to the template.
