Using Catalogues

What are catalogues and how do you use them?

Introduction to Catalogues

Catalogues allow for collections of files (e.g. photos) to be organised easily. PubTal can, for each Catalogue, generate a master index page, and individual pages for each item in the Catalogue.

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 individual entries in the Catalogue. 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.

If item page creation (controlled with catalogue-build-pages) is enabled then the name-value pair filename must be present for each item in the Catalogue. If PubTal is configured to generate one web page for each item in the catalogue (the default), it will use the filename given for each item, changing the extension to that of the template file.

PubTal can also be configured to generate an index 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 template file.

Catalogues and Templates

The templates used by PubTal to generate the web pages, for individual items and for the master index, can be set in the site configuration file. The two configuration options 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. When the master index is generated, the name-values pairs for the Catalogue are used.

Additionally both templates are given access to an object called "catalogue" which contains properties for the whole Catalogue. These properties include a list of page objects, one for each item in the Catalogue, and 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.

Template Properties

catalogue

The catalogue object has the following properties:

entries - A list of page objects, with one page object for each item in the catalogue.
rows - A list of lists containing the page objects for each item in the catalogue.
headers - The headers associated with this catalogue.
previous - The page object for the previous item in the list (not present for the first item in the list and the index web page).
next - The page object for the next item in the list (not present for the last item and the index web page).

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.

Example Templates

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 containing 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.

To specify which files are treated as Catalogues please refer to the Configuration section.

Sections

Software

The full list of my published Software