/ 
Posy-Plugin-Categories-0.64
/ Posy::Plugin::Categories

NAME

Posy::Plugin::Categories - Posy plugin to give category links.

VERSION

This describes version 0.64 of Posy::Plugin::Categories.

SYNOPSIS

    @plugins = qw(Posy::Core
		  Posy::Plugin::TextTemplate
		  ...
		  Posy::Plugin::Categories);

DESCRIPTION

This provides category-based (lists of) links: a category tree which can be used as a site map, contains a list of lists of all the categories; and a breadcrumb list which provides a "breadcrumb trail" list.

These methods can be called from within templates if one is using the TextTemplate plugin.

For example:

[==Posy->category_tree()==]

Configuration

This expects configuration settings in the $self->{config} hash, which, in the default Posy setup, can be defined in the main "config" file in the config directory.

categories_hide

Default value for categories not to show in the breadcrumb or category tree. The 'hide' value can also be set in the actual call as well, which will override the config value.

categories_labels

Optional hash which can only be set if one also has Posy::Plugin::YamlConfig or something similar.

By default, this uses prettified names of the category directories to use as labels. This hash provides replacement labels to use if you prefer longer, more descriptive names.

For example:

    category_labels:
	b7: "Blake's 7"
	b5: "Babylon 5"

Helper Methods

Methods which can be called from elsewhere.

category_tree

    $links = $self->category_tree(
	tree_head=>'<ul>',
	tree_foot=>'</ul>',
	subtree_head=>'<ul>',
	subtree_foot=>'</ul>',
	pre_item=>'<li>',
	post_item=>'</li>'
	pre_active_item=>'<em>',
	post_active_item=>'</em>',
	item_sep=>"\n",
	tree_sep=>"\n",
	use_count=>1,
	hide=>$hide_regex,
	root=>'Home');

Generates a list (of lists) of links of all the categories.

This provides a large number of options to customize the appearance of the list. The default setup is for a simple UL list, but setting the options can enable you to make it something other than a list altogether, or add in CSS styles or classes to make it look just like you want.

If HTTP_REFERRER exists, this will also flag a "you were here" in the list.

Options:

tree_head

The string to prepend the top-level tree with.

tree_foot

The string to append to the top-level tree.

subtree_head

The string to prepend to lower-level trees.

subtree_foot

The string to append to lower-level trees.

pre_item

The string to put in front of each item.

post_item

The string to append to each item.

pre_active_item

An additional string to put in front of each "active" item, after pre_item.

The active item is the category which is the current category if the current path is a category path. A regular item will have a link to that category; the active category doesn't, because we're already there.

post_active_item

An additional string to append to each active item, before post_item.

item_sep

The string to separate each item.

tree_sep

The string to separate each tree.

hide

If the category matches this string, don't include it in the tree. (defaults to 'categories_hide' config value)

labels

Hash containing replacement labels for one or more categories. (defaults to 'categories_labels' config value)

use_count

If true, display the count of entries for that category next to that category.

root

What label should we give the "root" category? (default: Home)

you_were_here

String which points to the directory we just came from. (default: '&lt;-- you were here')

    $links = $self->breadcrumb(
	tree_head=>'<ul>',
	tree_foot=>'</ul>',
	subtree_head=>'<ul>',
	subtree_foot=>'</ul>',
	pre_item=>'<li>',
	post_item=>'</li>'
	pre_active_item=>'<em>',
	post_active_item=>'</em>',
	item_sep=>"\n",
	tree_sep=>"\n",
	root=>'Home');

Generates a list (of lists) of links of the categories above (and just below) the current path.

This provides a large number of options to customize the appearance of the list. The default setup is for a simple UL list, but setting the options can enable you to make it something other than a list altogether, or add in CSS styles or classes to make it look just like you want.

Options:

tree_head

The string to prepend the top-level tree with.

tree_foot

The string to append to the top-level tree.

subtree_head

The string to prepend to lower-level trees.

subtree_foot

The string to append to lower-level trees.

last_subtree_head

The string to prepend to the last (lowest) tree.

last_subtree_foot

The string to append to the last (lowest) tree.

pre_item

The string to put in front of each item.

post_item

The string to append to each item.

pre_active_item

An additional string to put in front of each "active" item, after pre_item.

The active item is the category which is the current category if the current path is a category path. A regular item will have a link to that category; the active category doesn't, because we're already there.

post_active_item

An additional string to append to each active item, before post_item.

item_sep

The string to separate each item.

tree_sep

The string to separate each tree.

hide

If the category matches this string, don't include it in the breadcrumb. (defaults to 'categories_hide' config value)

labels

Hash containing replacement labels for one or more categories. (defaults to 'categories_labels' config value)

root

What label should we give the "root" category? (default: Home)

start_depth

The depth (from the root) at which to start the tree. The default is zero, which means start from the root. Most of the time that is just what one wants.

end_depth

The depth (from the root) at which to end the tree. The default is the depth of the current path ($path_depth) plus one. This allows one to have a breadcrumb path which looks below the current directory, as well as above it. If one wishes to just show the current directory and those above it, then set this option to $path_depth.

Private Methods

_build_lol

Build a list of lists of categories.

_traverse_lol

Traverse the list of lists of categories to produce links.

INSTALLATION

Installation needs will vary depending on the particular setup a person has.

Administrator, Automatic

If you are the administrator of the system, then the dead simple method of installing the modules is to use the CPAN or CPANPLUS system.

cpanp -i Posy::Plugin::Categories

This will install this plugin in the usual places where modules get installed when one is using CPAN(PLUS).

Administrator, By Hand

If you are the administrator of the system, but don't wish to use the CPAN(PLUS) method, then this is for you. Take the *.tar.gz file and untar it in a suitable directory.

To install this module, run the following commands:

perl Build.PL
./Build
./Build test
./Build install

Or, if you're on a platform (like DOS or Windows) that doesn't like the "./" notation, you can do this:

perl Build.PL
perl Build
perl Build test
perl Build install

User With Shell Access

If you are a user on a system, and don't have root/administrator access, you need to install Posy somewhere other than the default place (since you don't have access to it). However, if you have shell access to the system, then you can install it in your home directory.

Say your home directory is "/home/fred", and you want to install the modules into a subdirectory called "perl".

Download the *.tar.gz file and untar it in a suitable directory.

perl Build.PL --install_base /home/fred/perl
./Build
./Build test
./Build install

This will install the files underneath /home/fred/perl.

You will then need to make sure that you alter the PERL5LIB variable to find the modules, and the PATH variable to find the scripts (posy_one, posy_static).

Therefore you will need to change: your path, to include /home/fred/perl/script (where the script will be)

PATH=/home/fred/perl/script:${PATH}

the PERL5LIB variable to add /home/fred/perl/lib

PERL5LIB=/home/fred/perl/lib:${PERL5LIB}

REQUIRES

Module::Build
Posy
Posy::Core
Posy::Plugin::TextTemplate

Test::More

SEE ALSO

perl(1). Posy

BUGS

Please report any bugs or feature requests to the author.

AUTHOR

Kathryn Andersen (RUBYKAT)
perlkat AT katspace dot com
http://www.katspace.com

COPYRIGHT AND LICENCE

Copyright (c) 2004-2005 by Kathryn Andersen

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.