Red Queen Review Engine User Manual ABOUT THE TEMPLATE-TOOLKIT

Adjust Text:  a a a a

« Table of Contents   |   Obtain Red Queen »

• ABOUT THE TEMPLATE-TOOLKIT
• What Is It?
• Documentation

ABOUT THE TEMPLATE-TOOLKIT

What Is It?

First up, if you are looking for it, here is a link to the Template Toolkit Manual which is embedded in this documentation.

The PRIMARY templating scheme used by Red Queen is an open source collection of Perl modules known as the Template Toolkit written and maintained by Andy Wardley. The Template Toolkit is designed to parse templates. That is, it reads a file designated as a template and looks for tags that it recognizes as elements of a special template markup language. As template markup languages go, the one employeed by the Template Toolkit is fairly comprehensive. This means that it offers both power and flexibility. It is also widely used, well-tested, and comes with excellent documentation. You are advised to check that documentation before you implement any template modifications involving Template Toolkit tags. In Red Queen these Template Toolkit (or TT) tags have the following form:

	[% some.such.variable %]

Here, the markup elements [% and %] are opening and closing tags which delimit a Template Tookit variable. The variable itself will either be substituted when the template is parsed, or used to begin a programming loop or conditional of some kind. In the example above you see dots separating the components of the substitution variable. The components might be functions, arrays, or hashes. In this case some.such.variable might evaluate to the "variable" key of the "such" hash, itself keyed into the "some" hash. More commonly, you will find template variables in Red Queen that look like this:

	[% alias.variable %]

where alias is a special hash supplied by the program, which contains all the variables required to fill out the parsed template. You can think of it as a separate namespace that makes it easier for you to define your own template variables (which would NOT be prefixed by the 'alias.' syntax) without fear that the two sets of variables might clash. That said, there are lots of instances in the templates where local variables are defined--i.e. variables not passed into the template--so if you intend to add new local variables yourself, you might want to prefix these with your own unique string. As an example, you might use mine_ for you own local variables:

	[% mine_eyes = 'do see the light' %]

	[% IF alias.good_eyes %] [% mine_eyes %] [% END %]

If you study the templates you'll notice that lots of local variables are prefixed with my_ so it would be a good idea to avoid that string as a prefix.

You can do a great number of things with the Template Toolkit, such as perform conditional tests (see the example above), or run loops to any depth:

	[% FOREACH hash = alias.array %]
		Hash name = [% hash.name %]
		[% FOREACH key = hash.keys.sort %]
			[% NEXT IF key == 'name' %]
			Hash element [% key %] => [% hash.$key %]
		[% END %]
	[% END %]

In the above example an array whose elements are hashes is looped over, and for each hash in the array, the hash keys are extracted, sorted, and used to display the content of the hash. Other templates can be inserted into the current template by using an INCLUDE statement:

	[% INCLUDE another_template.ttml %]

or specially defined BLOCK elements within the template can be inserted into a given spot:

	Here is the content of the story: [% INCLUDE story %]
	Feedback on this article can be sent to the following address...

	[% BLOCK story %]
		It was reported today that...
	[% END %]

This is just a glimpse of the possibilities that the Template Toolkit offers. Information relating to the editing of specific Red Queen TT templates can be found elsewhere in this manual. Note that ALL Template Toolkit templates in Red Queen have a .ttml suffix.

Documentation

Because the accompanying copy of the Template Toolkit Manual (representing TT version 2.0.10) is so comprehensive, and represents the official guide to its use, not much more will be said about it here. It should be noted, however, that Red Queen utilizes only a fraction of the power that the Template Toolkit has to offer. In particular, Red Queen makes much use of the template parsing abilities of the Template Toolkit, but ignores completely some of the other features it offers, such as Plugins. This means that if you wish to incorporate some of these extra TT features there is nothing to stop you from doing so, provided you are prepared to study the Template Toolkit Manual.

« Table of Contents   |   Obtain Red Queen »