Here's the complete text for the download you were just reading about. For those that hate to read documentation, here's a link to DOWNLOAD sidewordz 0.4.

To return to the Downloads page, click the Downloads button at left.

sidewordz 0.4

Using normal entry files placed in whatever directory you configure, sidewordz builds a "sideblog" available to your head or foot flavours in $sidewordz::output. Entry files are processed by blosxom plugins, just like in a normal blog — the entries are filter()-ed, sort()-ed, story()-ed, and then interpolate()-d from sidewordz.story template files.

Sideblog display is set by flavour files (templates): sidewordz.story.flavour_name templates are directory-specific, flavour-specific; sidewordz.story.all templates are directory-specific but flavour-generic; a blog-wide template can be stored in the plugin's DATA section..

All of blosxom's normal story() vars are available to your sidewordz flavour files, such as $yr, $mo, $da (all the time vars), $default_flavour, $url, $path, $fn, $title, $body, etc.

Plugins that you can't use/don't need can be skipped, through a config var; likewise, plugins "on standby" (plugin file name ends with "_") can be enabled through a config var. The number of sideblog entries is set with sidewordz' $num_entries config var. All settings are available to config plugins that run during filter() (not head().)


Configuring & Installing sidewordz

There are four variables to configure in sidewordz; you might want to tinker with the default template, too. Gather up some sideblog entry files, make (or not) a flavour file or two, upload all the files, and blog on.

Sideblog Entries datadir : analagous to blosxom's $datadir, this is the complete disk path to the directory that holds your sideblog entry files (and, if any, flavour files, config files, etc.). AFAIK, your sidewordz $datadir must be located in your blosxom datadir, so what you enter here is always going to look something like: $datadir = "$blosxom::datadir/foo/bar"

Number of sideblog entries : analagous to blosxom's $num_entries, this is the number of sideblog entries to display. So, for example: $num_entries = 5 .

Plugins that shouldn't run: enter plugin names, separated by spaces, between the braces ({}) to keep them from running during sideblog processing. Just to be safe (more on this later), it is recommended that you always have these plugins configured to be off: my @unwanted_plugins = qw { excludez exclude hide };.

Plugins that should run: enter plugin names, separated by spaces, between the braces ({}) to take them from "standby" to "enabled" status. (This only works when a plugin name ends in "_". But don't include the underscore when adding a plugin name.) For example: my @wanted_plugins = qw { truncatez };.

Using config Files: AFAIK, your config plugin should run during filter(), and not during head(). Setting the $datadir and $num_entries vars is straightforward; e.g. $sidewordz::num_entries = 5;. Setting un/wanted plugins from config files is not (straightforward ;-) — instead of accessing the arrays from the config section, you'll access a pair of hashes, like this:

$sidewordz::unwanted_plugins{'exclude'}=1;  # don't want

$sidewordz::wanted_plugins{'truncatez'}=1;  # want


Flavour-ing sidewordz

Flavour files for sidewordz are just like "normal" story flavours, except that you p'bly want to limit the amount of $body you show (via seemore, foreshortened, truncatez, or a host of others). Use any of blosxom's normal "story" variables; use meta-vars, too! The default template identifies page elements with class="sidewordz"; you p'bly should, too.

For directory-specific, flavour-specific templates, name your flavour files sidewordz.story.flavour_name (no quotes), where flavour_name is one of your blosxom flavours (html, index, etc.). For directory-specific, flavour-generic templates, name the files sidewordz.story.all. For a site-wide flavour-generic template (i.e. default flavour), paste a template into the DATA section of the plugin.

All of blosxom's normal "story" variables are available to your flavours and plugins: $yr, $mo, $da (all the time vars), $default_flavour, $url, $path, $fn, $title, $body, etc. Your sidewordz flavours will be interpolated by blosxom's current interpolate() routine.

Using sidewordz

It is presumed that you'll want to keep your sideblog entry files isolated from your blog; the best way to do this is via plugins like exclude, hide, excludez, or others. But, when it comes time to process you sideblog, these plugins must be disabled (or the entry files won't be "visible" to blosxom); the easiest way to do this is via the @unwanted_plugins config var. sidewordz is pre-configured to "disable" these plugins during its run, and it is strongly recommended that you leave those three plugins listed in the @unwanted_plugins config var (just to be safe).

Also, if you use "caching" plugins (entries_index, etc.),they should p'bly be turned off for your sideblog (that is, added to @unwanted_plugins); ditto for labor-intense or specialty plugins like calendar, prev_next, better_title. etc. — but then again, there's nothing to keep you from using those plugins in your sideblog, AFAIK. Anyway, the point is that you've p'bly got a plugin or two that could stand to be skipped during sideblog processing...so look ;-)


Let's say you want to run a sideblog of...book reviews ;-) Here's a scenario using this blog structure:

 /datadir
   /images    # a pix is worth a kilobyte
   /flavours  # for flavourdir plugin
   /entries   # all your entries
     /books   # all your sideblog entries
     /mind    # directories/entries on the stuff you think about
     /body    # directories/entries on the stuff you do

You use the exclude plugin to hide the /books entries from "normal" blog pages; you only want to display snippets of sideblog entries, for which you'll use truncatez; your sideblog entries will provide sales info (ISBN numbers, Amazon links) through the meta plugin.

After configuring a sidewordz $datadir and $num_entries, you'll want to do some plugin adjusting; in particular, exclude-type plugins must be turned off (to allow blosxom to "see" your book entries), so you'll make sure that @unwanted_plugins contains "exclude" (no quotes). Don't worry — exclude is only "turned off" for your sidewordz entries; all the normal blog entries that you normally exclude are still "hidden."

You won't need truncatez to run all the time, just for your book entries, so you'll name the plugin "truncatez_" (no quotes), and add "truncatez" (you guessed it) to @wanted_plugins. And that's it for configuration.


You have a wealth of options for deploying your sidewordz flavour files. To tailor the sideblog to the current "mainblog" view, place sidewordz.story.flavour_name files in the appropriate "category" directories; for category-specific templates that work under any flavour, name the flavour files sidewordz.story.all. For blog-wide flavours, use any of the normal locations, or use the sidewordz datadir.

If one template will work in any situation (or to provide a default template), paste your template into the DATA section of the plugin.


Add the $sidewordz::output variable to your normal head or foot templates, and you're ready to test out your sideblog. If certain plugins seem to cause problems, or are clearly unneeded, add them to the @unwanted_plugins config var.

For more fine-grain control of plugins, use the config plugin and configuration files..but only after reading this SPECIAL NOTE: to change unwanted_plugins or wanted_plugins via config, you must access two hashes, not the arrays in sidewordz' Configuration Section. Turn a plugin off with:
$sidewordz::unwanted_plugins{'exclude'}=1;
and turn one on with:
$sidewordz::wanted_plugins{'truncatez'}=1;

And another SPECIAL NOTE: To be effective, your config plugin should run during filter(), not head().


With this sidewordz.story.html template:

<div class="story">
  <h4><a name="$fn" href="$url$path/$fn.default_flavour">$title</a></h4>
  ISBN: <code>$meta::sidewordz_isbn</code></br>
  Link: <a href="$meta::sidewordz_amazon">Amazon</a>
  $truncatez::body<br>
</div>

and this entry file (teeth.txt):

The Teeth of the Tiger
meta-sidewordz_isbn:0-425-19740-9
meta-sidewordz_amazon:http://amazon.com/some/damn/path

The bipolar world of Tom Clancy once again tilts from "doing what must be done," to "doing what feels good," as post-9/11 yuppies drop the bad guys like rocks, with mandated crew rest for fast cars, warm beer, and greasy food. The next generation of American aristocracy records its first cold-blooded kills while staying internally connected to humanity by pondering the everyday issues of "working sure is harder than the trust fund,"hey-I-like-this-Hummer, and "How come I'm not getting laid?"

produces $sidewordz::output of: (truncatez set to a max of 130 characters)

<div class="story">
 <h4><a name="tigerteeth" href="sample.net/entries/books/teeth.html">The Teeth of the Tiger</a></h4>
 ISBN: <code>0-425-19740-9</code></br>
 Link: <a href="http://amazon.com/some/damn/path">Amazon</a></br>
 The bipolar world of Tom Clancy once again tilts from "doing what must be done," to "doing what feels good," as post-9/11 yuppies...
</div>

Credits

This plugin is based on a blosxom list posting.

Bugs

sidewordz is very much a work in progress, and p'bly needs your loving strokes to grow big and strong. Please address bug reports and comments to the Blosxom mailing list:
http://www.yahoogroups.com/group/blosxom

 

DOWNLOAD sidewordz 0.4