# Blosxom Plugin: crumz3
# Author: Stu MacKenzie
# Based on "breadcrumbs" plugin by: Rael Dornfest <rael@oreilly.com> 
# Version: 2004-05-07 (v0.1a)
# More notes at the bottom of this file or type: perldoc blox

package Blosxom::Plugin::crumz;

# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
#
#  Configuration Section
#
# # # # # # # # # # # # # # # # #
#
#  What divider between path items in the link trail?
#  ex: $divider = ' / ';
  my $crumz_divider = " > ";
#
#  Should the trail start with a link back to the blog?
#   Specify link text for a "home" link back to $blosxom::url, 
#   or leave blank to exclude a home link
#  ex: $home = 'home';
  my $home = '';
#
#  How many leading items should be trimmed?
#   (excluding home link, if any)
#   Enter 0 to trim no leading items
#  ex: $trim = 1;
  my $trim = 0;
#
#  Show file name in the link trail?
#   Enter 1 to include filename in the trail; 
#   enter 0 to ignore the filename.
#  ex: $show_filename = 0;
  my $show_filename = 1;
#
#  Should the last item in the trail be linked?
#   0 = no; 1 = yes
#  ex: $link_last_item = 0;
  my $link_last_item = 0;
#
#  What flavour should be used in link urls? 
#  (leave blank to let Blosxom pick the flavour)
#  ex: $flavor = '';
  my $flavor = 'html';
#
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #

# call $Plugin::crumz::crumz in your story template
my $crumz;

sub run {
  my $self = shift;
  my $path = $self->{state}->{current_entry}->{path};
  my $filename = $self->{state}->{current_entry}->{fn};
  my $url = $self->{request}->{url};

  # no path, no crumbs, no point
  $path or return 0;
  
  # append filename as called
  $show_filename and $path .= "$filename";

  # trim leading /
  $path =~ s/^\///;

  # get a flavour
  $flavor or $flavor=$self->{request}->{flavour};

 # get a divider
  $crumz_divider !~ m/^\s*$/ or $crumz_divider=" > ";

## HUH -- doing this with x ? y : z works, but appends a digit 
## equal to the depth of $path...weird
  # step through $path, building an array of links and/or text
  my(@p, $p);
  foreach ( split /\//, $path ) {
    $p .= "/$_";
    if ($p ne "/$path") {
      push @p, qq{<a href="$url$p/">$_</a>}
    } else {
      if ($link_last_item) {
        push @p, qq{<a href="$url$p.$flavor">$_</a>}
      } else {
        push @p, qq{$_}
      }
    }
  }

  # trim items as called
  ($trim>0) and @p = splice(@p,$trim);

  # build a string with dividers
  $crumz = join $crumz_divider, @p;

  # prepend home link as called
  $home and $crumz =~ s/^/<a href="$url\/index.$flavor">$home<\/a>$crumz_divider/;
  
  $self->{state}->{current_entry}->{Plugin}->{crumz}->{crumz} = $crumz;

  return 1;
}

1;

__END__

=head1 NAME

Blosxom Plug-in: crumz3

=head1 SYNOPSIS

Generates a trail of links along the current story's path in $Plugin::crumz::crumz

ex: a/b/c/d becomes 
<a href="/a">a</a> > <a href="/a/b">b</a> > <a href="/a/b/c">c</a> > > <a href="/a/b/c/d">d</a> >

=head1 INSTALLATION AND CONFIGURATION

To install crumz3:
  First, drop this file into the Blosxom3 plugins folder;
  Second, rename this file to: crumz3.pm
  Third, add one line to your "handlers.entry" file -- 
    somewhere _between_ 'Blosxom::read_entry_file' and 'Blosxom::shortcut_max_entries'
    add 'Blosxom::Plugin::crumz::run' (no quotes)
    NOTE: make sure you save the handlers.entry file with 'nix lineneds, not Mac returns
  Fourth, it oughta work.


=head1 CONFIGURATION

Optionally begin each trail with a link back to the blog "home."  
$home becomes the link text; leave it blank to turn off the link 
to home. This link is hardcoded to "$blosxom::url/index.$flavor"
(see below for setting $flavor)

Optionally trim leading elements from the trail (excluding Home link, 
if any) with an integer greater than 0 in $trim

Optionally set a flavour for the links; leave $flavor empty to use 
the current Blosxom flavour in $blosxom::flavour

=head1 VERSION

2004-05-07 (v0.1a) - it's alive

=head1 LICENSE

this Blosxom Plug-in
Copyright 2004, Stu MacKenzie

This license is the same as that of Blosxom's at the time of release (3.0+3i).