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.
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.
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
.
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
".
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:
self
: The template will be processed for an entry when that particular entry has been altered.self+n
: The template will be processed when the entry n places ahead of the current entry in the list has been altered. This refers to a newer entry than the current one.self-n
: The template will be processed when the entry n places behind the current entry in the list has been altered. This refers to an older entry than the current one.last
: The template will be processed for all entries when the last (i.e. the newest) entry has been altered.last-n
: The template will be processed for all entries when the entry n places away from the last has been altered.first
: The template will be processed for all entries when the first (i.e. the oldest) entry has been altered.first+n
: The template will be processed for all entries when the entry n places away from the first has been altered.all
: The template will always be processed for all entries.
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 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.
All the templates are given access to a set of data about the blog:
blog.entries
: A list of all the entries in the blog, sorted in ascending order of date.blog.comments
: A list of all the comments in the blog, sorted in ascending order of date.blog.config
: A function giving access to all the configuration variables. Should be used as "blog.config('key_name')
".Entry objects have the following properties:
title
: The title of the entry.date
: The date of the entry in seconds since Jan 1 1970. FIXME: changedtext
: The text of the entry. This will be in HTML format, so unlike most of the other variables, you won't want to put it through Template Toolkit's html filter.count
: The number of comments attached to the entry.id
: The unique ID of the entry.comments
: A list of the immediate child comments attached to the entry.comments_flat_list
: A flat list of all the comments attached to the entry.type
: For entry objects this will always return "entry".Comment objects have the following properties:
title
: The title of the comment.date
: The date of the comment in seconds since Jan 1 1970. FIXME: changedtext
: The text of the comment. This will be in HTML format, so unlike most of the other variables, you won't want to put it through Template Toolkit's html filter.count
: The number of comments attached to this comment.id
: The unique ID of the comment.comments
: A list of the immediate child comments attached to this comment.type
: For comment objects this will always return "comment".name
: The comment author's name.email
: The comment author's email address.url
: The comment author's URL.parent
: The immediate parent of the comment. May be a comment or an entry.parent_entry
: The entry that this comment is attached to.
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.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.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:
reply_to
: This is what the user is replying to. It may be either an entry or a comment (this can be inspected using the type
property).preview
: If the user has pressed the preview button on the previous page, this will be a comment object containing the data they entered.form_reply_to, form_name, form_url, form_email, form_title, form_text, form_remember, form_mode
: These variables are used to pre-fill the form. They are all text apart from form_remember
which is a boolean, and form_mode
which is an object with the properties label
, name
, and checked
. For examples of their usage, see the default reply_page.template
.
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.
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.