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:

1. <b tal:content="path">test</b> - Replaces the word "test" with the contents of the "path", leaving the "b" tags intact.

2. <b tal:replace="path">test</b> - Replaces the word "test" and the enclosing "b" tags with the contents of the "path".

3. <b tal:attributes="attname path">test</b> - Adds the HTML attribute "attname" to the "b" element, setting the value to the contents of the "path".

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>.  PubTal supplies the current year in the "page/copyrightYear" path, so the string will become "Copyright 2004 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 properties available to a TAL template vary with the content type being used.  There are several properties that are common across most content types, and these are documented here.

page

The page object has the following properties:

headers - This object contains the name-value pairs applicable for this page.  (e.g. page/headers/title might contain "My first title").

1. content - The body of the page, with expanded HTML, as taken from the content file.

2. sourcePath - The filename of the content file (relative to the content directory).

3. absoluteSourcePath - The absolute path to the content file.

4. destinationPath - The filename of the destination file (relative to the destination directory).

5. absoluteDestinationPath - The absolute path to the destination file.

6. absoluteDestinationURL - The absolute URL for this page (requires url-prefix to have been set)

7. destinationFilename - The filename of destination file.

8. depth - The offset from the current directory back to root - see below.

9. copyrightYear - DATE Object.  Defaults to a four digit year (e.g. 2004).

10. lastModifiedDate - DATE Object.  Defaults to RFC8221 format.

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 other objects and properties available to the PubTal templates are more complex, and are not required before simple sites can be created.  If the following descriptions are confusing, don't panic, just refer to this section later once you are more familiar with TAL.

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>

readFile

A special object that evaluates the path passed to it and then treats the resulting value as a filename relative to the content directory.  The file is then read and the contents returned.   Example: If each page should have a different quotation before the content then a template could include:

<div tal:replace="readFile/headers/quotationFile"></div>

Each content file could then define a header called "quotationFile" which is the filename that contains a particular quote.

pubtal

The pubtal object has the following properties:

1. linkText - A standard "Made with PubTal" text (use <p tal:replace="structure pubtal/linkText"></p> to include)

2. version - The version of pubtal in use

3. url - The URL for PubTal

Date Objects

All Date objects have a default output format associated with them.  A TAL path that references the object directly will take the value of the DateTime in the local time zone in the default format.

Paths can be used to pass a specific date/time format.  The two paths supported are 'local' and 'utc'.  For example to output just the time component of a last modified date in UTC use page/lastModifiedDate/utc/%H:%M.  To get the same output in the local time zone use: page/lastModifiedDate/local/%H:%M.

The format characters supported by Date objects are those supported by the TimeFormat2 library, reproduced here for convenience. 

Formatting codes are of the form: %CODE[MODIFIER].  The use of [MODIFIER] is optional.

Modifiers are only applicable on a sub-set of codes, as defined here:

Example: At 16:18 the format string "%I[NP]:%M" will produce "4:18".

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:

1. index.html

2. first.html

3. second/index.html

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.