Dented Reality Notes

I got an email from someone in relation to FeedBlendr, asking me what RSS really is, and what you're supposed to do with it. He liked my reply so much that I thought I'd share it here for anyone else who's having a bit of a tough time understanding all these acronyms (although admittedly I did use another one in my definition, but what the hey?);

"So basically RSS is a way for websites to make their content (normally time-based stuff like blog posts or news) available to people in a machine-readable format (a dialect of XML)"

Hope that helps someone (else) out there!

I've just gotten around to getting a copy of a lengthy post that I made to the blosxom mailing list about the different types of Blogging APIs and how they apply. It covers the Blogger API (1.0 and 2.0), metaWeblogAPI, Atom and a bunch of stuff relating to blosxom.

It's been archived as a feature article for posterity :)

Have I mentioned BlogLines.com? It really is a cool service, and what's more - it's free.

BlogLines is an RSS aggregator; don't let that big name scare you - basically it allows you to get content from a bunch of sites, organised into your own directories and catgories, all in one place. It's perfect for keeping up to date on news, reading your daily blogs, or perhaps receiving certain types of updates and things like that.

There's not much I can say, other than it's a very well-made system, it's entirely web-based (so you can access it from all machines you use) and it has some great features which make managing your feed subscriptions really easy. Check it out and see what I'm talking about.

You may or may not have noticed, but the posting times on this blog have changed recently, because I installed the excellent blosxom timezone plugin, written by Raffi Krikorian.

It was wonderfully easy to configure, all I had to do was put in my own timezone, and it works out all times for posts based on the timezone of the server, in relation to mine.

In amongst all the talk of the Atom API (which might one day actually be released and usable) and RSS, and with me working on some XML/XSL things at work, I realised that there's probably another option entirely with blosxom as far as templates/flavours/themes goes, and it goes a little something like this;

Three Xs, therefore blosxxxom, that's one for blosxom (Apple's OSX), one for XML and one for XSL, which are the three technologies we're dealing with here.

1. Install the theme plugin for blosxom and get it working (this plugin makes life much easier!)
2. Now create a new theme, with a suitable name (mine's called 'blosxxxom' for the sake of the experiment, and it looks like this; page.blosxxxom. This theme should create a valid XML document from your posts.
3. Your XML output should refer to an XSL stylesheet, which will actually take care of doing the formatting, entirely client-side (style.xsl in my example theme file)
4. In the XSL file, just use normal XSL processing instructions to handle the output and presentation of the XML document into XHTML!
5. Point your browser to blosxom and tell it to use the flavour name that you used to create this theme, and you should be able to see what the output looks like. View the source of the document and you should see the plain XML produced by blosxom :)

Now, for a couple notes;

• I made my content_type value in the theme text/xml, but this forced blosxom to encode special characters to be nice for me. I found that it was better to comment this section of the main CGI out so that I could drop the values in, and wrap them in the CDATA tag seen in the XML theme.
• Rather than worry about what's in the body much, I just wrapped things in a <![CDATA[ tag ]]> to be safe.
• Mozilla doesn't currently display my output properly - it's not doing links (or any tags) properly, and it's just showing them rather than interpreting them as HTML. Anyone got any ideas on this one?
• There's more to be done, but it's a fun point to start at, and there's no reason why you can't add things like a COMMENTS element to your STORY node, or a KARMA, a META node with a series of elements - it's pretty free-form if you're only doing the XML for your own presentation needs!

Hope that's inspired some people to try some things out that they might not have otherwise tried, and if nothing else, it just demonstrates how flexible blosxom really is! :)

The most common complaints/questions on the blosxom developer's mailing list all relate to difficulties with plugins, so I have been trying to think of a way to make them a little easier to work with for people. What I came up with is blosxconfig, a single PHP script which works with very basic configuration files to determine what variables a user should have access to and what format they should be in. It will also confirm the existence and readability of the plugin files, and write the modified variables directly into the plugin files.

Download blosxconfig BETA version now!

Here's the details that I posted to the blosxom list;

WARNING: Back up all you plugins before saving changes via blosxconfig!!!

configure.php is a PHP script (duh!) so you'll need PHP on your server to run it. You can pass a path to it to look for a specific config file via either a GET or POST request (GET use ?conf=path-to-conf.conf on the querystring, POST use variable name 'conf' with a value of a path to a config file). if you don't pass a value, then blosxconfig will look for a file called blosxom.conf in the same directory as it, or die trying ;)

The config files are very basic, and look a little bit like a Windows ini file, but it's a custom style;

The first line is similar to a unix 'shebang' line, and should look like this;

#@/path/to/plugins

where obviously the /path/to/plugins is the full path to where your plugins live - this should be the same as the $blosxom::plugin_dir variable configured in your blosxom cgi executable.

After that line, you have plugin sections which are defined using [plugin_name] - be careful that you use the *exact* name of the plugin, because the value is used for confirming the plugin's existence :)

Under each plugin section, you define definable variables on a line each, in this format;

variable_name|type|default

variable_name is the actual name of the variable (as written in the script), without the '$' or '@' (in the case of arrays)

type can be one of 'string', 'boolean' or 'code'. Arrays should be defined as 'code'. Strings are enclosed automatically in quotes (") and all types are followed by a semi colon when written to file. Booleans are presented to the user as a Yes/No select box (0/1 passed as values) and other types are presented as simple text input fields.

default is a value to use by default. make sure this makes sense (so for a boolean make sure it's 0/1, for a string it's a string etc). You don't need to wrap it in quotes or anything, this is handled automatically.

Now, assuming you have a valid config file and blosxconfig can find it, it will load the file, and present you with an interface where you should be able to modify all the values that you spcified as being editable in the config file. *hopefully* blosxconfig will also tell you at this point if plugin files are available (file exists in plugin dir) and if they are not readable or writeable. when you have made you changes - click 'save' and the following will happen;

WARNING: Back up all you plugins before saving changes via blosxconfig!!!

1. All plugin files which are referenced in your config file will be MODIFIED - they will technically be overwritten entirely, since the contents of the file are processed, then the lines that look like they define the variables in question are replaced with new lines, with the new values.
2. The config file will be updated with the new details that you specified and written back to file.
3. blosxconfig will load again, with all your new values in place, and messages telling you what happened.

Assuming all goes well, you've just used an external interface to reach into your plugin files and modify certain details. The hope is that authors of plugins (or community-minded participants) can supply the simple, 1 - 10 lines worth of config required to add to this configuration file, which can then be distributed with this little application to help people configure their plugins.

Please be aware that I have *NOT* tested this extensively at all, it was hacked together and seemed to work for a couple of plugins that I was running (the ones in the config file included) on a Windows test box, other than that I can't make any promises. I'd LOVE if some people could try it out on some other plugins, on other systems, and let me know (directly if you like) how it goes. I'll fix any problems and then release it as public so that other people can use it.

Hope it's useful for someone out there, and can perhaps eventually make life easier for some newbies (and pro's alike :)

Oh yeah - did I mention; BACK UP YOUR PLUGINS BEFORE YOU TRY THIS!

On the suggestion of Andreas Banze, I've removed one small section which checked to make sure that the plugin files were executable, since as he pointed out, this is not necessary, they are just included in the main operation of the blosxom script, not executed individually.

Download blosxconfig BETA version now!

In case you didn't notice, all my blosxom plugins are working again!

Now that that is taken care of (ended up being a naming conflict within a plugin), I can eventually get around to doing what I had actually intended on doing, which is upgrade to the official release verion 2.0 of blosxom, and then implementing some more plugins to create better RSS feeds and probably sub-topic menus within the templates to aid in navigation of the sections.

Thanks to phpwebhosting.com (my web host) for giving me access to an error_log, even if it's only a shared one across the whole server :)

This looks like it could be a good read - it's a blog called Coherence Engine and it says that it's about "Social software, human interfaces, online games, biological models of computing, intellectual property, and the future of software."

Well, Fletcher has been flying away at the karma plugin we discussed and has got a version 0.3 going already. This one has the following features;

1. Show number of visits/votes
2. Show positive and negative votes
3. Show Controversy Index
4. Show Karma Index
5. Show Visits Index
6. Only show posts with minimum of 'x' for;
   1. Karma
   2. Controvery
   3. Interest

You can download karma 0.3 and drop it in as a plugin immediately. It's pretty self-explanatory if you understand the concept. To figure out the way that controvery and interest are calculated - have a look in the code for now, I'll post the formulae when I get a chance :)

I emailed the blosxom mailing list and suggested a new plugin, which I am just calling "karma". The idea was to allow people to click a + or - and indicate if they thought a post was good or not. This is similar to the system used on some other sites.

I got an email back from Fletcher Penney, who said that he'd develop it, and half an hour later we were chatting on MSN about the details. He's already knocked out 2 draft versions and we are sorting out some great stats and uses for the information!

blosxom and its developer-community rules!