Catkin Templates

Catkin uses a set of templates to transform your blog entries into full pages. Most of these will be HTML pages, but Catkin's templates can generate other textual formats as well.

The templates are divided into three types, each in a different directory: entry templates, which are used to generate the pages for individual blog entries; index templates, which are used to generate indexes of the entries; and cgi pages, which are used for dynamically generated pages such as the reply page.

All template files contain two parts: a header section with various metadata about the template, and the body, which is a Template Toolkit template. The header section and the body are separated by a blank line. Here is an example of a simple template:

Extension: txt
Depends: self

[% entry = blog.entries.$self %]
[% entry.title %]
[% entry.count %] comments have been made to this entry.

Headers

Each header is placed on a line by itself. It consists of a name and some data separated by a colon. The name is case-insensitive.

Catkin understands several different headers. Any headers which Catkin doesn't understand or which have no use in the context in which they appear will be ignored.

Filename

Index templates are written to the filename contained in this header. So an index template with the header "Filename: archive.html" will generate a file called archive.html.

Content-Type

This header contains the MIME type of the data generated by the template. For templates that generate pages that are directly output to the user, Catkin will send the value in the Content-Type header to the browser. If the generated page is written to disk, this header will be ignored. At the moment, only the CGI templates are sent directly to the user. In the future, Catkin will probably be able to dynamically generate all its pages, and then Content-Type header will be used in all the templates.

If this header is not present, it's value will default to "text/html".

Depends

Entry templates are only processed if one of the entries they depend on has been altered. The contents of the dependencies header is a comma-separated list of dependency rules. There are several different forms of dependency rule:

Extension

Pages generated from entry templates are written to a file with a name in the form <id>.<extension>. The Extension header contains the filename's extension.

The Body

The body of a Catkin template is a Template Toolkit template. This document will not describe Template Toolkit's syntax. Instead, see the documentation on the Template Toolkit website.

Standard Data Set

All the templates are given access to a set of data about the blog:

Entry Objects

Entry objects have the following properties:

Comment Objects

Comment objects have the following properties:

CGI Templates

There are two templates in the templates/cgi directory: failure_page.template and reply_page.template. These templates make use of the Content-Type header.

Failure Page

failure_page.template is used to display a message to the user when an action they have requested cannot be carried out. In addition to the standard data set, this template is given two variables, action and message, which contain the name of the action the user requested and the error message respectively.

Reply Page

reply_page.template is used to generate the page that the user sees when they go to post a reply to an entry or comment. In addition to the standard data set, this template is given:

Entry Templates

There can be any number of entry templates. They should be placed in the templates/entry directory and given the extension .template. In addition to the standard data set they are given a variable called self which just contains the number of the entry in the blog.entries list. These templates make use of the Depends and Extension headers.

Index Templates

There can be any number of index templates. They should be placed in the templates/index directory and given the extension .template. They are only given the standard data set. These templates make use of the Filename header.