# Blosxom Plugin: categoryz
# Author(s): Stu MacKenzie
#            based on categorytree plugin (v1.7) by Eric Davis
# Version: v0.62  2005-04-06 (6f)
# Documentation: See the bottom of this file or type: perldoc categoryz

package categoryz;

# = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
#
#  Configuration Section
#
# = = = = = = = = = = = = = = = =
#
# Style bits --
#       The directory structure of your entries is displayed as a series of
#       nested unordered lists. To control the appearance of these lists,
#       you'll probably want to use CSS definitions. The style_bits variables
#       hold style info you want to include in the <ul> and <li>tags.
#
#       For example, the plugin comes preconfigured to assign its lists
#       to the "categoryz" class, and its items to "categoryz_item" with:
#           my $list_style_bits = qq{class="categoryz"};
#           my $item_style_bits = qq{class="categoryz_item"};
#       You could also supply your own class names, such as:
#           my $list_style_bits = qq{class="myliststyle"};
#       Or you could supply "inline" style definitions such as:
#           my $list_style_bits = qq{style="margin:0px 0px 0px 1em;list-style-type:disc;"};
#       Or you could supply no style info:
#           my $list_style_bits = qq{};
#       Etc.
#
#      Enter your list style info between the {} below:
  my $list_style_bits = qq{class="categoryz"};
#      Enter your list item style info between the {} below:
  my $item_style_bits = qq{class="categoryz_item"};
#
#
# Entries counts --
#      Should each category item show the number of entries it contains?
#       0 = no; 1 = yes
  my $show_counts = 1;
#
#      What, if any, characters should preceed/follow the count?
#       Note: the count will *always* be preceeded by a space,
#       even if $pre_count is empty
#      Enter characters between the {} below:
#       (To use braces, enter "\{" and "\}" -- no quotes)
  my $pre_count_bits  = qq{(};
  my $post_count_bits = qq{)};
#
#
# Category view flavour --
#       What flavour should be used in category links?
#       (Leave blank to use the current blosxom flavour)
  $cat_flavour = qq{}
        unless defined $cat_flavour;
#
#
# Skip leading directories --
#       How many "top" directories should be trimmed from the tree?
#       e.g.  with:                 $skip_top_dirs = 0:   $skip_top_dirs = 1:
#             --------------------  --------------------  --------------------
#             /docs                  docs (30)
#             /docs/books                books (6)         books (6)
#             /docs/movies               movies (14)       movies (14)
#             /docs/movies/noire             noire (3)         noire (3)
#             /docs/movies/scifi             scifi (7)         scifi (7)
#             /special_stuff         special_stuff (10)
#
#       Enter 0 to trim no leading items  (normal is 0)
  $skip_top_dirs = 1
        unless defined $skip_top_dirs;
# = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

$display;                           # call results with: $categoryz::display

use File::Basename;
use strict;
use vars qw{ $display $cat_flavour $skip_top_dirs };

sub start {
  1;
}

# if there's something in style_bits, prepend a single space
$list_style_bits =~ s/^\s*/ /;  $item_style_bits =~ s/^\s*/ /;

# if a flavour's been specified, prepend it
#$cat_flavour and $cat_flavour =~ s|^|/index.|;
$cat_flavour and $cat_flavour =~ s|^|?flav=|;

sub head {
  my ($pkg, $cur_dir, $head_ref) = @_;
  #my ($pkg, $files_ref) = @_;
  my $files_ref = \%blosxom::files;
  my %count;
  my @tree;
  my ($i, $tmp, $dir, $skip_ref, $ref, $level, $new_level, $list_tag, $item_tag);

  foreach $dir (keys %$files_ref) {
    $dir =~ s/$blosxom::datadir//;  # trim leading datadir
    $dir = dirname($dir);           # trim trailing filename
                                    # count and remember each item in path
    $count{$dir}+=1 and $dir = dirname($dir) while $dir !~ m/^\/$/;
  }
  @tree = sort keys %count;

  $level = 0;
  $new_level = $level;
  $list_tag = 'ul';
  $display .= qq{<$list_tag$list_style_bits>\n};
  $item_tag = 'li';
  
  foreach $dir (@tree) {
    $skip_ref = $ref = $dir;
    $skip_ref =~ m/(\/.+)*/;        # skip leading directories
    (($1 =~ tr!/!!) <= $skip_top_dirs) and next;
    
    $dir =~  s!^/!!;
    $dir =~ s!(.+/)*!!;
    $new_level = $1 =~ tr!/!!;
    $new_level -= $skip_top_dirs;
    
    if ($new_level > $level) {                 # open a new list, or
      for (1..($new_level - $level)) {
        $display .= qq{<$list_tag$list_style_bits>\n};
      }
      $level = $new_level;
    } elsif ($new_level < $level) {            # close the current list, or
      for (1..($level - $new_level)) {
        $display .= qq{</$list_tag>\n};
      }
      $level = $new_level;
    }                                          # add a new list item
    $display .= qq{<$item_tag$item_style_bits><a href="$blosxom::url$ref$cat_flavour">$dir</a>};
    $show_counts and $display .= qq{ $pre_count_bits$count{$ref}$post_count_bits};
    $display .= qq{</$item_tag>\n};
  }
  
  for (0..$level) {                            # close any open lists
    $display .= qq{</$list_tag>\n};
  }

  1;
}

1;

__END__


=head1 NAME

Blosxom Plug-in: categoryz


=head1 SYNOPSIS

categoryz produces a hierarchical tree of all the directories 
("categories") in your datadir that contain entries; the tree is 
composed of nested unordered lists. Each list item is a link to 
that category's view. Optionally, each directory item can display 
the number of entries it contains.


=head1 INSTALLATION

Open the "categoryz" file and answer the questions in CONFIGURATION 
SECTION. Upload or drop the "categoryz" file into your blosxom plugins 
folder. Blog on.


=head1 CONFIGURATION

The plugin comes preconfigured for most blosxom installs; just drop it 
into your plugins folder and blog on. The following values can be changed 
to alter categoryz's behavior:

Style bits -- as shipped, categoryz assigns its lists and list items 
to the "categoryz" and "categoryz_item" CSS classes, respectively. 
These assignments can be changed to whatever you wish, including empty.

Entries counts -- as shipped, the plugin shows the number of entries 
(the count) for each category list item; each count is surrounded by 
parentheses. To suppress the count, set $show_counts to 0 (zero). To 
change the characters that surround the count, enter values into the 
$pre_count_bits and $post_count_bits variables.

Category view flavour -- as shipped, the category URLs composed by the 
plugin contain no flavour information; whatever flavour is specified in 
blosxom's configuration section or by the config plugin will be used 
when a category view is opened. To specify a flavour of your choice for 
category views, enter it into the $cat_flavour variable. $cat_flavour is 
available to the config plugin.

(Category view flavour is set by setting the "flav" parameter in URLs, 
as in "/category?flav=flavour". If you dig around in the code, you'll 
find a spot to use "/index.flavour" instead.)

Skip leading directories --
The $skip_top_dirs variable specifies the number of "top" directories 
to exclude from the category list. For example, your datadir might have 
one or more top-level directories that hold files for blosxom, but not 
necessarily for your blog. Set $skip_top_dirs to 1 the number of "top" directories


=head1 USAGE

Add "$categoryz::display" (no quotes) to a head or foot flavour to 
display the list generated by the plugin. To take advantage of the CSS 
class identifiers "categoryz" and "categoryz_item" you will, of course, 
have to add definitions to your style sheet or head flavour. 

For the most-complete listing of your blog's categories, the plugin 
should run as early as possible. To accurately reflect modifications 
to your entries list, run the plugin as late as possible.


=head1 NOTES

Inspired by a post to the blosxom list from Steph Smith; adapted from the 
"categorytree" plugin v1.7 by Eric Davis.


=head1 VERSION

2005-04-06 (v0.62)  - run in head() to get filter()-ed file data
2005-01-18 (v0.6)   - added skip_top_dirs; cleanup
2005-01-14 (v0.5)   - it's alive


=head1 LICENSE

this Blosxom Plug-in
Copyright 2005, Stu MacKenzie

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.