Flavour
Blosxom gives you two flavours right out of the box: a basic default HTML view and an XML-based RSS view for syndicating your blog. I've also created a Blosxom Flavour Sampler, consisting of a couple-three sets of flavour templates (we'll talk about those in a moment) to get you going.The default HTML view--by design, mind you--simply cries out to be altered. An earth-shatteringly bland white background with your blog title in large letters. Posts are functional, albeit also a little bland:
Typical Post
Your typical Blosxom post consists of a required title
on the first line and any manner of text and HTML
markup in the body.
posted at: 11:33 | path: / | permanent link to this entry
Thankfully, re-decorating is quite simple. There are only two bits of information you need to understand: template components and template files.
template components...
Template components are chunks of dynamic content made available to you by Blosxom. $blog_title, for instance, is a placeholder for what you set as the title for your blog during configuration; wherever that appears in your flavour template, it is replaced on the fly with its proper value.
Template components come in two forms: global and story.
...global template components
Global components are available for your use in any of the template files. Some are set in the Blosxom configuration, while others are generated on-the-fly:$blog_title
The title of your blog, as set in Blosxom's configuration.
e.g. My Blosxom Blog$blog_description
The description of your blog, as set in Blosxom's configuration.
e.g. A blog about this and that.$blog_language
The language code set in Blosxom's configuration.
e.g. en-us$url
Your blog's URL, as determined automagically by Blosxom or set explicitly in Blosxom's configuration.
e.g. http://www.example.com/cgi-bin/blosxom.cgi$path_info
The requested view, a path or date or combination thereof.
e.g. /society/television/retro/1977/$flavour
The requested flavour.
e.g. http://www.excampe.com/cgi-bin/blosxom.cgi/index.someflavour
...story template components
Story components are specific to the particular story/blog entry at hand and, so, change from story to story.
$title
The title of a blog posting.
e.g. Typical Post$body
The body of a blog posting--everything beyond the first line (title) of the file.
e.g. Your typical ... in the body.$url
Your blog's URL, as determined automagically by Blosxom or set explicitly in Blosxom's configuration. This is actually a global template component, but useful for constructing permalinks to stories, and so listed here too.
e.g. http://www.example.com/cgi-bin/blosxom.cgi$path
The path in your blog's directory/folder hierarchy at which the post lives.
e.g. travel/india$yr, $mo, $mo_num, $da, $hr, $min
The date/time at which the post was written, expressed as year, month (Jan-Dec), month numeral (01-12), day (01-31), and time in hours (00-23) and minutes (00-59), respectively.
e.g. 2002, "Dec", 12, 01, 11, 33$fn
The post's filename, without the file extension (usually.txt).
e.g. typical_post
With that under our belts, we'll step through a sample HTML flavour, introducing you to the various bits and bobs as we go along. Remember that all of these files don't yet exist as the default HTML view is built-in (it actually lives in the blosxom.cgi script itself, if you can believe that). By creating a new HTML view, we're overriding the built-in version.
template files...
A Blosxom template consists of a head (all the stuff before your posts), foot (all the stuff after), story (the formatting for an individual post), content_type (sets the content type of a particular flavour), and (optionally) date (controls the look of daily datestamps). These exist in simple text files named, appropriately enough: head, foot, story, content_type, and date. But Blosxom allows for more than one flavour, so each threesome must somehow be associated together. Thus, for an HTML flavour, we have:head.html, foot.html, story.html, content_type.html, and date.html. Simple, eh?
...the header
The header, as I mentioned, is everything appearing before you stories themselves. The header for the HTML flavour makes its home in a file called head.html in your data directory.
Here's a nice sample head.html to get you going:
<html> <head> <title>$blog_title</title> </head> <body bgcolor="#ffffcc"> <b>$blog_title</b> <hr size="1" noshade /> <p />Copy-and-paste this HTML to your favourite text editor and save it as a plain text file to
datadir/head.html, where datadir is your Blosxom data directory.
Notice that $blog_title bit? That's one of the global template components mentioned further up this page.
...the footer
Just as the header contains everything appearing before the stories, The footer contains everything you'd like to appear after. The footer for the HTML flavour lives in a file calledfoot.html in your data directory. Here's a nice sample foot.html consisting of a nice horizontal line and "powered by blosxom" button:
<p /> <hr size="1" noshade /> <a href="/"><img src="http://www.raelity.org/images/pb_blosxom.gif" border="0" /></a> </body> </html>Copy-and-paste this HTML to your text editor and save it too as a plain text file to
datadir/foot.html .
Reload your Blosxom page and notice the difference.
Of course its not written anywhere that you must include a "powered by blosxom" button on your page, but it's a nice way to identify yourself as a Blosxom user and point the way to Blosxom for anyone who's interested in starting their own weblog.
...the story
The look-and-feel of each story is specified in the story template,story.html in your data directory. Let's spice up that default story layout a little using some prettier HTML and the story template components available to us, shall we?
<p> <a name="$fn"><b>$title</b></a> <br /> $body </p> <p align="right"> <i>[<a href="$url$path">$path</a>] <a href="$url/$yr/$mo_num/$da#$fn">permanent link</a></i> </p>
...the story ...permalinks
A word about permanent links, or "permalinks". Permalinks provide a permanent URL for others to use when referencing one of your postings that promises never to change. While stories my drop off the bottom of your weblog's home page -- remember, they're presented in reverse-chronological order -- the permalink assures a link will withstand the ravages of time and template. Blosxom's default permalink style is date-based (as shown above). For example, a story saved to the filea_story.txt on January 1st, 2003 is permalinked as http://www.example.com/cgi-bin/blosxom.cgi/2003/01/01#a_story. This brings up a page with only stories from that day and directs the browser to hop down to the right story (the #a_story bit). To accomplish this kind of permalinking, your story template should include something like: <a href="$url/$yr/$mo_num/$da#$fn">permanent link</a>
You may prefer to use path-based permalinks. A story saved to the file a_story.txt in the directory datadir/fiction would be permalinked as http://www.example.com/cgi-bin/blosxom.cgi/fiction#a_story.txt. For this type of permalinking, your story template would include something like: <a href="$url$path/index.$flavour#$fn">permanent link</a>
You can also permalink to an individual story appearing all on its own. This is a modification of the path-based permalink. Your story template would include: <a href="$url$path/$fn.$flavour">permanent link</a>
...the content-type
The default content-type encoding -- what Blosxom tells your browser the type of output its about to see is -- is Plain Text (text/plain, to be precise). If you wish to create a template with different encoding (e.g. text/xml or text/html), you'll need to create a content_type.flavour file (where flavour is the flavour you're working with) specifying so.
For our example (an HTML flavour), the content-type should be text/html, specifying that this is to be interpreted by the browser as an HTML document.
Copy-and-paste the following to your text editor and save it as a plain text file to datadir/content_type.html .
text/htmlIf, for example, you were creating a custom XML flavour for your weblog called "exemel" which should be of content-type
text/xml, you'd simply create a file called datadir/content_type.exemel containing the one line: text/xml
...the date
Prepended to each day's clump of entries is a date-stamp. The default look-and-feel for the date-stamp is:Wednesday, 01 Jan 2003If that suits you, feel free to skip creating a
date.html template file. Otherwise, go ahead and alter it using any of the story template components relating to date: $yr, $mo, $mo_num, $da, $hr, $min.
Perhaps, for instance, you prefer an italic, purely numeric date for your HTML flavour. Copy-and-paste this HTML to your favourite text editor and save it as a plain text file to datadir/date.html, where datadir is your Blosxom data directory.
<i>$mo_num/$da/$yr</i>
This yields:
01/01/2003Aside from knowing where to save your template files and what template compnents are at your disposal, the sky's the limit. Use CSS, JavaScript, XML, plain text, ... Go hog wild. It's your weblog and you can style if you want to.
a wealth of flavours...
Don't wander off quite yet. There's a little something else you should know about flavours... there is a wealth of them, limited only by your interest and ingenuity. While the HTML and RSS flavours come right out of the box, you can create any flavour of your choosing simply by creating ahead.flavour, foot.flavour, story.flavour, content_type.flavour, and (optionally) date.flavour for each, flavour being your preferred flavour name.
Want a "circa 1993" flavour to cater to older browsers? Create head.1993, foot.1993, and story.1993 files in your data directory just as you did for the HTML flavour above. How about a "titles only" view of your weblog, displaying only the titles and none of the other details for each entry? You guessed it: head.titles, foot.titles, and story.titles .
To view a particular flavour, tack either index.flavour or ?flav=flavour (where flavour is the flavour at hand) on to the end of your Blosxom URL. So, for example, the 1993 flavour might be found at either http://localhost/cgi-bin/blosxom.cgi/index.1993 or http://localhost/cgi-bin/blosxom.cgi/?flav=1993.
index.flavour, the ?flav=flavour variation being provided for backward compatibility with older versions of Blosxom.