Softpanorama (slightly skeptical) Open Source Software Educational Society

May the source be with you, but remember the KISS principle ;-)

Blosxom

Blosxom was written by Rael Dornfest, a programmer at O'Reilly and Associates. I initially wrote off Blosxom as an unrealistic tool for blogging, assuming that its small size was indicative of its abilities. But Blosxom's power is not only in its strong feature set but in the way it allows us to mix and match functionalities.

This is a test entry.
<p>Hello!</p>

touch -t 200401011500 testing.txt

Old News

The Unofficial Blosxom User Group

Already a while ago, Kevin Scaldeferri, head of the current Blosxom developer group, managed to get all the content from Rael's well known but neglected Blosxom prime site at blosxom.com online at the SourceForge hosted website of the current Blosxom developer group at blosxom.sourceforge.net, where the developers have access to and can start updating the content.

To really be up-to-date, it will take a while, but at least the content is there, since blosxom.com seems no more reachable, as someone noticed today on the Blosxom user's mailing list.

At the Forge - Blosxom Linux Journal

Flavours

If this were all that Blosxom provides, I would not be too impressed. But after examining it a bit more closely, I see that it contains a great deal of power. That power is there thanks to the combination of display templates (known as flavours, using the British spelling) and the ability to accept any number of plugin programs. The combination of these two features makes Blosxom quite extensible.

Blosxom comes with two flavours built-in, the default HTML flavour and the optional RSS flavour for the RSS syndication feed. You can view the RSS feed yourself by tacking ?flav=rss onto the end of your blog's URL. So, if you normally view your Weblog at http://localhost/cgi-bin/blosxom.cgi, you can view the RSS feed for the site at http://localhost/cgi-bin/blosxom.cgi?flav=rss. Alternatively, you can specify your preferred flavour by changing the suffix of the page you retrieve. Thus, we can see RSS with http://localhost/cgi-bin/blosxom.cgi/index.rss.

A complete flavour registry is available on the Blosxom Web site. But the basic idea is easy to grasp: in your data directory, alongside your Weblog entries, you create an HTML file whose name reflects the part of Blosxom's output you want to change.

The filename's suffix is the same as the flavour you want to modify. Thus, the file header.html changes the way the Weblog's header is displayed in the HTML flavour, and date.blah changes Blosxom's display of dates in the blah flavour. Users can set the flavour in the URL by adding the flav name-value pair (as we saw before), and the default is set in blosxom.cgi itself, with the variable $default_flavour. Because blog entries have a .txt suffix, you cannot have a txt flavour.

Each flavour file consists of an HTML snippet, along with Perl variable names that might be instantiated into the particular file. For example, story flavour files receive the variables $title and $body, among others. (A full list is available on the Blosxom Web site.) I thus can change my blog's output such that headlines are huge and right-aligned, followed by the body:

<p>
<H1 align="right">$title</h1>
<br />
$body
</p>

The above flavour inserts the $body variable, the contents of our blog story, verbatim into the HTML. This is fine if the blog author knows HTML and is willing to enter paragraph tags manually. But if we want to let people separate paragraphs with blank lines, we need to run a program on our story. Luckily, Blosxom makes it easy to write such programs with an extensible plugin architecture.
 

Plugins

Each plugin is a Perl program loaded with the require function, which reads and evaluates code in a particular file. So require foo.pl opens foo.pl and evaluates the code it contains. Because require executes at runtime, whereas use executes during the compilation phase, it is far easier to work with it here.

Blosxom assumes that any file in the plugin directory, defined by the optional $plugin_dir variable, is a plugin. Plugins are both loaded and applied in alphabetical order, which means if you want to make sure a particular plugin is applied first or last, you might need to rename it.

Each plugin is nothing more than a simple Perl program that defines one or more subroutines. Every plugin must define the start subroutine, which simply returns 1. This allows Blosxom to determine that the plugin is alive, ready and willing to be invoked. A number of other plugin subroutines are available that each plugin optionally may define, ranging from entries (which returns a list of entries) to story (which allows you to modify the contents of a story). By breaking things down in this way, Blosxom allows for a tremendous amount of customization and sophistication, while keeping the core code small and compact.

So, what sorts of features can plugins provide? There seems to be only a few restrictions. You can change the source from which Weblog entries are retrieved, the way in which this list of entries is filtered, the templates used to display the entries and the contents of the entries themselves.

A large number of plugins are available from the Blosxom Web site. Some of them depend on other plugins, while others, such as the calendar, appear only if you are using a flavour that supports the plugin. Other plugins work immediately and merely need to be dropped into your plugin directory.

A simple example of a plugin that works out of the box is atomfeed, which provides an Atom syndication feed. Atom is a competitor to RSS that has been promoted by a number of heavy-hitting bloggers and programmers, in no small part because of the competing standards now evident in the RSS world. To get an Atom feed, simply copy the atomfeed plugin to your plugins directory. You then can retrieve your Atom feed with http://localhost/cgi-bin/blosxom.cgi?flav=atom or http://localhost/cgi-bin/blosxom.cgi/index.atom.

Writing Plugins

Listing 1 contains a simple filter, called egotrip, to make my name appear in boldface whenever it appears in a Weblog entry. Notice how the plugin must define its own package; this ensures that each plugin's subroutines are kept in a separate namespace and makes it possible for Blosxom to determine whether a package contains a particular method name.

Listing 1. egotrip.pl

#!/usr/bin/perl
use strict;
use warnings;
use diagnostics;
package egotrip;
# Returns 1 to indicate the plugin is active
sub start
{
    return 1;
}
# Boldfaces my name
sub story {
    my ($pkg, $path, $filename, $story_ref,
        $title_ref, $body_ref) = @_;
    $$body_ref =~ s|Reuven|<b>Reuven</b>|g;
    1;
}
1;

The actual work is done in the story subroutine, which is passed six arguments when invoked by Blosxom, corresponding to a number of items having to do with the entry. In our case, we care about changing only the body of the entry, which is in the final variable, known as $body_ref. As its name implies, this is a scalar reference, which means we can access or modify its contents by dereferencing it, using two $$ signs. With that in mind, it should not come as a surprise that we can boldface every instance of my name with:

$$body_ref =~ s|Reuven|<b>Reuven</b>|g;
 

Of course, we could make this step even more sophisticated and insert automatic hyperlinks to a number of different items:

$$body_ref =~ s|(Reuven Lerner)|
↪<a href="http://www.lerner.co.il/">$1</a>|g;
$$body_ref =~ s|(Linux Journal)|
↪<a href="/">$1</a>|g;
 

Indeed, a plugin of this sort already exists; it automatically creates links to the community-driven Wikipedia. Any text placed within [[brackets]] automatically is turned into a link to that on-line reference book.

Notice how flavours are HTML templates into which we can instantiate Perl variable values, whereas plugins are Perl programs. This division between display and actions takes a little bit of time to grasp, but it shouldn't be too difficult.

As for our paragraph-separating problem from before, there's no need to reinvent the wheel. You simply can download a plugin, Blox, that allows you to separate paragraphs with blank lines when writing your blog entry. The plugin then separates paragraphs with the HTML of your choice. Blox is listed on Blosxom's plugin registry (see the on-line Resources section).

The fact that Blosxom keeps all entries and flavours in a single directory is a bit disturbing to me and makes me wonder about the program's scalability. Even if my filesystem and Perl can handle that many files without too much trouble, do I really want to wade through them all? If and when this becomes a problem, an entries plugin probably can provide the right solution, scooping up files from multiple directories and returning an appropriate hash to Blosxom.
 

Conclusion

Blosxom is a powerful tool for creating a Weblog; it's more than it might appear at first glance. Blosxom consists of an easy-to-install, easy-to-configure CGI program written in Perl, but its true power lies in the fact that it lets you change every part of the display through a combination of flavours (display templates) and plugin routines. By mixing and matching existing flavours and templates with something of your own, it can be easy to create your own Weblog.

Resources for this article: www.linuxjournal.com/article/7454.

Reuven M. Lerner, a longtime consultant in Web/database programming, now is a graduate student in Learning Sciences at Northwestern University in Evanston, Illinois. You can reach him at reuven@lerner.co.il.

Review Blosxom Blogging Script - webreference.com

By  Lee Underwood

If you spend any amount of time on the Web, it's a pretty safe guess that you've heard of blogs. Basically, a blog is an online journal, but there's more to them than just posting your daily thoughts.

Blogs are used used by corporations to keep their customers updated on current products and trends, business leaders use them to share their views on a variety of topics (Jupitermedia Chairman and Chief Executive Officer Alan M. Meckler has his own blog), they are used by individuals to address topics related to specific subject areas (JupiterReasearch has several analysts who write their own blogs) and individuals use blogs to address subjects which are more personal to them. There are political blogs, religious blogs, news blogs, personal blogs, industry-specific blogs and many more. Together, I suspect they cover the entire human experience.

From a Web designer point-of-view, blogs may need to be established for several reasons: to provide current information about your services; to comment on the topics of the day as they relate to Web design or to set one up for a client. Anybody can start a blog and there are several ways to go about setting one up. The three most basic methods are:

Create a page on your Web site and post your comments to it. Join one of the many existing blog communities (i.e. Weblogs, Inc. or Blogger). Create your own blog on your own Web site, using one of the many existing blogging packages (i.e. Blosxom, Movable Type, or WordPress)

Each of these methods has its share of positive and negative aspects, although the first method is rarely used. Within the blogging community, the second two methods seem to be the most popular. For our purposes we'll take a look at one of the existing blogging scripts, Blosxom.

During my recent vacation, I decided it was time to set up a blog about my personal Web sites. I've read the horror stories that many people have experienced with some of these programs — and many of those people are really tech-savvy. It seems that blogging software can be a bit frustrating at times. Many of the packages also require a database (which I didn't want) as that could complicate things a bit. I was just looking for something simple, something I could quickly set up and start posting. I don't even recall how I stumbled upon Blosxom but it seems to be a popular program (judging from the search results on Google).

Blosxom (pronounced "blossom") is a compact, easy-to-use blogging script created by Rael Dornfest, Chief Technology Officer at O'Reilly Media. It's Open Source so it's free. The entire package consists of one file written in 444 lines of Perl code. Very simple. There are 10 variables to configure, 12 if you use plugins, which I'm sure you will. (There are four additional variables to configure if you set up static rendering.)

This script has all the bells and whistles, just like the others. It automatically creates RSS feeds, you can set up trackback links, ping other servers and allow visitors comments.

Configuration and Installation

As I said, the program is just one script, so configuring the variables is quite simple. Instructions are given right on the Web site. Basically, it's just a matter of adding the title of your blog, a description and some path information. That's all there is to it. If you're interested in the coding, Frank Hecker created an annotation version of the script.

Installing the script is a snap. Once again, instructions are on the Web site, but if you've ever installed a CGI script, you could do it blindfolded. You just drop the script into your CGI bin and change the file permission to make it executable.

Plugins and Flavours

These are used to change the display and makeup of the blog itself. By mixing and matching these, you can personalize the blog to match your own site or preferences.

Plugins are used to add customized features to each blog. They're easy to use; most just need to be uploaded to the site. To activate plugin support, just create a plugin directory on your Web site. While you don't need them to use Blosxom, they add another dimension to the blog. There are plugins available for all kinds of different things: setting up archives or a calendar, listing different categories for your postings, changing the date display, setting up the display, letting visitors make comments, customizing RSS feeds, setting up cookies, creating polls and many other options. On the Blosxom Web site there are 239 plugins, divided into 35 categories. In addition, there are other plugins on other Web sites. You can even write your own plugins.

Flavours are nothing more than templates that tell the script how to format the pages displayed. (The spelling within the program is "flavours.") If you like the default output, you don't even need to create one. You will need to do it, however, if you want to blend the blog into an existing site. It took me about five minutes to create a set to match my site. A "set" is made up of four small files which, together, comprise a whole page. Just take an existing page from the site and cut it up into four parts:

head (the top section). date (displays in the blog's date section but you can choose to display another stuff). story (the individual blog posting itself). foot (the footer at the bottom).

Posting to the Blog

Well, this is what we were working for, the ability to post our comments and thoughts for all the world to see. The actual blog postings are plain text files loaded into a designated directory on your Web server with a ".txt" extension. You can add HTML coding, if you like. You can even post to it via e-mail.

Conclusion

For the most part, that's all there is to setting up the Blosxom blog. As I said, it's easy to create and use a blog with this script. There's no need to set up any databases either. One of the nice things is that it doesn't have to look like all the other blogs.

If you're looking to create your own blog, or set one up for a customer, be sure and check out Blosxom. It could save you a lot of headaches.

Additional Links

The Blosxom Web site Download the script The Unofficial Blosxom User Group

[1-Feb-2003] Network Computing/Perl-ing your BlogsDr Seamus Phan,

Weblogs, or blogs, have become the underground movement for online journalism. With blogs, it is very easy for users who have no experience in writing HTML code, or using visual HTML editing tools such as Macromedia DreamWeaver MX, to upload Web content.

It is done by using nothing more than glorified text editors with FTP (file transfer protocol), or even through the new breed of GUI-based blog writing and upload tools with a Web browser.

If you examine some of the blog editing tools closely, you will see that they are nothing more than repackaged text editors with a simple FTP client included. If you are familiar with C++, Java or Cocoa programming, you are likely to be able to write such a tool in under one day flat. The code may not be pretty and there may be specific GUI quirks depending on your operating environment, but I suspect that the tool will work.

Rael Dornfest, a researcher at O’Reilly & Associates, has a simple and elegant Perl blog script, which I have used in this example. It remains one of the simplest blog scripts I have seen, although in the future we may even have simpler PHP versions. If you need to integrate the blog uploads to a calendar, you may have to patch the script to accept Javascript or Perl calendar scripts.

Parameters for editing

Dornfest’s Perl blog script provides a few simple parameters to edit and you are ready to go. Bear in mind that if you intend to have a Website look-and-feel that resembles your own content, you have to tweak the head.html and foot.html files accordingly. Since this blog script, as with many server-based CGI scripts these days, rely on discrete HTML files to be joined during runtime execution, some server-based testing is necessary—quite a departure from static HTML editing.

First off, check that the line #!/usr/bin/perl –w is pointing to the right Perl directory on your server. Next, change those variables under “configurable variables”, especially the $datadir directory.

Dornfest’s script works by having you deposit simple text files into the right directory, and the script will automatically merge the textual content into the format determined by the style templates of the HTML code.

I have given an example of how the text file can look like. You can label the text file in any way you choose, although I would recommend that you name them in ways you can reference later, such as full date with single word description of the content (e.g. 20030115_higheredu.txt). Remember that as with any server systems, you should NOT have spaces in file names, and should respect Unix file naming conventions to avoid problems during deployment.

You can determine how many articles will display in a single Web page, under the $num_entries parameter. If you tend to upload short news clips, with embedded links to full text, you can have a higher number (e.g. 30). But if you tend to feature the entire article in full, you may want to limit the $num_entries to five or under.

Style’s a lot of work

As with many blog scripts out there, Dornfest’s Perl script allows the use of “flavours”, or templates. You name the templates xxx.html, and it can be addressed through the use of the URL convention. For example, you may want to call an alternative “flavour” other than the default, and your URL should be: http://www.ABC.com/pathto/blosxom.cgi/?flav=yourflavour.

If you think your job is done, think again. You need to prepare flavour template HTML files for each of the components, including the likes of head.yourflavour, foot.yourflavour, story.yourflavour, and content_type.yourflavour.

The content_type.yourflavour file is to state that the default content for all these discrete HTML components are indeed HTML, and not any other type of encoding.

HTML is a subset of XML, as is RSS, which is something that is used for news aggregation. Because RSS is recognised innately as well, it is therefore possible to tweak the script to recognise XML formatting, assuming that you have edited a new set of HTML or XML templates, including the head, foot and story files.

The script uses the join command to join the discrete HTML or XML components together to form the entire Web page, before using the print command to print to screen for representation in Web browsers.

Further, if you intend to stray away from the standard and understandably boring stylesheet, you have to know a bit about Cascading Style Sheets (CSS). With CSS, you can easily modify the entire look-and-feel of all Web pages and still be able to tweak individual textual elements on specific pages.

Dornfest’s script works mostly as advertised. However, showing full URL links exhibited some errors in certain freeBSD installations, although they can be tweaked to work. Most other Unix or similar operating systems should work without much hassle.

Worth the effort?

If you need a platform that can be an efficient and affordable news generation and collaborative tool, that is accessible to just about anyone who can use a Web browser, blogging is the way.

But if you need something more powerful, find a full-fledged content management system (CMS).

Seamus Phan is a research director at KnowledgeLabs News Center (www.knowledgelabs.net), an independent technology news bureau. He can be reached at seamus@knowledgelabs.net.

perl.com Blosxoms, Bryars and Blikis

by Simon Cozens
December 18, 2003

Recently we heard from Kake Pugh about the OpenGuides project, a wiki-based collaborative city guide system; previously, we heard from Brian Ingerson about his Kwiki wiki implementation. Guides, wikis, blogs ... the new fashion in software engineering at the moment is the use of software to help organize, document, and facilitate collaboration -- the social software movement is gaining momentum, and Perl is one of the best languages for it.

In this article we'll look not just at some of the existing social software tools in Perl (focusing, naturally, on my own Bryar blog toolkit), but we'll look at some ways to break, bend, and embed them in other tasks.

Basic Blogging with Blosxom

When I finally decided that the world would benefit from hearing my internal monologue, I naturally looked around for nice, simple blogging programs. Blogs are, essentially, simple things, and so I didn't want all-singing, all-dancing web-based database-backed content management systems. I knew that if I were going to blog, it would have to be easy for me to do so, and there's nothing easier than firing up a text editor in the next available terminal window and doodling my thoughts into it.

Thankfully, Rael Dornfest has the same sort of laziness as I, and created Blosxom, a very simple blogging tool, which simply reads a bunch of files from the file system, finds the most recent and relevant, packages them up together, and sends them at a browser. That was how I saw blogging.

Getting Blosxom up and running is, in keeping with the whole theme of Blosxom, quite simple. You need to download the blosxom zip file, unpack it, drop the blosxom.cgi file in your web server's cgi-bin directory, and then edit the first few lines of it to tell it the name of your blog and where the entries will live, and you're done.

Posting into the blog is just a matter of creating a file called something.txt in the blog directory. It doesn't even matter what the something is. All that matters is the first line of the file, which becomes the title, and the rest, which becomes the story in raw HTML:

First post!

<p> Today I set up a blosxom blog. It was really easy! </p>

You can then, if you like, style your blog with custom header and footer files, CSS, custom HTML for each blog post, and so on.

Enter Bryar

Of course, back when I started using Blosxom, things were not quite so easy, and templating required hacking the Blosxom CGI file itself, and things just didn't seem as neat as I wanted them to be. I liked Blosxom's simplicity, but didn't want to pay the price for it in terms of flexibility.

At the same time, I was learning the wonders of the Template Toolkit, and thought that a well-designed blog should merely collect Post objects and send them to a user-defined template to do what it wants with them.

So I started writing Bryar, which is designed to be a modular, extensible replacement for Blosxom. To make this happen, I needed to provide a default set of components that simply Does The Right Thing. Let's take a look at that default set before we go any further.

When we install Bryar from CPAN, we're encouraged to run a command to set up a new blog:

You probably want to run bryar-newblog in a likely home for
your blog once we've finished installing.
    

The bryar-newblog command simply sets up a decent default set of templates, creates a first blog post, and drops in a bryar.cgi driver, similar to blosxom. At this point, we're ready to go.

Bryar's default collection of modules consists of a Bryar::DataSource::FlatFile, which emulates Blosxom's use of text files in the file system as a database of blog posts; there are Bryar::Frontend::CGI and Bryar::Frontend::mod_perl, which describe how URL parameters are retrieved from the server translated into a request for documents, Bryar::Document which represents each post, and Bryar::Collector which ties it all together. With the benefit of hindsight, that should have been called a Bryar::Controller, since the whole thing can be described as a Model-View-Controller application. But more on that later!

Since all of these things can be overridden, we need something to keep track of which classes we're using, and the Bryar::Config class does that, reading an optional configuration file but otherwise providing mostly sensible defaults.

In the rest of this article we're going to look at some interesting ways to override those classes, and build some more funky tools out of this social software framework.

Recommended Links

SourceForge.net Blosxom

Last modified: March 15, 2008