Building PubTal Templates

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.

Required TAL

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.

TAL Paths

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!).

More TAL

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.

Available Properties

Here is the list of objects and their properties that are made available to templates when they are being expanded.

page

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>

macros

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.

ispage

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>


pubtal

The pubtal object has the following properties:

PubTal Version 1.0