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-#

Template Variables

This is the list of variables that are available to your templates. Additionally, plugins that you are using will add additional variables. To get a complete list of what variables are available in your blog, use the debug renderer by changing the renderer property in your config.py file to debug like this:

py["renderer"] = "debug"

That will tell you all kinds of stuff about the data structures involved in the request. Don't forget to change it back when you're done!

URL Encoding and Escaping of Template Variables

PyBlosxom 1.3 allows you to escape and URL encode any variables by adding "_escaped" or "_urlencoded" to the end of the variable name.

For example, title_escaped is an escaped form of the title with ' (single-quote) replaced with ' and " (double-quote) replaced with ".

title_urlencoded is a URL encoded form of the title which uses the Python urllib.

Variables From config.py

These template variables are available to all templates. They come directly from your config.py file.

Template variables from config.py

variable name description example
blog_description the description of the blog blosxom with a touch of python
blog_title the title of the blog RoughingIT - pyblosxom : /weblogs/tools/pyblosxom
blog_language the language of the blog en
blog_encoding the encoding of the blog iso8859-1
blog_author the author of the blog (hopefully you) Joe Dirt
blog_email the email address of the author of the blog (feel free to obfuscate it) joe at joe dot com

Additionally, any other properties you set in config.py are available in your templates. If you wanted to create a blog_images variable holding the base url of the directory with all your images:

Example 4-2. creating your own config.py variables

py["blog_images"] = "http://www.joe.com/~joe/images/"

to your config.py file and it would be available in all your templates.

Calculated Template Variables

These template variables are available to all templates as well. They are calculated based on the request.

Table - Calculated template variables

variable name description example
content_type the content type of this page text/html
root_datadir the root datadir of this page? /home/subtle/blosxom/weblogs/tools/pyblosxom
url the PATH_INFO to this page pyblosxom/weblogs/tools/pyblosxom
flavour the flavour for this page html
latest_date the date of the most recent entry that is going to show Tue, 15 Nov 2005
latest_w3cdate the date of the most recent entry that is going to show in w3cdate format 2005-11-13T17:50:02Z
latest_rfc822date the date of the most recent entry that is going to show in RFC 822 format Sun, 13 Nov 2005 17:50 GMT
pi_yr the four-digit year the user requested 2002
pi_mo the month name the user requested Sep
pi_da the day number the user requested 15
pi_bl the entry the user requested to see weblogs/tools/pyblosxom
pyblosxom_version the version number and release date of the pyblosxom version you're using 1.2 3/25/2005

Template Variables Only Available in the story Template

These template variables are only available in your story template.

Table - Variables in the story template

variable name description example
title title of the entry First Post!
filename template file name and path of the entry /home/subtle/blosxom/weblogs/tools/pyblosxom/index.txt
file_path just the filename and extensions of the entry index.txt
fn just the filename (no extension) index
absolute_path the category/path of the entry weblogs/tools/pyblosxom
body the text of the entry first post!
tb_id the trackback id of the entry _index
path the category/path of the entry weblogs/tools/pyblosxom
yr the four digit year of the mtime of this entry 2004
mo the month abbreviation of the mtime of this entry Jan
mo_num the month number of the mtime of this entry 01
ti the hour and minute of the mtime of this entry 16:40
date the date string of the mtime of this entry Sun, 23 May 2004
w3cdate the date in w3cdate format 2005-11-13T17:50:02Z
rfc822date the date in RFC 822 format Sun, 13 Nov 2005 17:50 GMT
fulltime the date in YYYYMMDDHHMMSS format 20040523164000
timetuple the time tuple (year, month, month-day, hour, minute, second, week-day, year-day, isdst) (2004, 5, 23, 16, 40, 0, 6, 144, 1)
mtime seconds since the epoch 1085348400.0
dw the day of the week Sunday
da the day of the month 23

Template Variables From Plugins

Additionally, many plugins will create additional variables. Refer to the plugin's documentation for what variables it creates, where the variables are available, and what the variables do.

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

Invoking a Flavour

The flavour for a given page is specified in the extension of the file being requested. For example:

Table - Examples of request URIs

url what happens
http://some.blog.org/ brings up the index in the default flavour which is "html"
http://some.blog.org/index.html brings up the index in the "html" flavour
http://some.blog.org/index.rss brings up the index in the "rss" flavour (which by default is RSS 0.9.1)
http://some.blog.org/2004/05/index.joy brings up the index for May of 2004 in the "joy" flavour

Additionally, you can specify the flavour by adding a flav variable in the query-string. Examples:

Table - Specifying flavour using the querystring

uri what happens
http://some.blog.org/ brings up the index in the default flavour which is "html"
http://some.blog.org/?flav=rss brings up the index in the "rss" flavour
http://some.blog.org/2004/05/index?flav=joy brings up the index for May of 2004 in the "joy" flavour

You can change the default flavour from html to some other flavour in your config.py file with the default_flavour property:

Example - default_flavour variable value

py["default_flavour"] = "joy"

Doing this will set the default flavour to use when the URI the user has used doesn't specify which flavour to use. For example, if you do the above, then the following URIs will use the default flavour:

Table - Default flavour used

uri what happens
http://www.joe.com/cgi-bin/pyblosxom.cgi/2005/03 uses the default flavour which is set to "joy"
http://www.joe.com/cgi-bin/pyblosxom.cgi/2005/03/?flav=html uses the html flavour as specified by flav=

Example Flavours

  • Show gray flavour
  • Show green flavour

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

An Example Flavour (from this presentation)

content_type.html

text/html

head.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
        <meta http-equiv="content-type" content="text/html; charset=utf-8" />
        <meta name="generator" content="pyblosxom" />
        <title>$blog_title</title>

<link rel="stylesheet" 
      href="http://127.0.0.1:9000/css/table-pyblosxom-styles.css" 
      type="text/css" />
<link rel="alternate" type="application/rss+xml" 
      title="MichiPUG PyBlosxom Presentation Blog" href="$base_url/?flav=rss" />
</head>

<body>

<table id="main">
<tr>
<td>

<table id="banner">
<tr>
<td>
<h1><a class="title" href="$url">$blog_title</a></h1>
<h2>-- $blog_description -- </h2>
</td>
</tr>
</table>

<table id="middle-content">
<tr>
<td id="left" class="sidebar" >
<h2>Starting Points</h2>
<a href="$base_url">this blog</a>
<br />
<br />

<h2>Blog Categories</h2>
$categorylinks
<br />
<br />

<h2>Other Feeds</h2>
<ul>
   <li>
    <a href="$base_url/?flav=rss">RSS</a> 
   </li>
</ul>
<p> </p>
<ul>
   <li> 
     <img src="http://www.w3.org/Icons/valid-xhtml10" 
          alt="Valid XHTML 1.0!" height="31" width="88" />
   </li>
   <li>
    <a href="http://pyblosxom.sourceforge.net/">
     <img src="http://127.0.0.1:9000/graphics/pb_pyblosxom.gif" 
          border="0" alt="pyblosxom" />
    </a>
   </li>
<!--   
   <li> 
    <a href="http://validator.w3.org/check/referer">
     <img src="http://www.w3.org/Icons/valid-xhtml10" 
     alt="Valid XHTML 1.0!" height="31" width="88" />
    </a>
   </li>
   <li>
    <a href="http://jigsaw.w3.org/css-validator/">
    <img style="border:0;width:88px;height:31px"
     src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!" />
    </a>
   </li>
-->
</ul>
</td> <!-- end of the left sidebar column -->

<td id="center">
<div class="content">

story.html

<div class="story">
<a name="$fn"></a>
<h3>$title</h3>
$body
<p class="posted">
[<a href="$base_url/$yr/$mo/$da#$fn" title="Date link">$ti</a>] | 
[<a href="$base_url/$path" title="Category">$path</a>] |
 <a href="$base_url/$file_path.html" title="Permalink">#-permalink-#</a>  
</p>
</div>

foot.html

</div>

</td> <!-- end of the center column -->

<td id="right">
<div class="sidebar">

<h2>Archives</h2>
$archivelinks
<br />

<h2>Calendar</h2>
$calendar
</div>
</td> <!-- end of the right sidebar column -->

</tr> <!-- end of the 3 column content row column -->

</table>

<table id="footer">
<tr>
<td>
<div class="footer">
<h2>$blog_title <$url></h2>
</div>
</td>
</tr>
</table>

</td>
</tr>
</table> 

</body>
</html>

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

Writing Entries [Metadata-mood=good]

The Format of an Entry

PyBlosxom entries consist of three parts: the title, the metadata, and then the body of the entry. The first line is title of the entry. Then comes the metadata of the entry (if any). After the metadata comes the body of the entry.

The title consists of a single line of plain text. You can have whatever characters you like in the title of your entry. The title doesn't have to be the same as the entry file name.

The metadata section is between the title line and the body of the entry. It consists of a series of lines that start with the hash mark (#), then a metadata variable name, then the metadata variable value.

The body of the entry is written in HTML and comprises the rest of the entry file.

Here's an example first post entry:

Example - first post

This is my first post!

<p>
  This is the body of the first post to my blog.
</p>

Here's a more complex example:

Example - more complex first post

The rain in Spain....
<p>
  The rain
</p>
<p align="center">

  in Spain
</p>
<p align="right">
  is <font color="ff0000">mainly</font> on the plain.
</p>

Here's an example of a post with metadata:

Example - first post with metadata

The rain in Spain....
#mood bored
#music The Doors - Greatest Hits Vol 1

<p>
  The rain
</p>
<p align="center">
  in Spain
</p>
<p align="right">
  is <font color="ff0000">mainly</font> on the plain.

</p>

The metadata variables here would be available in your story template. So for the above example, the template variable $mood would be filled in with bored and $music would be filled in with The Doors - Greatest Hits Vol 1.

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

Categories (and Sub-Categories)

Writing entries in PyBlosxom is fairly straightforward. Each entry is a single text file located somewhere in the directory tree of your datadir. The directory that the entry is in is the category the entry is "filed under". For example, if my datadir was /home/joe/myblog/entries and I stored an entry named firstpost.txt in /home/joe/myblog/entries/status then the category for my entry would be /status.

Be careful when you create your categories--be sure to use characters that are appropriate in directory names in the file system.

Don't worry about making sure you have all the categories you need up front--you can add them as you need them.

Sub-categories are simply directories under another directory.

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

Rendering & Entry Parsers

PyBlosxom supports only one format for entry files by default. This format is the same format that blosxom uses. The extension for this format is .txt. The first line of the file is in plain text and forms the title of the entry. The second line through the end of the file is in HTML and is the body of the entry.

A sample blog entry could look like this:

First post
<p>
  Here's the body of my first post.
</p>

Some people really detest writing in HTML which is valid. Other people use their entries in other places, so they need a markup format that's less web-oriented. Some folks write a lot of material in a non-HTML markup format and would like to use that same format for blog entries. These are all very valid reasons to want to use other markup formats.

PyBlosxom allows you to install entry parser plugins which are PyBlosxom plugins that implement an entry parser. These entry parser plugins allow you to use other markup formats. Check the Plugin Registry at http://pyblosxom.sourceforge.net/ for which entry parsers are available.

In general, we only have entry parsers written by people who really wanted that markup format. If you don't see your favorite markup format represented, try looking at the code for other entry parsers and implement it yourself. If you need help, talk to us on the pyblosxom-users or pyblosxom-devel mailing lists.

Details on the various entry parsers should be at the top of the entry parser plugin itself in the Python doc-string.

Other entry parsers:

  • PyMarkdown : Allows you to format your blog postings in Markdown format (http://daringfireball.net/projects/mark...
  • Native : This plugin allows you to use a different format for your weblog entries. This format is basically ...
  • htmlentryparser : This file will use a simple HTML file as the entry format. The <h1/> is used as the title of ...
  • genericwiki : Generic wiki markup PreFormatter for pyblosxom.
  • linebreaks : Preformatter for people who are lazy to type <p>s, <br />s, and </p>. Let's face...
  • moinmoin : Preformatter and entryparser for the MoinMoin wiki software.
    • This preformatter/entryparser uses the...
  • py : An entryparser that reads python source code and formats it accordingly.
  • rst : A reStructuredText entry formatter for pyblosxom. reStructuredText is part of the docutils project ...
  • txtl : PyTextile is a Python port of Textile, Dean Allen's Humane Web Text Generator. It supports all the ...

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

Posting Date

The posting date of the entry file is the modification time (also known as mtime) on the file itself as stored by your file system. Every time you go to edit an entry, it changes the modification time. You can see this in the following example of output:

willg ~/blogdata/blosxom/site: vi testpost.txt                            [1]
willg ~/blogdata/blosxom/site: ls -l
total 16
-rw-r--r--  1 willg willg 764 Jul 20  2003 minoradjustments.txt
-rw-r--r--  1 willg willg 524 Jul 24  2003 moreminoradjustments.txt
-rw-r--r--  1 willg willg 284 Aug 15  2004 nomorecalendar.txt
-rw-r--r--  1 willg willg  59 Mar 21 16:30 testpost.txt                   [2]
willg ~/blogdata/blosxom/site: vi testpost.txt                            [3]
willg ~/blogdata/blosxom/site: ls -l
total 16
-rw-r--r--  1 willg willg 764 Jul 20  2003 minoradjustments.txt
-rw-r--r--  1 willg willg 524 Jul 24  2003 moreminoradjustments.txt
-rw-r--r--  1 willg willg 284 Aug 15  2004 nomorecalendar.txt
-rw-r--r--  1 willg willg  59 Mar 21 16:34 testpost.txt                   [4]

[1] I create the blog entry testpost.txt using vi (a text editor). The mtime of the file will be the time I last save the file and exit out of vi.

[2] See the mtime on the file is Mar 21 16:30. That's when I last saved the blog entry and exited out of vi.

[3] I discover that I made a spelling mistake in my entry... So I edit it again in vi and fix the mistake. The mtime of the entry has now changed...

[4] Now the mtime of the file is Mar 21 16:34. This is the time that will show up in my blog as the posting date.

be careful with the mtimes
 

There are some issues with this method for storing the posting date. First, if you ever change the blog entry, the mtime will change as well. That makes updating blog entries very difficult down the line.

There's a utility that comes with the contributed plugins pack called editfile.py. This will note the mtime of the file, open up your favorite editor to edit the file, and when you're done, it'll reset the mtime of the file back to what it was.

pyfilenamemtime plugin

Using the pyfilenamemtime plugin one can force the mtime by using a filename format like xxxxx-YYYY-MM-DD-hr-mi.txt .

If a filename contains a timestamp in the form of YYYY-MM-DD-hh-mm, change the mtime to be the timestamp instead of the one kept by the filesystem. For example, a valid filename would be foo-2002-04-01-00-00.txt for April fools day on the year 2002.

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

Comments

PyBlosxom does not come with comments functionality built-in. Instead, comments are implemented as a plugin which people who are interested in in having comments can install and everyone else can ignore.

Available comments plugins:

  • Magic Word : The Magic Word plugin is a way of preventing comment spam. It is a bit like the nospam plugin, but...
  • nospam : Human verification for the comments plugin. Based on a idea and ref impl of Jesus Roncero Franco <j...
  • comments : Comprehensive comments support for pyblosxom, includes files for trackback, pingback (requires xmlr...
  • wbgcomment_blacklist : This plugin works in conjunction with the comments plugin (i.e. you need the comments plugin for th...
  • akismet comments : This plugin merges the work of two plugins by myself and Blake Winton. The comment uses the API of ...

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

Syndication

Most newsreaders read most of the syndication formats. So you shouldn't feel that you have to implement each one of them in your blog--you can most assuredly get away with implementing RSS 2.0 or ATOM and be just fine.

Feed formats that come with PyBlosxom

PyBlosxom comes with a few default flavours, three of which are feeds.

RSS 0.9.1

PyBlosxom comes with an rss flavour that produces RSS 0.9.1 output. Here's a sample of what it produces:

Example 9-1. example of RSS 0.9.1 feed


<?xml version="1.0" encoding="utf-8"?>

<!-- name="generator" content="pyblosxom/1.2 3/25/2005" -->
<!DOCTYPE rss PUBLIC "-//Netscape Communications//DTD RSS 0.91//EN"
"http://my.netscape.com/publish/formats/rss-0.91.dtd">

<rss version="0.91">
<channel>
<title>My Blog</title>
<link>http://www.joe.com/blog/index.rss</link>

<description>This is my blog about trivial things</description>
<language>en</language>
<item>
    <title>Example of an entry post</title>

    <link>http://www.joe.com/blog/entries/example1.html</link>

    <description>&lt;p&gt;
  Here's an example of an entry in my blog.  This is the body of the entry.
&lt;/p&gt;
</description>
  </item>
</channel>
</rss>

This example only has one entry in it. The number of entries the rss flavour will display is determined by the num_entries property in your config.py file.

probably better not to use RSS 0.9.1
 

RSS 0.9.1 format lacks dates in the data for the items. Unless you include the date for the entry somewhere in the description block, people looking at your RSS 0.9.1 feed won't know what the date the entry was created on was.

Unless you have some reason to use RSS 0.9.1 as your syndication format, you should look at using RSS 2.0 or Atom 1.0 both of which also come with PyBlosxom.

The standard for RSS 0.9.1 is at: http://my.netscape.com/publish/formats/rss-spec-0.91.html

RSS 2.0

PyBlosxom 1.3 comes with an RSS 2.0 flavour called "rss20". If it's missing features that you want (for example, some folks are doing podcasting with their blog), then override the individual templates you need to adjust.

The standard for RSS 2.0 is at: http://blogs.law.harvard.edu/tech/rss

Atom 1.0

PyBlosxom 1.3 comes with an Atom 1.0 flavour called "atom". If it's missing features that you want, then override the individual templates you need to adjust.

The standard for Atom 1.0 is at: http://atomenabled.org/

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

Static Rendering

Static rendering made its first appearance in PyBlosxom 1.0. It fills the functionality gap for people who want to use PyBlosxom, but don't have a web-server with CGI installed, don't have CGI access, or can't run PyBlosxom for one of a myriad of other reasons. Static rendering allows these people to run PyBlosxom on their local machine, write blog entries, render their entire site into HTML, and then use ftp or some other file copy method to move the pages up to their static web-site.

PyBlosxom's static rendering allows for incremental building. It can scan your entries, figure out what's changed, and render only the pages that need re-rendering.

Beyond that, it's not particularly sophisticated.

Configuring Static Rendering

These are the instructions for configuring static rendering in PyBlosxom.

  1. Install PyBlosxom. When you're copying the pyblosxom.cgi and config.py files, you don't have to put them in a CGI directory--you can put them in any directory you have permissions in. For example, I created a directory /home/joe/pyblosxom/ and put both files in there.

  2. Add static_dir to your config.py file. This is the directory we will save all the static output. The value of static_dir should be a string representing the absolute path of the output directory for static rendering.

  3. Add static_flavours to your config.py file. The value of static_flavours should be a list of strings representing all the flavours that should be rendered. This defaults to [ "html" ].

  4. Add static_monthnames to your config.py file. The value (either 1 or 0) will determine if you want month names (such as April) in the static pages.

  5. Add static_monthnumbers to your config.py file. The value (either 1 or 0) will determine if you want month numbers (such as 04 for April) in the static pages.

  6. Set base_url in your config.py file to the base url your blog will have. For example, if your static_dir were set to /home/joe/public_html and the url for that directory were http://www.joe.com/~joe/ , then you probably want your base_url to be http://www.joe.com/~joe/ .

Example 7-1. static rendering configuration


py["static_dir"] = "/home/joe/public_html/static/"
py["static_flavours"] = ["html"]
py["static_monthnames"] = 0     # i do not want month names
py["static_monthnumbers"] = 1   # i do want month numbers

#!/bin/bash
./pyblosxom.cgi --static

or 
./pyblosxom.cgi --static --incremental

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