Guide to writing your own templates.
Writing PubTal templates should be very easy if you are already familiar with TAL; if this is the case jump down to the available properties. If TAL is new to you, then read on for a quick introduction, it's very easy to pick up.
All TAL commands consist of attributes on HTML elements. The three most common TAL commands for use in PubTal templates are tal:content, tal:replace, tal:attributes. Each of these is described briefly here:
Both tal:content and tal:replace take an optional keyword 'structure' that stops TAL escaping any HTML special characters that might be in the path content. E.g. <div tal:content="structure page/content">Body</div> includes any HTML in the content body directly into the template without escaping it.
The two kinds of path most commonly used in PubTal are ordinary paths (e.g. page/content) which point to data, and string paths. A string path contains a mixture of fixed text, and data included using the syntax ${ordinaryPath}. An example of a string path is <b tal:content="string: Copyright ${page/copyrightYear} By Me"></b> where the content of this 'b' element will be replaced by the string 'Copyright 2003 By Me' (depending on the year you run it!).
Although only the most common TAL commands have been documented here, PubTal supports all TAL and METAL commands. For documentation on all available commands please refer to the Zope Book's description of the language.
The following is a list of objects and their properties which are made available to templates when they are being used for HTMLText content. A different set of properties are made available when using Catalogue content, details of which are given later.
The page object has the following properties:
The "depth" property takes the value of the offset required to get back to the root of the destination directory. For example, if the destination directory is "dest", then the file "dest/test/index.html" would have a depth of "../". By using this property, the template can adjust its links so that they work for any content, regardless of how deep into the directory structure it is. An example of how this can be used is:
<a tal:attributes="href string:${page/depth}index.html">Home</a>
The macros object holds the macros included from templates. Take an example where a template "base.html" exists that declares two macros "email" and "navbar". The following configuration directive could be used to make them available to a template:
<Directory>
macro site-macros base.html
</Directory>
The template could access then these macros using macros/site-macros/email and macros/site-macros/navbar. See the Macro Example for more details.
This is a special object that takes the path passed to it and returns true if the current page being built matches that path, or false otherwise. This is useful when building navigation links in a page and you wish to exclude the link to the current page:
<a tal:omit-tag="ispage/index.html" href="index.html">Index</a>
<a tal:omit-tag="ispage/test/resources.html" href="test/resources.html">Resources</a>
The pubtal object has the following properties:
What follows is a description of how the properties available to Catalogue templates (both index and item) are different from those available to templates handling HTMLText content.
The following properties are not available on the page objects given to Catalogue templates:
The catalogue object has the following properties:
The rows property can be used by the index template to display catalogue items in rows and columns rather than as a continous list. This is best illustrated by an example template fragement:
<table>
<tr tal:repeat="row catalogue/rows">
<td tal:repeat="item row"><b tal:content="item/headers/title"></td>
</tr>
</table>
The number of columns in each row can be changed by setting the catalogue-max-columns parameters in the site configuration file (defaults to 5). This property is especially useful for photo albums.
PubTal Version 1.1