Writing 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

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.

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:

<Content>
macro site-macros base.html
</Content>

The template could access then these macros using macros/site-macros/email and macros/site-macros/navbar. See the Macro Example below 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:

Catalogue Content 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 other (e.g. HTMLText) content.

page

The following properties are not available on the page objects given to Catalogue templates, unless the catalogue-item-content-type has been set:

catalogue

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 continuous list. This is best illustrated by an example template fragment:


<table>
  <tr tal:repeat="row catalogue/rows">
    <td tal:repeat="item row"><b tal:content="item/headers/title"></b></td>
  </tr>
</table>

The number of columns in each row can be changed by setting the catalogue-max-columns parameter in the site configuration file (defaults to 5). This property is especially useful for photo albums.

Macro Example

Macros are implemented using METAL, a language complementary to TAL, which is used to define and include macros. Macros allow parts of templates to be shared across multiple templates, enabling easier maintenance when dealing with several templates for the same site.

This example is included in the PubTal download.

The website

This example uses a simple website with three pages:

The config file

The example uses the following configuration file:

# Use base.html as the default template
<Content>
template base.html
</Content>

# For the second directory, use second.html as the default template
<Content second>
template second.html
# Make macros in base.html available under site-macros.
macro site-macros base.html
</Content>

A Macro Template

A template which contains one or more macros can be used just like an ordinary template. The declaration of the macro doesn't interfere with its function as a template in any way. The base.html template in this example is:

<html>
<body>
  <div metal:define-macro="navbar">
  	<a tal:attributes="href string:${page/depth}index.html">Home</a>
  	<a tal:attributes="href string:${page/depth}first.html">First Page</a>
  	<a tal:attributes="href string:${page/depth}second/index.html">Second Page</a>
  </div>
  <h1 tal:content="page/headers/title">Title</h1>
  <div tal:content="structure page/content">Body</div>
  <p metal:define-macro="email">A <b>fancy</b> email address: me@mydomain.com</p> 
  <p>Last modified: <b tal:replace="page/lastModifiedDate">Date</b></p>
</body>

A second template

To use the macros in the second template we use the metal:use-macro command. An example of a second.html template is:

<html>
<body>
  <h1 tal:content="page/headers/title">Title</h1>
  <div tal:content="structure page/content">Body</div>
  <p metal:use-macro="macros/site-macros/email">Email goes here.</p>
  <p metal:use-macro="macros/site-macros/navbar">Nav bar here.</p>
</body>

Notes

The second.html template can include the macros declared in the base.html template anywhere, even multiple times, using the metal:use-macro command. Any TAL that forms part of the included macro (in this case the tal:attributes commands in the "navbar" macro) will be expanded as though it had been placed directly in the second.html template.

PubTal Version 2.0