Creating Web Templates with TT
Creating Web Templates with TT
So, what's involved in actually creating templates for web pages using the template toolkit. Here again, the good news is that it can be quite simple. Although you are encouraged to use template toolkit helper macros (as this can be used to enforce some consistency), the basic challenge of standardizing the "boilerplate" stuff can be done by adding a single line to the top and bottom of your content. Everything else can be left the same if desired.
So a simple page, with full PNCE boiler plate, can be created with just the lines:
[% standard_pnce_header('Title of Page'); %]<h1>My web page</h1>
Hello, World!
[% w3c_valid_pnce_footer %]These will be explained shortly, but first a brief digression in the syntax of the language.
Before we proceed any further, we are just going to very briefly touch on some basics of the Template Toolkit Templating Language. A bit more depth is provided here, with references to where you can get in depth information.
When the Template Toolkit processes a file, it starts out in literal mode and simply outputs stuff exactly as it was inputted (actually, it can be configured to do some processing even in literal mode, but we have that disabled). When it encounters a start tag, generally [%, although [%+, [%-, and [%# are variants, it enters the template language mode. It remains in template language mode until a close tag, generally %] with variants +%] and -%] as variants. One minor exception is the [%# start tag; with this start tag everything until the closing tag is considered a comment and ignored (no template processing, and it does not get sent to the HTML file).
Don't worry about the '+' and '-' variants of the start and close tags, these are not that important and are discussed elsewhere. The [% and %] tags are sufficient for almost all purposes.
When inside the template language blocks, a # symbol means that everything after it, until the end of the line, is a comment. Note that [%# is different; when there is no space between the start tag and the # symbol, the entire template language block is treated as a comment.
Commands in the template block are terminated by semi-colon, and can span multiple lines. The last command before a closing tag does not require the final semi-colon (although can have one); it is mandatory for all other commands. In general, extra whitespace is not a problem.
Standard Template Toolkit commands are generally all capital letters,
although a lot of locally defined macros will be used which do not follow that
format. You can use either single or double quotes to quote literals, and
string literals must be quoted. Some macros take arguments; usually if the
argument is required or common it is just positional, whereas you can include
less common optional arguments by name. For example, in the previous example
of a web page, the standard_pnce_header macro was called with
a positional argument "Title of page" for the docTitle (the
title in the HTML header block). Because the second positional argument,
pageTitle (the title displayed next to the PNCE logo) was
missing, the value from docTitle was used. To have the two differ,
you would call it with
[% standard_pnce_header('Title of Page',
'Title to Display'); %]cssFile, you could use
[% standard_pnce_header('Title of Page',
cssFile='mystyle.css'); %][% standard_pnce_header('Title of Page',
'Title to Display',cssFile='mystyle.css'); %]We have encapsulated the basic design and boilerplate for PCS web pages into a couple of lines of template toolkit language to include into your template. The first of these is
[% standard_pnce_header('HTML Header Title',
'Title Displayed Next to Logo'); %]<html> tag,
all the header info, the metatags, includes the standard CSS file, sets up
the PNCE logo, prints the title next to the logo, and the horizontal rule
underneath the title and logo. If the 'Title Displayed Next to Logo' is
omitted, the 'HTML Header Title' is used for both. There are a bunch of
other options available through named parameters as well.
After this line, you put your content. The content should be HTML, possibly enhanced with template toolkit extensions. You can define your own, or more commonly use ones that were pre-defined.
Finally, you need to display the PNCE footer, close the body and html tags, etc. All this is done with one of the footer macros. These usually do not require any arguments. They are:
[% standard_pnce_footer %]: This is the basic PNCE footer,
and is the parent for the others. No W3C validation stuff is displayed, so
this is good for restricted pages (where the W3C validation links do not really
work), but should not be used for public pages.
[% w3c_valid_pnce_footer %]: This prints the standard PNCE
footer and then includes logos indicating the page is valid HTML/CSS, which
can be clicked on to test for validity. Note: Using this footer
does not automatically mean the page is valid, you must test the page. But
public PCS pages should use this footer and test (and fix problems and retest)
to ensure is W3C valid.
[% w3c_test_pnce_footer %]: Like
w3c_valid_pnce_footer but the logos are replaced by links which
do not imply that the page is valid, but allows to easily check.
The next most important tag to include is the addTopic
command. This is a local macro to set up a semi-automated indexing of
web pages. One problem is that users (or administrators) looking for PCS
web content do not always approach the problem from the same design perspective
as the author. E.g., we may have instructions for printing from the PNCE-Unix
environment under PNCE-Unix Environment, Common Tasks, Printing. While a
perfectly reasonable location, and perhaps more than reasonable in terms of
the structure of the web site as a whole, an impatient user might not be
thinking in those terms. The goal is to have a master index page which would
list the instructions for printing under all the topic entries one might
try (e.g. Printing, PNCE-Unix Environment, or MDQS, commands, or Common Tasks,
Printing, PNCE-Unix Environment).
No computerized system can do a good job of placing a page under the
relevant entries automatically, but generally the author of the page can
easily come up with a fair number of potential entries. The aim is to enable
the author to simply list these potential entries in the template for the
page, and have an automated system of assembling all these hints into the
master index pages. To do this, just use a number of addTopic
commands anywhere in your page template after invoking the standard header.
So our page on printing instructions might start like:
[%
pnce_standard_header('PNCE-Unix Printing',
'Instructions for Printing on PNCE-Unix Systems');
addTopic('PNCE-Unix|common tasks|printing');
addTopic('PNCE-Unix|printing');
addTopic('PNCE-Unix|MDQS');
addTopic('printing|PNCE-Unix');
addTopic('MDQS|commands');
addTopic('common tasks|printing|PNCE-Unix');
%]There are some other tags which you can use in your content. You must wrap them in start and closing tags, although if doing a string of macros in a row they can share the start and closing tags; e.g.
[% h1('Big title') %]
[% h2('Medium title') %]
[% h3('Small title') %][% h1('Big title')
h2('Medium title')
h3('Small title')
%]A reference for these TT macros is provided.
