/ 
HTML-Menu-Hierarchical-0.13
River stage zero No dependents
/ HTML::Menu::Hierarchical

NAME

HTML::Menu::Hierarchical - HTML Hierarchical Menu Generator

SYNOPSIS

my $menu_obj =
    HTML::Menu::Hierarchical->new($conf, \&callback, $params);

my $html = $menu_obj->generateMenu($menu_item);

or

my $menu_obj =
    HTML::Menu::Hierarchical->new($conf, [ $obj, $method ]);

my $html = $menu_obj->generateMenu($menu_item);

or

my $menu_obj =
    HTML::Menu::Hierarchical->new($conf, $std_callback_name);

my $html = $menu_obj->generateMenu($menu_item);

In the first case, the callback is a function.  In the second,
the callback is a method called on the given object.  In the
third example, the callback is the name of a standard callback
defined by HTML::Menu::Hierarchical itself (see the section on
callback functions/methods).

The $conf parameter is a navigation configuration data structure
(described below).

The $params parameter is an optional hash reference containing
parameters pertaining to the menu as a whole.  Recognized
parameters are:
first_with_url
If this is set to a true value and you are using the 'url'
field in the info hash (see below) in the configuration to
specify the url for the menu item, then if a menu item is
chosen that does not have a url configured, the url for that
menu item will be changed to the url of the first child menu
item that has a url configured.  This works by looking at the
items first child, then at that child's first child, and so
on.  It does not look at the second child.
open_all
This has the same effect as the open_all parameter in the
menu configuration structure mentioned below, except that it
affects the entire menu hierarchy.
old_style_url
When using the utilities urlEncodeVars() and addArgsToUrl(),
this parameter controls which separator is used to separate
key/value pairs in the generated query string.  Setting
old_style_url to a true value will cause an ampersand ('&')
to be used as the separator.
new_style_url
When using the utilities urlEncodeVars() and addArgsToUrl(),
this parameter controls which separator is used to separate
key/value pairs in the generated query string.  Setting
new_style_url to a true value will cause a semicolon (';') to
be used as the separator, as recommended by the W3C.  This
will become the default in a later release.

DESCRIPTION

HTML::Menu::Hierarchical provides a way to easily generate a
hierarchical HTML menu without forcing a specific layout.
All output is provided by your own callbacks (subroutine
refs) and your own navigation configuration.

configuration data structure

A navigation configuration is a reference to an array whose
elements are hashrefs.  Each hash contains configuration
information for one menu item and its children, if any.
Consider the following example:

my $conf = [
            { name => 'top_button_1',
              info => { text => 'Top Level Button 1',
                        url => '/'
                      },
              open => 1, # force this item's children to be displayed
              children => [
                           { name => 'button_1_level_2',
                             info => { text => "Child 1 of Button 1",
                                       url => '/child1.cgi'
                                     },
                           },
                           ]
            },

            { name => 'top_button_2',
              info => { text => 'Top Level Button 2',
                        url => '/top2.cgi'
                      },
              callback => [ $obj, 'my_callback' ]
            },
               
           ];

In each hash, the 'name' parameter should correspond to the
$menu_item parameter passed to the generateMenu() method.  This
is how the module computes which menu item is selected.  This is
generally passed via a CGI parameter, which can be tacked onto
the end of the url in your callback function.  Note that this
parameter must be unique among all the array entries.
Otherwise, the module will not be able to decide which menu item
is selected.

The value of the 'info' parameter is available to your callback
function via the getInfo() method called on the
HTML::Menu::Hierarchical::ItemInfo object passed to the callback
function.  In the above example, the 'info' parameter contains
text to be displayed as the menu item, and a url the user is
sent to when clicking on the menu item.

The 'children' parameter is a reference to another array
containing configuration information for child menu items.  This
is where the Hierarchical part comes in.  There is no limit to
depth of the hierarchy (until you run out of RAM, anyway).

If a 'callback' parameter is specified that callback will be
used for that menu item instead of the global callback passed to
new().

An 'open' parameter can be specified to force an item's children
to be displayed.  This can be a scalar value that indicates true
or false.  Or it can be a subroutine reference that returns a
true or false value.  It can also be an array, in which case the
first element is expected to be an object, the second element
the name of a method to call on that object, and the rest of the
elements will be passed as arguments to the method.  If an
'open_all' parameter is passed, the current item and all items
under it in the hierarchy will be forced open.

callback functions/methods

Callback functions are passed a single parameter: an
HTML::Menu::Hierarchical::ItemInfo object.  See the
documentation on this object for available methods.  The
callback function should return the HTML necessary for the
corresponding menu item.

METHODS

new()

my $menu_obj = HTML::Menu::Hierarchical->new($conf, \&callback);

generateMenu($menu_item)

my $html = $menu_obj->generateMenu($menu_item);

$menu_item is the 'name' parameter of the selected item,
typically passed as a CGI parameter.

addChildConf($conf, $menu_item_name)

Adds another configuration tree into the current configuration
at the specified node (name of the menu item).

addChildConfToChildren($conf, $menu_item_name)

Like addChildConf(), except add this conf to the list of
children of the parent with name $menu_item_name.  If $conf is
an array, each element of the array will be added to the list of
children.

getSelectedItemInfo($menu_item)

Returns the ItemInfo object corresponding to the selected menu
item.

getSelectedPath($menu_item)

Returns an array of InfoItem objects representing the path from
the top level menu item to the selected menu item.

There are also underscore_separated versions of these methods.

E.g., unescapeHtml($html) becomes unescape_html($html)

EXAMPLES

See the scripts in the examples subdirectory for example usages.

See the documentation for HTML::Menu::Hierarchical::ItemInfo for
methods available via the $info_obj parameter passed to the
menu_callback function below.

    sub menu_callback { my ($info_obj) = @_; my $info_hash = $info_obj->getInfo; my $level = $info_obj->getLevel;

    my $text = $$info_hash{text};
$text = ' ' if $text eq '';
my $item_arg = $info_obj->getName;

# Add a cgi parameter m_i to url so we know which menu
# item was chosen
my $url = $info_obj->addArgsToUrl($$info_hash{url},
                                  { m_i => $item_arg });

my $dpy_text = $info_obj->isSelected ? "<$text&gt" : $text;
my $spacer = '  ' x $level;
my $str = qq{<tr>\n};
$str .= qq{<td bgcolor="#cccc88"><a href="$url">};
$str .= $spacer . $dpy_text;
$str .= qq{</a></td>};
$str .= qq{</tr>\n};
return $str;
}

BUGS

Please send bug reports/feature requests to don@owensnet.com.

There are currently no checks for loops in the configuration
data structure passed to the module.

AUTHOR

Don Owens <don@owensnet.com>

COPYRIGHT

Copyright (c) 2003 Don Owens

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

VERSION

0.13