Iris and I must ride the Ferris wheel

Categories has been updated.

User-visible Interesting Changes, in rough order by interestingness:

• new $indent template variable, which is the contents of the flavour file 'indent', repeated N times, where N is the depth of the current category
• new template variable "$prettydir", is the name of the category with spaces added to CamelCaps and instead of underlines in underlined_names.
• The top-level directory is now called "Root" by default, not "/", and it's configurable
• uses the built-in templating system, including any template plugin that's installed
• variables in templates can be interpolated with ${name} as well as $name
• cached layouts are keyed based on flavour, so if you have template files that vary by flavour it will actually work now
• cache is only enabled if the available Storable supports lock_retrieve
• the cache is flushed every time a story is added, not every time the timestamp of the latest file changes; if caching is enabled, the category list (usually) now shows all the categories even if a filtering plugin (such as a search system) has reduced the number of visible files.
• the $story_count_commulative configuration variable is now spelt $story_count_cumulative, to match the actual english language. Attempts to get enlish to change to match the plugin were unsuccessful.
• requires Blosxom 2.0rc1 2.0rc2 or newer
• the default templates are in the 'error' flavour rather than 'html', so they're used for any flavours that don't override them (the same effect was achieved a different way in 0+4i)

Thanks to:

• Jason Hoffman, prodding me into XHTML validation
• Robert Hahn, for the directory-name prettification
• Colin Eric Johnson, for an HTML validation note
• Earle Martin, HTML validation note

Things I'd like to be able to do, but can't reasonably without Blosxom changes:

• use the built-in interpolation system, including any interpolate plugin that's installed

To install:

1. download and unzip the plugin.
2. Copy it to your plugins directory. Make sure it's world-readable.
3. Modify a head or foot file to include $categories::categories or $categories::breadcrumbs
4. Try it out — load your blog in your browser. If you see a category tree, great!
5. Look at your error log. Verify you have an 'enabled' line.
6. If you're wanting to verify caching is working, load the page again, and now look for an error log line "calendar debug 1: Using cached state"
7. Once you're satisfied it's working, edit the $debug_level configuration variable to 0. There are a couple other configuration variables you may wish to change, too.
8. Drop me a note to let me know you're using it; if you're having problems, let me know and I might be able to help. If everything's working okay, please let me know that, too.

Molelog is running this with some customized templates.

categories.breadcrumb_between_child.html:

|​

categories.head.html:

<form name="cat" method="get" action="$url"> 
<!-- XXX any way to do this w/o js? -->
<script type="text/javascript">
function gotocat() {
 location = document.cat.cat.options[document.cat.cat.selectedIndex].value;
}
</script>
<select name="cat" onchange="gotocat()">

categories.indent.html:

   

categories.dir_head.html:

<option value="$url/index.html">
  $indent$prettydir /
</option>

categories.this_dir_head.html:

<option selected value="$url/index.$blosxom::flavour">
  $indent$prettydir /
</option>

categories.foot.html:

</select></form>

categories.dir_foot.html, categories.subtree_head.html, categories.subtree_foot.html, categories.this_dir_head.html, and categories.this_dir_foot.html are all empty.

Update: There are newer versions available; please use the newest version unless you have a particular reason not to.

Update: Minor bug in first 0+3i release; if you've already downloaded and are using the breadcrumbs, please download again, install this one, and remove your cache ($plugin_state_dir/.categories.cache). The original 0+3i didn't close the breadcrumb <div>. Thanks to Taper Wickel for the bug report.

Categories has been updated. Changes:

• New variable available to templates $categories::breadcrumbs; this is very similar to (and inspired by) Rael's breadcrumbs plugin; the only major difference is that this one includes a display of the direct children of the current category (minor difference: it also includes a 'Root' item at the head). If you don't want the children included, and aren't using $categories::categories, use Rael's plugin instead — it's quite a bit more efficient


• Some of the class names may have changed; if you've customized a stylesheet, you'll need to update it. Hopefully that won't happen again. (Yes, I said that last time, too. Turns out "_" isn't valid in class names.)


• If you have Storable installed, the tree data and partial results can be cached. It's not completely clear whether this is a win or not; it will depend on things like the number of stories, the speed of your disks relative to your CPU, and the like. If you're concerned about it, you should benchmark it on your own system.


• $categories::categories is now valid XHTML (thanks to Jason Hoffman)


• POD documentation is included

Things still to do:

• Keep better track of people who deserve thanks. Mea culpa.

To install:

1. download and unzip the plugin.


2. Copy it to your plugins directory. Make sure it's world-readable.


3. Modify a head or foot file to include $categories::categories or $categories::breadcrumbs
   
4. Try it out — load your blog in your browser. If you see a category tree, great!


5. Look at your error log. Verify you have some lines like the following:

   categories debug 1: start() called, enabled
   categories debug 1: filter() called, 233 files
   categories debug 1: head() called
   categories debug 1: head() exiting, length($categories) = 4957
   

   The numbers will be different, but the rest shouldn't be. If none of them are there, the plugin isn't getting invoked at all for some reason -- is it in the right place? Is it named "categories"? Is it readable?



6. If you're wanting to verify caching is working, load the page again, and now look for an error log line:

   categories debug 1: Using cached state
   



7. Once you're satisfied it's working, edit the $debug_level configuration variable to 0. There are a couple other configuration variables you may wish to change, too.


8. Drop me a note to let me know you're using it; if you're having problems, let me know and I might be able to help. If everything's working okay, please let me know that, too.

You can see a sample if you like. The stylesheet being used there is:

.categories {
	list-style-type:	none;
}
.categories ul {
	list-style-type:	none;
	padding-left:		1ex;
 	margin-left:		0;
	border-left:		1px dotted #cccccc;
}

Update: There are newer versions available; please use the newest version unless you have a particular reason not to.

Categories has been updated. Changes:

• The links link to the current flavour rather than the default flavour. This requires Blosxom 2.0 beta 2; on beta 1, the links are just broken.


• All the formatting is controlled via a templating system similar to Blosxom's. You probably won't feel the need to override the standard formatting (although you probably will want to add some stylesheeting), but you can if you want.


• Debugging output is available, and some is turned on by default. Once you have it working, turn it off or you'll fill your error logs with output you don't need.


• Some of the class names may have changed; if you've customized a stylesheet, you'll need to update it. Hopefully that won't happen again.

This is a minor upgrade. If you have 0-1i working and don't mind always linking to the default flavour, there's no need to change.

Things still to do (maybe):

• Write some real docs, include them in the plugin itself.

To install:

1. download and unzip the plugin.


2. Copy it to your plugins directory. Make sure it's world-readable.


3. Modify a head or foot file to include $categories::categories
   
4. Try it out — load your blog in your browser. If you see a category tree, great!


5. Look at your error log. Verify you have some lines like the following:

   categories debug 1: filter() called, 211 files
   categories debug 1: filter() exiting 84  dirs
   categories debug 1: head() called
   categories debug 1: head() exiting, length($categories) = 4707
   

   The numbers will be different, but the rest shouldn't be. If none of them are there, the plugin isn't getting invoked at all for some reason -- is it in the right place? Is it named "categories"? Is it readable?


6. Once you're satisfied it's working, edit the $debug_level configuration variable to 0. There are a couple other configuration variables you may wish to change, too.


7. Drop me a note to let me know you're using it; if you're having problems, let me know and I might be able to help. If everything's working okay, please let me know that, too.

You can see a sample if you like. The stylesheet being used there is:

.categories {
	list-style-type:	none;
}
.categories ul {
	list-style-type:	none;
	padding-left:		1ex;
	border-left:		1px dotted #cccccc;
}

Update: There are newer versions available; please use the newest version unless you have a particular reason not to.

Second plugin: categories

This builds a tree display structure of your category tree, like the one on my sidebar.

1. download it, and rename it "categories"


2. Stick it in your blosxoms plugin directory


3. Look at the configuration variables; You probably want to set @prune_dirs to the empty list, unless you have a very branchy tree.


4. Add "$categories::categories" to your head.$flavour or tail.$flavour file
   

Things that might be added to this at some point

• depth limits


• Showing more details 'near' the current location than further away in the tree


• more output formats?


• anything else wanted/needed?