The NewsBruiser Templating System

Leonard Richardson <leonardr@segfault.org>
Version: 1.5.0

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 "Templates" section of configure.cgi (follow the "Configure" link from the notebook index and then the "Templates" link).

Template format

NewsBruiser templates consist of HTML interspersed with template directives. All template directives consist of a percent sign and a one- or two-character command, for instance: %a or %CP or %c#. 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).

Universal directives

The following directives can be used in the entry template or any of its subtemplates:

• %2: Print the string '2' on even-numbered entries (second entry, fourth, etc.), and print out nothing on odd-numbered entries. This is useful when you want to distinguish entries by printing every alternate entry in a different style (different background colors, for example). You can keep two sets of CSS styles: "entryText", "entryText2", etc. See the entry template section for an example.
• %i Print the entry ID of this entry, in the format "yyyy-mm-dd-ordinal".

The entry template is used to display notebook entries on view.cgi, edit.cgi, category.cgi, this_month.ssi, etc. etc. Anywhere a notebook entry is rendered as HTML, the entry template controls what HTML is generated.

The entry template recognizes the following special directives:

• %d Print the date of this entry, in the date display format defined for this notebook.
• %e Print the text of this entry.
• %p Print the permalink to this entry, using the permalink text defined for this entry's notebook.
• %A: Process the author template for this entry, if the entry has an author and there is more than one author set up for this notebook.
• %T: Process the title template for this entry, if the entry has a title.
• %CL: Process the category list template for this entry, if categories are enabled for this notebook and the entry is filed under one or more categories. The category list is suppressed in certain places, such as category.cgi.

The default entry template is as follows:

<p class="entry">%p <a name="%i" class="entryDate">%d</a>%A%T: <span class="entryText">%e</span></p>

If you want the same, but you want to alternate background colors for your entries, then uncomment the background-color attributes of the .entry2 directive in default.css and try this:

<p class="entry%2>%p <a name="%i" class="entryDate" width="100%">%d</a>%A%T: <span class="entryText">%e</span></p>

If you want a really simple entry template, with no permalink, author, title, or anchor, try this:

<p>%d: %e</p>

The title template is a sub-template of the entry template. It's displayed for an entry only if that entry has a title and the entry template contains the %T directive.

This template recognizes the following special directive:

• %t Print the title of this entry, if it has one.

The default title template is as follows:

<span class="entryTitle">%t</span>

The author template is a sub-template of the entry template. It's displayed for an entry only if that entry has a title and the entry template contains the %A directive.

This template recognizes the following special directive:

• %a Print the author name, if the entry has an author and there is more than one author set up for this notebook.

The default author template is as follows:

(<span class="entryAuthor">%a</span>)

This template recognizes the following special directives:

• %c#: Print the number of categories under which this entry is filed.
• %cs: Properly pluralize the number of categories; Print 'y' if the entry is filed under only one category, and 'ies' otherwise.
• %CP: Process the category template for each of this entry's categories.

This template is a sub-template of the category template. It is interpolated once for every category to which an entry belongs, when the %CP directive is found in the category list template.

This template recognizes the following special directives:

• %,: Print a comma, unless this is the first category to be printed. This allows you to print out a comma-separated list of categories.
• %cn: Print the name of the current category, linked to its category.cgi page.

The default category template is as follows:

%, %cn

If you want to do a fancier category list, here's one suggestion. Set your category list template to this:

<div class="entryCategories">Filed under %c# categor%cs: <ol>%CP</ol></div>

And set your category template to this:

<li>%cn</li>

Back to the main documentation