Red Queen Review Engine User Manual

TEMPLATES
Adjust Text:  a a a a
« Table of Contents   |   Obtain Red Queen »

TEMPLATES

One of the most commonly asked questions I receive is "How do I edit the templates?" Well, you read this chapter of the user manual. Then you experiment. There are no shortcuts here. I have placed the bulk of the formatting logic into the templates so that you have the option of reformatting the content of your review pages. Therefore, if you want to change how things look, it is up to you to spend the time to figure out how to do it.

I used to position this chapter near the end of the user manual. But I have moved it up in the hope that people will actually read it. Because if there is one support question I hate to get, it is: "How do I edit the templates?"

Yes, editing templates can involve some head-scratching. This is particularly true in Red Queen where there are a great number of templates. But the procedure for editing templates is well-defined and spelled out here in detail.

Before you jump in, let me say one more thing about templates. Despite the fact I have placed most of the page formatting options into the templates (which are under your control, and not mine, once you have installed the program) if I should come up with a good idea in the future that would require restructuring the templates in order to implement it, I shall have no qualms about going ahead with it (this has already happened a few times in the history of the program).

In other words, I don't worry that existing customers will have to spend an hour or two bringing their existing templates up to grade if they want to use the new features of a major release. That's just a consequence of using a program that offers highly customizable templates. But don't worry--the latest UPGRADE file will always document the exact changes you need to make to your templates to get the latest features. Sometimes this will require tossing some of your existing templates and replacing them with the newly overhauled templates (then adding back in any customizations you might have made to the old templates). And sometimes this will require the modification of only a few lines in a template.

In practice, although there are a lot of public templates, you should find that there are only a few that you feel the need to modify. In that case, if you take note of which templates you have modified, it will be easier to make the required changes if you upgrade to a new release later. Also, as mentioned below, it is a good idea if you learn how to package your modifications into separate files which you can pull into the existing templates. That way, when you replace a template, you only have to replace a few [% INCLUDE filename.ttml %] statements to get back the modifications of your old templates.

Admin Templates

In Red Queen, the templates used to create the administrative control panels are of the exact same form as those used to create the public pages. However, the templates for administrative pages are not meant to be edited and no interface is made available for this. These templates are replaced each time the Red Queen distribution is upgraded, whereas the templates used to create public pages are not.

Public Templates

Every template used to create public pages can be edited. A template editor is provided to help you perform the editing (see the Templates control panel). If you prefer, editing can be done instead using your favorite text editor, after which time you can reupload the template to the place you took it from in

/cgi-bin/rs/redqueen/my/skins/default/templates

Do NOT be tempted to use some kind of WYSIWYG HTML editor like Dreamweaver, or anything else, to edit your RQ templates. This will only ruin the Template Toolkit code contained in your templates. Template Toolkit tags are a kind of mini-language, and if you destroy the syntax of the TT markup, your template will not compile. So, be sure to hand-edit your templates, and avoid editing the TT markup unless you have studied the Template Toolkit user manual and know what you are doing.

In general, you should aim to perform as little editing as possible--just enough to give the templates the look and feel of the rest of your site. Of course, if you need extra functionality then feel free to add it if you understand what's possible. Studying the Template Toolkit user manual will help with this.

Before performing any editing you should study the various options made available through the Configure control panel, especially the Configure > Style / Colors control panel, and try to determine whether you can effect the changes you need simply by adjusting the colors, or layout options. There are a huge number of page formatting options to be found on the Configure > Build / Browse control panel.

As you will quickly discover, there are a large number of templates that make up the public pages, and trying to determine which template controls what is not an easy task. Some tips on how to go about this are discussed in the next section. If all you want to do is give your Red Queen pages the "look and feel" of your site, you may only need to edit the navigation.ttml template. And you should only do that after you have effected color and style changes from the Configure > Style / Colors control panel first.

By keeping your template modifications to a minimum you allow yourself the option of swapping out unedited templates with any newer versions that might be made available at a later date (which might happen if a new feature is added which affects a particular template).

Those templates that you are most likely to want to edit, if you add custom fields to your Item (or Member, or Supplier) table, are discussed in some detail in the sections entitled Adding New Item Fields and Understanding The Table Definition.

The Navigation Template

Probably the most important template is the one named navigation.ttml, which is known as the navigation template. This template provides HTML common to every public page generated by Red Queen. In other words it wraps the output of every page. This is the template in which you place navigational links to the rest of your site, or anything else that you want to appear on every single page.

Schematically, and in its simplest configuration, the navigation template looks like this:

Logo
Main Branch Navigation Links


RED QUEEN OUTPUT


In fact, this schemtic is just the first of several which are presented in the tutorial: HOW TO ORGANIZE REVIEW SITE NAVIGATION which you should read before editing the navigation template.

The navigation template is fairly simple in structure. It contains a navigation bar with links that allow hopping from one branch to another in Red Queen, and it contains a Template Toolkit tag that is replaced by the inique content that will appear on the page:

[% alias.content %]

The template also contains some material that is required if you want to add Google Maps to your pages, but you can ignore that content, which is clearly marked as Google Maps and uses the string 'gmaps' to identify itself. As of version 2.04 there is also some code to allow a side panel of navigation links to be included. This is a configuration option covered in detail in the tutorial HOW TO ORGANIZE REVIEW SITE NAVIGATION which by now you have probably realized is required reading.

Concentrate on making the navigation template look good before you think about editing any other public template. You may just decide it is the only template you really need to edit.

Nested Templates

You won't always find what you were looking for when you scan a given template. Sometimes the actual templating logic is contained in another template which is pulled into the current one when the template is parsed. Other times the template is the one that is being pulled in and variable definitions which appear to be absent may in fact be located in the parent template. Template Toolkit offers two ways to pull in another template:

[% INCLUDE some_template.ttml %]
[% PROCESS some_template.ttml %]

These methods of pulling in another template differ only in the way in which variables are scoped before the nested template (here some_template.ttml) is processed. If you need to learn about the difference, check out the TT documentation. Mostly in Red Queen you will see the first method being used, so to find instances of template inclusion you need only do a search for the keyword INCLUDE. To further help in this regard, you will find a pair of commentary lines at the top of the public templates which mention any templates pulled into the current one, and whether the current template is pulled into any others. For example, the template named item_page_top.ttml contains the following lines:

pulled into: item_page.ttml
pulls in:    image_zoom_js.ttml format_image.ttml

Many templates neither pull in other templates, nor are pulled in themselves, but it pays to be aware of when that isn't the case when editing a template.

When a template is processed from inside another, you can pass it variables like so:

[% INCLUDE some_template.ttml
	width=100
	height=20
	name=frog.gif
 %]

This means that if you are looking in one template for the source of the variable definition and you cannot find it, it may well be because the template is one that is pulled in by another and the variable definitions are to be found within the [% INCLUDE %] directive responsible for processing the template. Otherwise you will usually be able to track a given variable definition back to the special alias hash that is passed to all Red Queen templates, or one of the other special hashes discussed in the next section.

Editing a Template

When you decide you don't like the look of something on your Red Queen pages and you determine to change it, you will first need to figure out which template is responsible for controlling the section of HTML you intend to modify. Your first step should be to study the HTML source code for the generated page (that is, use the "View Source" option that your browser offers when looking at a generated page). You'll need to find the section of HTML in question, then scan upwards for a comment tag containing the name of a template. All public templates start and end with the following tags (the filename, of course, differs from one template to the next):

<!-- begin: navigation.ttml -->
<!-- end: navigation.ttml -->

Templates are often nested, so you may see several begin or end tags in a row. The purpose of these tags is merely to allow the kind of "debugging" we are considering here. Once you think you know the source of the HTML, you go to the Template Editor (available from the Templates control panel) and study the template to see whether you can understand which part of the template is responsible for outputting the piece of HTML you are interested in.

While the "mini language" used by the Template Toolkit is not particularly difficult to learn, figuring out how a given template actually works is usually NOT an easy task. This is because templates can pull in other templates, and the flexibility of the templating language allows for elaborate templating logic (and sometimes it gets used).

If you do make changes to the templates, it is recommended that you make a small modification, test to see whether it has the expected effect, then continue with the next small modification. Templates do follow rules of syntax, and they can be broken simply by leaving out a right square brace somewhere (actually there are a lot of ways to break the syntax, but if you aren't directly editing the templating syntax you shouldn't have to worry too much about that). If you do break the syntax, Template Toolkit will be unable to parse the template and you'll get back an error that might look something like this:

ref $data = Template::Exception
$data_ref_going_in = HASH
blah blah...

The entire template may actually be tacked onto the error message, and unfortunately the Template Toolkit error messages are not nearly as helpful as one might like. So tracking down the cause of an error can end up being a process of elimination (but if you carefully check the syntax of the last section of the template you edited you'll usually be able to spot the problem).

If you find yourself with a template error for which the source of the problem eludes you, make a backup copy of the template, then proceed to "pull out" chunks of the template until it begins to parse again. When you finally figure out which section of the template is causing problems, the error will probably become obvious. This is not the best way to track errors, and there can be little doubt that exception handling is one of the weaker elements of the Template Toolkit. However it makes up for this in a lot of other areas, so you won't find too many complaints about it here. The best advice that one can give here is: be careful with your syntax, always add the [%%] construct first then expand inside it so that the numbers of left and right braces match and the % symbols are always paired too--i.e. your basic editing logic.

A good idea when editing templates, is to learn the Template Toolkit [% BLOCK %] syntax, which allows sections of templating markup to be stashed away--usually somewhere towards the bottom of the template--and then pulled into the appropriate spot at the right time with an [% INCLUDE %] statement. If you adopt this approach you will be able to maintain something close to the native form of the template, with a few scattered [% BLOCK %] statements where your changes are added. The advantage of this approach is that you can more easily compare your modified template to new versions of the template if features are added to it in the future. Thus:

[% INCLUDE mod_1 %][%# here's my comment about modification number 1 %]

then somewhere near the bottom of the page...

[% BLOCK mod_1 %]
	markup for modification 1...
[% END %]

Of course, serious template modifications may not very easily lend themselves to this approach, but if only small modifications are to be put in place the approach is probably sound.

Even better, you might get into the practice of placing you new BLOCKs of TT code into separate files, and pulling them in like so:

[% INCLUDE mod_1.ttml %]
Then in a separate file named mod_1.ttml you simply place the code you would otherwise have placed into a separate BLOCK element.

Special Template Hashes

When the Template Toolkit parses a template, it draws variable values from special hashes that have been passed to it. The main hash that Red Queen passes to its templates is named (somewhat arbitrarily) alias. So you will see plenty of references like the following:

[% FOREACH item = alias.items %]
	do something with the item...
[% END %]

There are also a couple of other special hashes that Red Queen makes available to the Template Tookit. One is the global.cfg hash, which allows access to all the variables of the Red Queen configuration hash. Another is the global.skin hash, which allows access to the Red Queen skin hash. A third is the global.user hash, which stores user-specified parameters, such as a skin preference (not currently in effect). Example variable assignments involving these three hashes might look like this:

[% members_per_page = global.cfg.browse_members_per_page %]
[% background_color = global.skin.style_background_color %]
[% skin_id          = global.user.skin_id %]

Language Templates

Unlike the Template Toolkit templates, the language templates are very simple and are intended to be used only for inserting text into a particular spot. Language templates, which have a .pl suffix, are implemented as simple hashes and should be edited using the Language Template Editor.

Comments are included in the language templates (and presented next to the edit box) so that you may figure out more easily which piece of language corresponds to the HTML actually produced by a parsed template.

You may add language variables to any language template and these new variables will become available whenever that language template has been incorprated into a given Template Toolkit template. You will need to add the relevant language tags to your Template Toolkit templates (those ending in .ttml) so that the new language variables will be expressed. For example, if you add the batmobile phrase "I think the Batmobile is a cool car." to the global.pl language template (which is available by default to every TT template) then this code in any TT template will display the new phrase: 


	[% alias.language.global.batmobile %]

Often though, you will see the following combination of tags in a given template, allowing more compact tags: 


	[% lang = alias.language %]
	...
	[% IF alias.favorites == 'car' %]
	   [% lang.global.batmobile %]
	[% ELSIF alias.favorites == 'superhero' %]
	   [% lang.superhero.catwoman %]
	[% END %]

in which the catwoman phrase from the superhero.pl language template will be displayed--provided that the superhero.pl language template is actually used by the given TT template.

When deciding about which language template should be used to hold a new language variable, first determine which language templates are available for the page where the language variable will be expressed. If you scan for the string lang. in a given TT template you will see which language templates are being used there. In general, try to select the language template most specific to the page in question. For example, if the language variable will be expressed in superhero.ttml and the primary language template for that page is superhero.pl, then that's probably the best place to put the new variable. If you need the same variable to appear in several templates, then the global.pl language template may be a better candidate. Of course, you don't want to overfill global.pl, as it is made available every time a page is generated.

Dumping The Data Structure

There may be times when adding customizations to your templates where you would like to know exactly what data is being passed from Red Queen into the template. All data is passed in the form of a hash named alias, as should become evident perusing the templates.

You can add the following temporary code to a template to dump the entire data structure to screen:

[% USE Dumper %]
<pre>[% Dumper.dump_html(alias) %]</pre>

Be sure to remove both lines when you are done. If you want to dump just a smaller component of the data structure, such as the thing_info hash (if it is available) you would simply use alias.thing_info in your call to the dump_html() method, rather than just alias

More information about the Dumper plugin can be found in the documentation pages for the Template Toolkit.

« Table of Contents   |   Obtain Red Queen »

Copyright © 2004 Random Mouse Software. All Rights Reserved.