Using Catalogues

Introduction to Catalogues

PubTal 1.1 introduced the concept of a new kind of content: Catalogues. Catalogues can be used when building web pages that present a collection of files, for example photo albums.

A Catalogue content file is a text file consisting of name-value pairs similar to those used in HTMLText for headers. The first group of name-value pairs associates data with the Catalogue, and all subsequent name-value pair groups are used by individual entries. To illustrate this take the example of a Catalogue of photos:

title: My first photo album
subject: This photo album is about examples.

filename: one.jpg
title: My first photo
description: It's a photo of me.

filename: two.jpg
title: My second photo
description: A second photo.

The only name-value pair that must be present is filename which is used by PubTal to determine the name of the resulting HTML files. If PubTal is configured to generate one HTML file for each item in the catalogue (the default) it will use the filename given for each item, changing the extension to that of the item template file.

PubTal can also be configured to generate a master HTML page for the Catalogue (again enabled by default). This master page will use the name of the catalogue file, changing the extension to that of the index template file.

Catalogues and Templates

The templates used by PubTal when generating HTML files for individual items and for the master index can be set in the site configuration file in the same way as the template used by HTMLText content. The two parameters used to control the templates are catalogue-item-template and catalogue-index-template respectively.

Both templates are given access to a page object similar to the one used for HTMLText. When the item template is being expanded the headers property contains the name-value pairs for this particular item, and for the master index the name-values pairs for the Catalogue.

Additionally both templates are given access to an object called "catalogue" which contains properties of the Catalogue, including a list of all items and access to the headers associated with the catalogue. Two other useful properties present when expanding the individual items template are 'previous' and 'next' which contain a copy of the 'page' object given to the previous and next item in the list.

A full description of the objects and properties available to Catalogue templates is given in the Templates page, with the list of available configuration options described in Configuration.

Here are an index and item example template which could be used by our example photo album:


<html>
  <body>
    <h1 tal:content="page/headers/title">Album Title</h1>
    <p tal:content="page/headers/subject">Album subject</p>

    <ul>
      <li tal:repeat="photo catalogue/items">
         <a tal:content="photo/headers/title" tal:attributes="photo/destinationFilename">Photo link</a>
      </li>
    </ul>
  </body>
</html>

This template will produce a list of links to individual item pages (in this example containing the photo). The headers of the individual items can be accessed in this loop, enabling the link to be the title of the photo.

An example item template shows how navigation between item pages can be easily achived:


<html>
  <body>
    <h1>Photo from Album: <b tal:replace="catalogue/headers/title">title</b></h1>
    <h2 tal:content="page/headers/title">Title for this photo</h2>
    <p tal:content="page/headers/description">Description for this photo</p>

    <img tal:attributes="string: images/${page/headers/filename">

    <a tal:condition="previous" tal:attributes="href catalogue/previous/destinationFilename">Previous Photo (<b tal:replace="catalogue/previous/headers/title">)</a>
    <br>
    <a tal:condition="next" tal:attributes="href catalogue/next/destinationFilename">Next Photo (<b tal:replace="catalogue/next/headers/title">)</a>
  </body>
</html>

The "previous" and "next" properties contain a full page object, and so the destinationFilename as well as header information can be accessed.

Catalogues of Content

Catalogues can also be used to organise PubTal content. This is useful for generating tables of contents and previous/next navigation links on individual pages. When a Catalogue has the option catalogue-item-content-type set to a value other than 'None', PubTal will read the file specified for each entry by 'filename' and treat it as a piece of content. The means that the context used to expand the individual items template will have:

Any headers in the content merged into the page/headers object
Both page/content and page/rawContent will contain the content from the entry file.

An example of how this can be used is given in the 'examples/toc-example' directory included with the download.