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 crumz 0.88.
To return to the Downloads page, click the button at left.
The crumz plugin generates a trail of links along each story's path, which you can add to your stories by calling the
$crumz::crumz variable in your story flavour files (templates). For instance, an entry file located at
hither/thither/anon/story.txt will produce a trail of links similar to:
crumz has options to let you: generate links that are path-based, date-based, or context-sensitive to the blosxom URL; set the divider between links; add a link back to your main blog page; set the "depth" of the link trail by trimming leading or trailing path items; add the entry's filename to the end of the link trail; set whether the last item in the trail is linked or just plain text; and set the default flavours to call in the home, directory, and entry links.
Configuring & Installing crumz
You're not required to configure anything — crumz produces link trails "right out of the box" as soon as you add
$crumz::crumz to your story template(s). Configuration and flavours let you customize your crumz to the exact look and performance you want.
Item Divider : whatever you enter into
$crumz_divider becomes the divider between link trail items. If you leave
$crumz_divider empty, crumz uses "
> " as a default. (Note: crumz treats a divider made up of spaces as being empty; use a non-breaking space entity (
) to make a divider composed of only spaces.)
Home link : entering a value into
$home tells crumz to begin each trail with a link back to your blog's "home," with
$home becoming the link text -- leave it blank to turn off the link.
Show filename : entering a 1 into
$show_filename tells crumz to add the entry file's name to the link trail; entering a 0 tells crumz to ignore the file name. (The file extension will be stripped from the file name.)
Link Last Item : entering a 1 into
$link_last_item tells crumz to give the last item in the trail a link; entering a 0 tells crumz to display the last item as plain text. Depending on your
$show_filename setting, this will affect either a category name or a file name.
Path-based or Date-based Link URLs : crumz links can be set to always be path-based; or to always be date-based; or to match whatever is in the blosxom URL that called the current page. When
$match_date_based_url is set to 1, a date-based blosxom URL will result in date-based crumz links, while a path-based blosxom URL will result in path-based crumz links.
$always_date_based is set to 1, crumz links will always be date-based. (And so, setting both
$always_date_based to 0 results in links always being path-based.)
$restrict_dates_to_category variable lets you set whether date-based links point to the whole blog, or to just the story's category. For example, consider an entry posted April 15, 2005 to the
/perl/rants category; with
$restrict_dates_to_category set to
0, a link would look something like this:
$restrict_dates_to_category set to
1, a link would look something like this:
Trim Leading Items : giving
$trim_start any integer value greater than zero tells crumz to trim that many items from the front of the link trail (the Home link, if specified, is left intact). Thus, with
$trim_start = 1,
$trim_start = 2,
Trim Trailing Items : giving
$trim_after any integer value greater than zero tells crumz to keep that many items at the front of the link trail, and trim all the rest (the entry link, if specified, is left intact). Thus, with
$trim_after = 3,
$trim_lead_items = 2,
Show Only Last Directory : giving
$last_dir_only any integer value greater than zero tells crumz to trim all items but the last directory from the link trail (the home and entry links, if specified, are left intact). Note: using $last_dir_only disables both $trim_start and $trim_after. With
$trim_after = 3,
Link Flavours : when
$home_flavor = '', the current Blosxom flavour is specified in the home link (if any); any other value is treated as a valid flavour file extension (e.g. 'html', 'rss', 'index', etc.).
$dir_flavor = '', the current Blosxom flavour is specified in directory links ; any other value is treated as a valid flavour file extension (e.g. 'html', 'rss', 'index', etc.).
$entry_flavor = '', the current Blosxom flavour is specified in the entry file link (if any); any other value is treated as a valid flavour file extension (e.g. 'html', 'rss', 'index', etc.).
To install crumz, just drop the configured file into your Blosxom plugins folder. That's it. Add a call to
$crumz::crumz in your story flavour files, and away you go.
The links that crumz produces are assigned to the css class
crumz; other than that, they're just plain links. To give the links position or further styling, you'll need some markup — this can be inserted in either your story template, or in a crumz flavour file. For instance, let's say you want to place your crumz inside a positioning DIV. You could just add the relevant bits to your story template, like this:
<h4>$mo $da, $yr</h4> <div class="crumz_block">$crumz::crumz</div> <h1><a name="$fn" href="$url$path/$fn.html">$title</a></h1> $body
Or, you could add those bits to a crumz flavour file and just add
$crumz::crumz to your story template. Your
crumz.story.html file would look like this:
and your story template would simply be:
<h4>$mo $da, $yr</h4> $crumz::crumz <h1><a name="$fn" href="$url$path/$fn.html">$title</a></h1> $body
If used, crumz flavour files must be named "
crumz.story.flavour_name" (no quotes), with the extension matching the desired flavour. Flavour files must reside directly inside your datadir; e.g.
/datadir/crumz.html. (Users of the flavourdir plugin should keep their crumz flavour files in the top level of their
To get the benefits of flavours without the bother of creating flavour files, you can also add template info into the DATA section of the plugin, in the format:
flavour_name story flavour_info
where flavour_name is a flavour name (e.g. html, rss, etc.), followed by a space, followed by the word "story" (no quotes), followed by a space, followed by the flavour info. For our previous example, the template info would look like this:
__DATA__ html story <div class="crumz_block">$crumz::crumz</div> __END__
(To make a DATA template work for all flavours, set the first word to "error" (no quotes); e.g.
error crumz <div class="crumz_block">$crumz::crumz</div>.)
To use crumz, find a spot to call the
$crumz::crumz variable in your story flavour files; then play with the config vars until you like what you see. All crumz settings are available to the config plugin. Using config files, flavour templates, and crumz settings in concert, you can tailor your breadcrumbs all across your blog.
Here are some of the finer points of crumz operation --
- No matter how whacky your settings are (like,
$trim_start = 99;-), the plugin will always return at least a non-breaking space (
). This ensures that any surrounding markup (such as a positioning DIV) won't freak out by receiving nothing.
$trim_aftercan be set "too high" (as in
$trim_after = 99), and perl won't freak out.
Here's an example of using crumz --
Let's say a blosxom datadir looks like this:
/blosxom /entries /life <-- entry files in here /liberty <-- entry files in here /happy pursuits <-- entry files in here /flavours /wipwith numerous subdirectories inside the
/happy pursuitscategories; there are no entry files in the top level of
/entries. The blog uses
htmlas its default flavour; when viewing categories, a
sliceflavour is used; individual entries are viewed with an
entryflavour; a special
indexflavour is also used.
When users "normally" open the blog — let's say it's at:
sample.net/blosxom.cgi — they are presented with a page of 10 stories in the default flavour, via Blosxom settings. The default html story template calls
$crumz::crumz to give each story a link trail composed of a link to an "index" page (
$home = "index") using the special index flavour (
$home_flavor); directory links using the slice flavor (
$dir_flavor); entry file name (
$show_filename = 1); and an entry flavor (
$entry_flavor) of entry via crumz settings. The outer, containing folder
/entries is trimmed from all link trails by setting
$trim_start = 1. With
$link_last_item = 1, all the bits in link trails are clickable.
Clicking a trail's index link opens a page produced by the index flavour templates and a
config.index file atop the datadir: a listing of up to 999 stories, showing only date, title, and crumz link trail. The
config.index file also sets
$crumz::index_flavor = ''; (empty; current blosxom flavour, which will default to html) and
$crumz::home = 'blog' to allow users to easily return to a default main blog page just like they started on.
Clicking a directory link opens the category using the slice flavour, which conveys information specific to browsing categories. Clicking an entry link on category or index index pages opens the individual story with the entry flavour, conveying information specific to reading indivdual entries. A
config.html file atop datadir sets
$crumz::link_last_item = 0 (off), which displays the current entry's filename as plain text.
This plugin is based on Rael's breadcrumbs plugin. crumz produces link trails for
story flavours; if you want link trails in your
head flavours, use breadcrumbs.