Login | Register
My pages Projects Community openCollabNet

Newsbruiser Technical Overview

Leonard Richardson <leonardr@segfault.org>

Object Model

NewsBruiser is built around three basic concepts: the Notebook, the Entry, and the EntryID.

  • A Notebook object represents a section in .nbrc and all the entries that have ever been logged to it. From a Notebook you can access all of the notebook's configuration information as stored in .nbrc. You can also use various ways of getting Entry objects corresponding to some or all of the notebook's entries.

  • An Entry (extends HtmlGenerator) represents a single entry for a notebook as found on disk, with author and timestamp information as well as the text of the entry. The Entry class contains the logic for reading entries from disk and writing them to disk. Basically all you can do with an Entry object once you have it is render it as HTML in various ways, search its text for a string, or write it to disk.

  • An EntryID is a five-part key (notebook, year, month, day, ordinal) which represents one or more of the entries in a notebook and which can be used to get a list of corresponding Entry objects by calling its getEntries() method. An EntryID also knows a plethora of ways of representing itself to the end-user or to other parts of the system, and ways of returning other entryIDs which have a special relationship with itself (such as being exactly one year earlier).

    At least the first part of the EntryID key must be specified; there is no way for one EntryID to represent all the entries in every notebook on the NewsBruiser installation.

Core Classes

There are three core classes which support the object model and the CGIs.

  • HtmlGenerator contains (specialized and general) HTML generation methods.
  • NBCGI extends HtmlGenerator. It implements an execution path in which the configuration is read, CGI input is obtained from PATH_INFO and form fields, any entry ID is turned into the corresponding list of entries, and then a CGI-specific run method is called to operate on the data.
  • NBConfig contains logic for parsing the .nbrc configuration file into data structures (a dictionary and a list) chock-full of Notebook objects.

CGIs and SSIs

Each of the five CGIs (covered in the intro doc) implements an __init__ method which specifies the page title and any special data to be collected from CGI variables, and a run method which makes changes and/or renders an HTML page. Each is implemented as a class which is instantiated and run when the CGI file is run as a script.

The SSIs are simpler, having only a main function which gets some specified Entry objects and prints them out in some way.

Helper Modules

There are five helper modules, each of which is used by multiple classes.

  • cfg contains basic configuration information like where to find the .nbrc file. It also contains partial URLs to all the CGIs.
  • const contains a lot of constants, for referencing to configuration file fields, CGI variables, EntryID granularities, entry file fields, and common errors.
  • ControlPanel is a class used by the view, edit, and search CGIs for printing control panels at the top and bottom of their pages. It has logic for creating navigation bars and date jump controls.
  • DateArithmetic contains functions for manipulating dates (represented as (year, month, day) or (year, month) tuples).
  • util contains utility functions for manipulating strings in specialized ways and for comparing NewsBruiser entry filenames so that the chronologically later entry is greater than the chronologically earlier one.
  • Viewer is a class which implements a simple container for some Entry objects, with logic to render each one chronologically or reverse chronologically. Used by most CGIs and SSIs.

.firstEntry

Every non-empty notebook will soon sprout a .firstEntry file in its top-level directory. This file contains the slash-separated identifier of the first entry in that notebook. .firstEntry is used as a cache, since on a site with several years worth of entries, the date of the first entry takes a while to calculate. The date of the first entry is needed by ControlPanel, so that "previous" links are not shown if following them would lead you before the first entry in the notebook.

If the first entry changes (because you import old entries, for instance), you'll need to delete the .firstEntry file or your older entries won't be linked to from CGIs (but you'll still see them if you hit their URLs).

Extending NewsBruiser

Since most methods have access to a Notebook object, it's likely that anything you add to the .nbrc configuration will be accessible from the method where you need it, so changing method signatures should not be neccessary for small changes, or possibly even large changes like the addition of user accounts.

The API should be complete enough that writing additional CGIs and SSIs will be fairly easy (see today_in_history.ssi for an example of a rather complex SSI).


Back to the main documentation