The NewsBruiser Templating System

Leonard Richardson <leonardr@segfault.org>

NewsBruiser has a simple templating system that allows you to customize the look of your entries on a per-notebook basis without changing the NewsBruiser code. If you can't make your entries look the way you want with CSS, you should be able to do it by changing the templates.

Editing templates

All of NewsBruiser's templates are editable under the "Layout Templates" and "Entry Templates" section of the configure screen (follow the "Configure" link from the notebook index and then the "Layout Templates" or "Entry Templates" link).

If you don't like editing the NewsBruiser templates from the Web, you can change any template value to the string "file:" plus the path to a file on disk, for example: file:templates/entry.template. NewsBruiser will read that file (it looks for it under the directory in which you installed NewsBruiser) and use its contents as the template string. This lets you edit the templates with a text editor on the web server, upload them from your home computer with scp, or whatever else you might want to do.

Template format

NewsBruiser templates consist of HTML interspersed with template directives. All template directives consist of a percent sign and a directive of one or more characters, for instance: %a or %CP or %url-currentMonth. When a template is interpolated for an entry, its directives are replaced with the appropriate values for that entry (see a template's documentation below for a list of the valid directives for that template).

If you need a literal percent sign in your template (for instance, when expressing the width of a table element as a percent), you can use '%%'. NewsBruiser will not interpolate directives it doesn't recognize, so you don't need to use '%%' unless the character after your percent sign is a valid NewsBruiser directive character.

General directive information

In general, lowercase and non-alphabetic directives apply directly to the object being interpolated (for instance, an entry). Uppercase directives in a template trigger the interpolation of another template (if appropriate to the object being interpolated). There are a few exceptions to this rule, mostly required for compatibility with the strtime format.

All templates recognize the following notebook-specific directives:

Layout Templates

These templates let you customize the general layout of NewsBruiser.

The master header template

This template controls the HTML that gets rendered at the beginning of every page you visit. You can use it to create a global look and feel. It recognizes the following special template directives, and you really should use all of them:

The master footer template

This template controls the HTML that gets rendered at the end of every page you visit. You can use it to create a global look and feel. It recognizes the following special template directives, the first of which you really should be sure to use:

The main page template

This template controls the HTML that gets rendered when you visit the main page of your NewsBruiser installation. It can call the entry list template as well as use the following directives:

The monthly archive link template

This template is interpolated whenever the %notebook-archive-monthly directive is encountered. It's basically a wrapper around each archive link so that you can put each link on its own line or table cell. It must include the %link directive (which prints an actual archive link), and it can't include any other directives.

The blogroll panel template

This template is interpolated when the %panel-blogroll directive is encountered and when there are links in the blogroll. It must include the %notebook-blogroll directive.

The blogroll link template

This template is interpolated for each item in the blogroll when the %notebook-blogroll directive is encountered. It's basically a wrapper around each blogroll so that you can put each link on its own line or table cell. It must include the %link directive (which prints the actual link link), and it can't include any other directives.

The reader links panel template

This template is generally interpolated from the main page template. It should consist of the %links-reader directive, wrapped around whatever HTML is neccessary to mantain consistency with the main page template.

The search box panel template

This template is generally interpolated from the main page template. It should consist of the %searchBox directive, wrapped around whatever HTML is neccessary to mantain consistency with the main page template.

The summary list template

You can put this in your header or footer template to display summaries of the most recent items in your summary list. It is baiscally a mini-entry list template. It accepts the entry template directives as well as the following special directive: