Leonard Richardson <leonardr@segfault.org>
Version: 1.0
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.
There are three core classes which support the object model and the CGIs.
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.
There are five helper modules, each of which is used by multiple classes.
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).
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).