Thu, 07 Dec 2006

Flavours

PyBlosxom takes the data provided in the entries and by the plugins and transforms it into output using renderers. Output can be in html, xhtml, xml, or anything else--anything that you could get back from a CGI script or web application.

The default renderer can be set in your config file like this: 

py["renderer"] = "blosxom"

PyBlosxom comes with two renderers: blosxom and debug.

The debug renderer displays all the data in the various parts of the PyBlosxom Request object. This is really helpful to see what variables are at your disposal and also to debug problems you might be having with plugins you've installed.

The blosxom renderer renders entries just like Blosxom does.

If you want your blog rendered using a different template system--say Cheetah or htmltmpl--implement a renderer that renders the output. This can be done as a PyBlosxom plugin. See the chapter on writing plugins for more information.

Flavours and Templates

The blosxom renderer uses the same template style that Blosxom uses. As such, you can use most Blosxom flavour templates and only have to make some minor modifications.

A flavour can be thought of as a theme or an output format. For example, you could have an "html" flavour that renders the blog data in html format. You could have an "xhtml" flavour that renders the blog in a strict xhtml format. You could have a "happy-sunshine" flavour that renders the blog in html format using a happy sunshiney look and feel. You can have an "rss" flavour that renders the output in RSS 2.0 format with enclosures. So on and so forth.

A flavour consists of a series of templates each of which is a part of the page that finally gets rendered. The minimum set of templates are these:

  • content_type - holds the content type of the flavour

  • head - holds everything before all the entries

  • story - holds a single entry

  • foot - holds everything after all the entries

  • date_head - shows at the start of a date

  • date_foot - shows at the end of a date

You can have other templates as well. Many plugins require additional templates in order to work.

The template files for a given flavour all have the same file extension which is the flavour's name. For example, if you were using an "html" flavour, the flavour itself would be composed of the following files:

  • content_type.html

  • head.html

  • story.html

  • foot.html

  • date_head.html

  • date_foot.html

If you want to create a "joy" flavour, you would have the following files:

  • content_type.joy

  • head.joy

  • story.joy

  • foot.joy

  • date_head.joy

  • date_foot.joy

You can have as many flavours as you want in your blog.

PyBlosxom comes with a series of flavours: html, rss ("RSS 0.9.1), rss20 (RSS 2.0), and atom (Atom 1.0). These flavours come as part of PyBlosxom and they will work out of the box with no modifications and no configuration changes. Additionally, you can override all or portions of these flavours. We'll talk about this a little later.

Additionally, there is a flavour registry on the PyBlosxom web-site at http://pyblosxom.sourceforge.net/ . This is where you can submit flavours that you have created and see flavours other people have created and submitted.

Where To Put Your Flavour Files

If you want to override the existing flavours, add new flavours, or develop your own flavours, you should set the flavourdir property of your config.py file. I have this directory parallel to my datadir. In my flavourdir, I have flavour directories--one for each flavour in my blog:

/home
 |-- willg/
    |-- myblog/
       |-- entries/        <-- my datadir
       |  |-- content/        <-- category
       |  |-- dev/            <-- category
       |  |-- links/          <-- category
       |
       |-- flavours/       <-- my flavourdir
          |-- html.flav/      <-- defines the html flavour
          |-- xml.flav/       <-- defines the xml flavour
          |-- links/          <-- parallels the links category
             |-- html.flav/   <-- defines the html flavour for the links category

In my flavourdir, I have two flavour directories html.flav and xml.flav. The xml.flav is a copy of the atom.flav directory that comes with PyBlosxom. I copied it so that I could use "xml" for the flavour name. This isn't necessarily a wonderful idea, but it helped me upgrade my blog without disturbing planets and writing lots of .htaccess redirects and such.

You'll notice there's an html.flav directory in the links directory. When someone is looking at items in the links directory, then PyBlosxom will use this html flavour.

The order of overiding works like this:

  1. PyBlosxom looks for flavour files that came with PyBlosxom

  2. PyBlosxom starts at the root of the flavourdir and looks for flavour files there. If there are some, then these files override the files PyBlosxom has found so far.

  3. PyBlosxom iterates through category directories in the flavourdir if there are any that are parallel to the datadir and looks for flavour directories there. If there are some, then those files override the files it has so far.

This allows you to easily override specific templates in your blog (like the header or footer) depending on what category the user is looking at.

[23:39] | [] | #-permalink-#