Writing NewsBruiser themes

Leonard Richardson <leonardr@segfault.org>

NewsBruiser themes let you package the look of your site for others to use. You can keep several themes and easily switch back and forth between them easily. If you're good at Web design but not at programming, themes are your ticket to NewsBruiser-contribution fame and fortune.

Anatomy of a Theme

A theme consists of one or more files in a directory under the themes/ subdirectory of a NewsBruiser installation. The name of the directory is the name of the theme.

The theme configuration file

The theme configuration file is in the same format as the notebook configuration file, but it can set only the subset of the configuration options deemed "themed" by NewsBruiser (these are all the "Templates" options and almost all of the "UI Customization" options). It consists of a set of key-value pairs, one per line, with the key and the value separated by an equals sign. Example:

entry-list-template=<ol>%E</ol>

You can get a list of configuration keys by scouring options.conf for options with 'themed=Y' set, or by looking at the Default theme, which sets every themable value.

The theme-generate.cgi CGI (linked to from the 'Util' option on the main menu) will create a theme configuration file from your current notebook setup.

Creating a theme

NewsBruiser currently ships with several themes that take different approaches to presentation. Study them, learn from them.

To create a new theme, first create a CSS file (if you want one associated with your theme), then use configure.cgi to use that CSS file and generally make your notebook look the way you want it. Then, create a new directory under themes, named after your theme. Add the description and AUTHOR files.

To create the configuration file, start with the output of theme-generate.cgi. Whittle away the options that you want to leave up to the user of the theme to configure (display-time-format is probably one of these). Be sure that all your URLs point to a resource inside the theme directory, and that your CSS file, your images, and any other resources point inside the theme directory. Any instance of '%R' in your theme definition file will be replaced with the base content URL, as defined in cfg.py

If you create a cool theme not like any current NewsBruiser theme, I'd really appreciate it if you could send it to me to include in a future version of NewsBruiser.


Back to the main documentation