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:

• %newsbruiser-link: Print a link to the NewsBruiser homepage.
• %newsbruiser-version: Print NewsBruiser's current version number.
• %notebook-name: Print the short name of the notebook. Useful if you need to construct your own NewsBruiser links inside of a template.
• %notebook-titleLink: Print the title of the notebook.
• %notebook-titleLink: Print the title of the notebook, linked to its URL.
• %notebook-contactLink: Print the name of the administrator of this notebook, linked to their email address if one was provided.
• %notebook-description: Print the description of the notebook.
• %links-reader: Prints a list of useful links for readers of the notebook (eg. links to the category tree and the syndication feed). Will not print anything if the notebook has no categories and no entries.
• %links-admin: If the user is logged in, prints out links for administering the notebook. Otherwise, prints a login form.
• %searchBox: If there are entries in the notebook, prints a search box form for the notebook. Otherwise, prints nothing.
• %notebook-calendar: Prints an appropriate calendar for the current entries being displayed. If there is no appropriate calendar, prints a calendar for the current month.
• notebook-archive-monthly: Prints archive links for every month in which this notebook has an entry. Uses the monthly archive link template (cf.) to wrap each such link.
• notebook-yearSpan Prints the first year and the last year for which this notebook has an entry. If there's only one year, prints the one year. Used in a copyright statement, eg. "© 2000-2004".
• system-baseContentURL Prints the URL to the theme-independent content that comes with NewsBruiser, such as the documentation, the default entry export image, and the RSS XSLT transform.

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:

• page-docType: Prints out an HTML document type. Mainly so you don't have to remember what an HTML document type looks like.
• page-standardHeadContents: Prints NewsBruiser-specific HEAD tag information like a reference to the CSS file and robot indexing information.
• page-bodyColors: Prints out the portion of a BODY tag which deals with link, text, and background colors.
• page-title: Prints the title of the current NewsBruiser page.
• notebook-licenseText: Prints out information about the current notebook copyright license, if there is one. This basically means interpolating either the Creative Commons license description template or the non-Creative-Commons license description template. You can call this either in the header or the footer.

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:

• links-contextual: Prints out any contextual links for this page
• notebook-licenseText: This is the same as in the header template. If you don't use it in the header template, you should use it here.

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:

• %calendar-currentTimespan: Prints a calendar for this month.
• %entryCount-currentTimespan: Prints a count of the number of entries posted this month.
• %panel-readerLinks: Interpolates the reader links panel template (qv.) if there are any categories or any entries in this notebook. Does nothing otherwise.
• %panel-searchBox: Interpolates the search box panel template (qv.) if there are any entries in this notebook. Does nothing otherwise.

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:

• summaryList-date: Prints the date of the current entry in the summary list date format. If there's no specific summary list date format, uses the notebook's default format.

  The license templates

  There are two of these; one for Creative Commons-compatible licenses and one for all other licenses (including full copyright). They can make use of all the basic template commands (notebook-yearSpan is especially useful), as well as the following one:

  • notebook-licenseData: If you're using a Creative Commons license, prints out the URL to the license. If you're using a license where you specified a custom URL, prints out a link to that URL. If you're using a license where you specified custom text, prints out that text. Otherwise, prints nothing.

  When you call the Creative Commons license template, in addition to what you specified in the template you'll get some RDF enclosed in an HTML comment. This machine-readable code will help search engines and other tools know about the terms under which your notebook is licensed. It won't be visible or affect the way your notebook looks at all.

  Entry Templates

  These templates are interpolated in the context of a specific list of entries being rendered as HTML, whether the entries be a list of recent entries, the contents of a dated archive, a list of search results, a list of random entries, or anything else.

  The entry list template

  The entry list template is the 'master' template, which indirectly or directly includes every other NewsBruiser template. The entry list template is used to display notebook entries on the screens view, edit, search, and category, the this_month.ssi SSI, etc. etc. Anywhere a notebook entry is rendered as HTML, the entry list template is being processed.

  You have two choices for the entry template. You can invoke %E directive directly and print out all the entries in the current entry list one after another. Alternatively, you can group the entries by year, month, or day by interpolating one of the timespan templates. The latter option allows you to (e.g.) print separators distinguishing different months, or to put each day's entries in their own table.

  The entry list template recognizes the following directives:

  • %D Process the day-span template (q.v.) for every day of entries in the list. If all the entries to be displayed are from the same day, NewsBruiser will act as though you had specified the %E directive instead (you can override this by changing the 'Minimum timespan to interpolate' option)
  • %E Process the entry template (q.v.) for every entry in the list.
  • %M Process the month-span template (q.v.) for every month of entries in the list. If all the entries to be displayed are from the same month, NewsBruiser will act as though you had specified the %D directive instead (you can override this by changing the 'Minimum timespan to interpolate' option)
  • %Y Process the year-span template (q.v.) for every year of entries in the list. If all the entries to be displayed are from the same year, NewsBruiser will act as though you had specified the %M directive instead (you can override this by changing the 'Minimum timespan to interpolate' option').

  The entry list template is useful for specifying opening and closing HTML for your entry list. For instance, if you wanted every entry in an entry list to be part of an ordered HTML list, you could set your entry template to this:

  <ol>%E</ol>

  And set your entry template to (something like) this:

  <li>%d: %e</li>

  The "Poindexter" theme provides an example of HTML in the entry list. The "Sobelow" theme provides an example of the date span templates.

  Timespan templates

  The year span template

  The year span template is interpolated once for every year in a list of entries. It must contain the '%M' directive.

  The year span template recognizes the following directives:

  • %M Process the month-span template (q.v.) for every month of entries in this year.
  • %url-currentYear Print the URL to view all entries for this year.
  • %Y Print the current year as four digits, as in strftime format.
  • %y Print the current year as two digits, as in strftime format.

  The month span template

  The month span template is interpolated once for every year in a list of entries (if interpolated from the entry template), or once for every month in a year of entries (if interpolated from the year span template). It must contain the '%D' directive.

  The month span template recognizes the following directives:

  • All of the year span template directives except for %M
  • %b Print the abbreviated name of the current month, as in strftime format.
  • %B Print the full name of the current month, as in strftime format.
  • %D Process the day-span template (q.v.) for every day of entries in this month.
  • %m Print the month as a decimal number ([01,12]), as in strftime format.
  • %url-currentMonth Print the URL to view all entries for this month.

  The day span template

  The day span template is interpolated once for every day in a list of entries (if interpolated from the entry template), or once for every day in a month of entries (if interpolated from the day span template). It must contain the '%E' directive.

  The month span template recognizes the following directives:

  • All of the year span template directives except for %M
  • All of the month span template directives except for %D
  • %a Print the abbreviated weekday name of the current day, as in strftime format.
  • %A Print the full weekday name of the current day, as in strftime format.
  • %b, %B, %m: As in the month span template.
  • %d Print the day of the month as a decimal number [01,31], as in strftime format.
  • %e The same as %d, but won't pad a number less than 10 with a leading zero. Therefore the range is [1,31].
  • %e The same as %d, but won't pad a number less than 10 with a leading zero. Therefore the range is [1,31].
  • %E Process the entry template (q.v.) for every entry in this year. If in detail mode, the entry detail template is processed instead.
  • %h Print the day of the month as an English number [1st,31st].
  • %o Print the day of the month as an English word, uncapitalized [first,thirty-first].
  • %O Print the day of the month as an English word, capitalized [First,Thirty-first].
  • %url-currentDay Print the URL to view all entries for this day.
  • %w Print the weekday as a decimal number [0(Sunday), 6], as in strftime format.

  Templates for a specific entry

  Generic entry directives

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

  • All of the time-related directives found in the day-, month-, and year-span templates, plus %H (the hour of the day this entry was posted), %M (the minute of the hour this entry was posted), and %S (the second of the minute this entry was posted).
  • %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.
  • %b Print the size of this entry's text, in bytes.
  • %i Print the entry ID of this entry, in the format "yyyy-mm-dd-ordinal".
  • %v Print the URL that shows this entry and only this entry.

  The entry template

  The entry template is used to display one of the notebook entries in a list. It is called whenever the %E directive is found in the entry list template.

  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, or interpolates the summary template if this notebook is set up to summarize long entries.
  • %p Print the permalink to this entry, using the permalink text defined for this entry's notebook.
  • %s Print the summary (first paragraph) of this entry.
  • %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.
  • %categories: 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. In entry detail view, the category list detail template is processed instead.
  • %trackbacks: Process the trackback template (if in detail view) the trackback detail template, or (if there are no trackbacks for an entry) the "No trackbacks" template.

  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

  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

  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>)

  The summary template

  The title template is a sub-template of the entry template. It's displayed for an entry when the following conditions are met: the entry template contains the %e directive to print out the entry text, the entry text is longer than one paragraph, and the notebook has been configured to summarize long entries.

  This template recognizes no special directives.

  The default summary template is as follows:

  %s [<a href="%v">More]

  The category list template

  This template, and its sibling the category list detail template, are sub-templates of the entry template. The category list template is displayed for an entry when the entry belongs to one or more categories, and when the entry template contains the %categories directive. The category list detail template is displayed under the same circumstances in detail view.

  This template recognizes the following special directives:

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

  The category template

  This template is a sub-template of the category list and category list detail templates. It is interpolated once for every category to which an entry belongs, when the %categories directive is found in its parent template.

  This template recognizes the following special directives:

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

  The default category template is as follows:

  %category-commaIfNotFirst %category-linkedName

  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 %category-numberOfCategories categor%category-plural: <ol>%category-each</ol></div>

  And set your category template to this:

  <li>%cn <span class="categoryDescription">%category-description</span></li>

  The incoming trackback list template

  The incoming trackback list and incoming trackback detail list are for printing out a list of an entry's incoming trackbacks. They are interpolated when the entry template or entry detail template contains the %trackbacks directive.

  This template, and the templates it interpolates, recognize the following special directives:

  • %trackback-entry-url: The URL other clients should use to add an incoming trackback to this entry.
  • %trackback-numberOfTrackbacks: Prints the number of incoming trackbacks for this entry.
  • %trackback-plural: Prints nothing if there is one trackback, and "s" otherwise.

  This template recognizes the following special directives:

  • %trackback-each: If there are no incoming trackbacks, interpolates the "empty trackback list" template. Otherwise, interpolates the trackback template or (if in detail view) the trackback detail template for each incoming trackback.

  The incoming trackback template

  This template recognizes the following special directives.

  • %trackback-date: The time at which this trackback came in.
  • %trackback-url: The URL to the weblog entry that referenced your entry.
  • %trackback-title: The title of the weblog entry that referenced your entry.
  • %trackback-blogname: The name of the weblog that sent the trackback ping.
  • %trackback-description: The excerpt from the weblog entry that referenced your entry.

  ---

  Back to the main documentation