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
