Provided by: libhtml-linklist-perl_0.1701-3_all bug

NAME

       HTML::LinkList - Create a 'smart' list of HTML links.

VERSION

       version 0.1701

SYNOPSIS

           use HTML::LinkList qw(link_list);

           # default formatting
           my $html_links = link_list(current_url=>$url,
                                      urls=>\@links_in_order,
                                      labels=>\%labels,
                                      descriptions=>\%desc);

           # paragraph with ' :: ' separators
           my $html_links = link_list(current_url=>$url,
               urls=>\@links_in_order,
               labels=>\%labels,
               descriptions=>\%desc,
               links_head=>'<p>',
               links_foot=>'</p>',
               pre_item=>'',
               post_item=>''
               pre_active_item=>'<em>',
               post_active_item=>'</em>',
               item_sep=>" :: ");

           # multi-level list
           my $html_links = link_tree(
               current_url=>$url,
               link_tree=>\@list_of_lists,
               labels=>\%labels,
               descriptions=>\%desc);

DESCRIPTION

       This module contains a number of functions for taking sets of URLs and labels and creating
       suitably formatted HTML.  These links are "smart" because, if given the url of the current
       page, if any of the links in the list equal it, that item in the list will be formatted as
       a special label, not as a link; this is a Good Thing, since the user would be confused by
       clicking on a link back to the current page.

       While many website systems have plugins for "smart" navbars, they are specialized for that
       system only, and can't be reused elsewhere, forcing people to reinvent the wheel. I hereby
       present one wheel, free to be reused by anybody; just the simple functions, a backend,
       which can be plugged into whatever system you want.

       The default format for the HTML is to make an unordered list, but there are many options,
       enabling one to have a flatter layout with any separators you desire, or a more
       complicated list with differing formats for different levels.

       The "link_list" function uses a simple list of links -- good for a simple navbar.

       The "link_tree" function takes a set of nested links and makes the HTML for them -- good
       for making a table of contents, or a more complicated navbar.

       The "full_tree" function takes a list of paths and makes a full tree of all the pages and
       index-pages in those paths -- good for making a site map.

       The "breadcrumb_trail" function takes a url and makes a "breadcrumb trail" from it.

       The "nav_tree" function creates a set of nested links to be used as a multi-level navbar;
       one can give it a list of paths (as for full_tree) and it will only show the links related
       to the current URL.

FUNCTIONS

       To export a function, add it to the 'use' call.

           use HTML::LinkList qw(link_list);

       To export all functions do:

           use HTML::LinkList ':all';

   link_list
           $links = link_list(
               current_url=>$url,
               urls=>\@links_in_order,
               labels=>\%labels,
               descriptions=>\%desc,
               pre_desc=>' ',
               post_desc=>'',
               links_head=>'<ul>',
               links_foot=>'</ul>',
               pre_item=>'<li>',
               post_item=>'</li>'
               pre_active_item=>'<em>',
               post_active_item=>'</em>',
               item_sep=>"\n");

       Generates a simple list of links, from list of urls (and optional labels) taking into
       account of the "current" URL.

       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.

       Required:

       urls
           The urls in the order you want them displayed.  If this list is empty, then nothing
           will be generated.

       Options:

       current_url
           The link to the current page.  If one of the links equals this, then that is deemed to
           be the "active" link and is just displayed as a label rather than a link.

       descriptions
           Optional hash of descriptions, to put next to the links.  The keys of this hash are
           the urls.

       hide_ext
           If a site is hiding link extensions (such as using MultiViews with Apache) you may
           wish to hide the extensions (while using the full URLs to check various things).
           (default: 0 (false))

       item_sep
           String to put between items.

       labels
           A hash whose keys are links and whose values are labels.  These are the labels for the
           links; if no label is given, then the last part of the link is used for the label,
           with some formatting.

       links_head
           String to begin the list with.

       links_foot
           String to end the list with.

       pre_desc
           String to prepend to each description.

       post_desc
           String to append to each description.

       pre_item
           String to prepend to each item.

       post_item
           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 link which matches 'current_url'.

       pre_item_active
           INSTEAD of the "pre_item" string, use this string for active items

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

       prefix_url
           A prefix to prepend to all the links. (default: empty string)

   link_tree
           $links = link_tree(
               current_url=>$url,
               link_tree=>\@list_of_lists,
               labels=>\%labels,
               descriptions=>\%desc,
               pre_desc=>' ',
               post_desc=>'',
               links_head=>'<ul>',
               links_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",
               formats=>\%formats);

       Generates nested lists of links from a list of lists of links.  This is useful for things
       such as table-of-contents or site maps.

       By default, this will return UL lists, but this is highly configurable.

       Required:

       link_tree
           A list of lists of urls, in the order you want them displayed.  If a url is not in
           this list, it will not be displayed.

       Options:

       current_url
           The link to the current page.  If one of the links equals this, then that is deemed to
           be the "active" link and is just displayed as a label rather than a link.

       descriptions
           Optional hash of descriptions, to put next to the links.  The keys of this hash are
           the urls.

       exclude_root_parent
           If this is true, then the "current_parent" display options are not used for the "root"
           ("/") path, it isn't counted as a "parent" of the current_url.

       formats
           A reference to a hash containing advanced format settings. For example:

               my %formats = (
                          # level 1 and onwards
                          '1' => {
                          tree_head=>"<ol>",
                          tree_foot=>"</ol>\n",
                          },
                          # level 2 and onwards
                          '2' => {
                          tree_head=>"<ul>",
                          tree_foot=>"</ul>\n",
                          },
                          # level 3 and onwards
                          '3' => {
                          pre_item=>'(',
                          post_item=>')',
                          item_sep=>",\n",
                          tree_sep=>' -> ',
                          tree_head=>"<br/>\n",
                          tree_foot=>"",
                          }
                         );

           The formats hash enables you to control the formatting on a per-level basis.  Each key
           of the hash corresponds to a level-number; the sub-hashes contain format arguments
           which will apply from that level onwards.  If an argument isn't given in the sub-hash,
           then it will fall back to the previous level (or to the default, if there is no
           setting for that format-argument for a previous level).

           The only difference between the names of the arguments in the sub-hash and in the
           global format arguments is that instead of 'subtree_head' and subtree_foot' it uses
           'tree_head' and 'tree_foot'.

       hide_ext
           If a site is hiding link extensions (such as using MultiViews with Apache) you may
           wish to hide the extensions (while using the full URLs to check various things).
           (default: 0 (false))

       item_sep
           The string to separate each item.

       labels
           A hash whose keys are links and whose values are labels.  These are the labels for the
           links; if no label is given, then the last part of the link is used for the label,
           with some formatting.

       links_head
           The string to prepend the top-level tree with.  (default: <ul>)

       links_foot
           The string to append to the top-level tree.  (default: </ul>)

       pre_desc
           String to prepend to each description.

       post_desc
           String to append to each description.

       pre_item
           String to prepend to each item.  (default: <li>)

       post_item
           String to append to each item.  (default: </li>)

       pre_active_item
           An additional string to put in front of each "active" item, after pre_item.  The
           "active" item is the link which matches 'current_url'.  (default: <em>)

       pre_item_active
           INSTEAD of the "pre_item" string, use this string for active items

       post_active_item
           An additional string to append to each active item, before post_item.  (default:
           </em>)

       pre_current_parent
           An additional string to put in front of a link which is a parent of the 'current_url'
           link, after pre_item.

       pre_item_current_parent
           INSTEAD of the "pre_item" string, use this for links which are parents of the
           'current_url' link.

       post_current_parent
           An additional string to append to a link which is a parent of the 'current_url' link,
           before post_item.

       prefix_url
           A prefix to prepend to all the links. (default: empty string)

       subtree_head
           The string to prepend to lower-level trees.  (default: <ul>)

       subtree_foot
           The string to append to lower-level trees.  (default: </ul>)

       tree_sep
           The string to separate each tree.

   full_tree
           $links = full_tree(
               paths=>\@list_of_paths,
               labels=>\%labels,
               descriptions=>\%desc,
               hide=>$hide_regex,
               nohide=>$nohide_regex,
               start_depth=>0,
               end_depth=>0,
               top_level=>0,
               preserve_order=>0,
               preserve_paths=>0,
               ...
               );

       Given a set of paths this will generate a tree of links in the style of link_tree.   This
       will figure out all the intermediate paths and construct the nested structure for you,
       clustering parents and children together.

       The formatting options are as for "link_tree".

       Required:

       paths
           A reference to a list of paths: that is, URLs relative to the top of the site.

           For example, if the full URL is http://www.example.com/foo.html then the path is
           /foo.html

           If the full URL is http://www.example.com/~frednurk/foo.html then the path is
           /foo.html

           This does not require that every possible path be given; all the intermediate paths
           will be figured out from the list.

       Options:

       append_list
           Array of paths to append to the top-level links.  They are used as-is, and are not
           part of the processing done to the "paths" list of paths. (see "prepend_list")

       descriptions
           Optional hash of descriptions, to put next to the links.  The keys of this hash are
           the paths.

       end_depth
           End your tree at this depth.  If zero, then go all the way.  (see "start_depth")

       exclude_root_parent
           If this is true, then the "current_parent" display options are not used for the "root"
           ("/") path, it isn't counted as a "parent" of the current_url.

       hide
           If the path matches this string, don't include it in the tree.

       hide_ext
           If a site is hiding link extensions (such as using MultiViews with Apache) you may
           wish to hide the extensions (while using the full URLs to check various things).
           (default: 0 (false))

       labels
           Hash containing replacement labels for one or more paths.  If no label is given for
           '/' (the root path) then 'Home' will be used.

       last_subtree_head
           The string to prepend to the last lower-level tree.  Only used if end_depth is not
           zero.

       last_subtree_foot
           The string to append to the last lower-level tree.  Only used if end_depth is not
           zero.

       nohide
           If the path matches this string, it will be included even if it matches the 'hide'
           string.

       prefix_url
           A prefix to prepend to all the links. (default: empty string)

       prepend_list
           Array of paths to prepend to the top-level links.  They are used as-is, and are not
           part of the processing done to the "paths" list of paths.

       preserve_order
           Preserve the ordering of the paths in the input list of paths; otherwise the links
           will be sorted alphabetically.  Note that if preserve_order is true, the structure is
           at the whims of the order of the original list of paths, and so could end up odd-
           looking.  (default: false)

       preserve_paths
           Do not extract intermediate paths or reorder the input list of paths.  This speeds
           things up, but assumes that the input paths are complete and in good order.  (default:
           false)

       start_depth
           Start your tree at this depth.  Zero is the root, level 1 is the files/sub-folders in
           the root, and so on.  (default: 0)

       top_level
           Decide which level is the "top" level.  Useful when you set the start_depth to
           something greater than 1.

   breadcrumb_trail
           $links = breadcrumb_trail(
                       current_url=>$url,
                       labels=>\%labels,
                       descriptions=>\%desc,
                       links_head=>'<p>',
                       links_foot=>"\n</p>",
                       subtree_head=>'',
                       subtree_foot=>"\n",
                       pre_item=>'',
                       post_item=>'',
                       pre_active_item=>'<em>',
                       post_active_item=>'</em>',
                       item_sep=>"\n",
                       tree_sep=>' &gt; ',
               ...
               );

       Given the current url, make a breadcrumb trail from it.  By default, this is laid out with
       '>' separators, but it can be set up to give a nested set of UL lists (as for
       "full_tree").

       The formatting options are as for "link_tree".

       Required:

       current_url
           The current url to be made into a breadcrumb-trail.

       Options:

       descriptions
           Optional hash of descriptions, to put next to the links.  The keys of this hash are
           the urls.

       exclude_root_parent
           If this is true, then the "current_parent" display options are not used for the "root"
           ("/") path, it isn't counted as a "parent" of the current_url.

       hide_ext
           If a site is hiding link extensions (such as using MultiViews with Apache) you may
           wish to hide the extensions (while using the full URLs to check various things).
           (default: 0 (false))

       labels
           Hash containing replacement labels for one or more URLS.  If no label is given for '/'
           (the root path) then 'Home' will be used.

   nav_tree
           $links = nav_tree(
               paths=>\@list_of_paths,
               labels=>\%labels,
               current_url=>$url,
               hide=>$hide_regex,
               nohide=>$nohide_regex,
               preserve_order=>1,
               descriptions=>\%desc,
               ...
               );

       This takes a list of links, and the current URL, and makes a nested navigation tree,
       consisting of (a) the top-level links (b) the links leading to the current URL (c) the
       links on the same level as the current URL, (d) the related links just above this level,
       depending on whether this is an index-page or a content page.

       Optionally one can hide links which match match the 'hide' option.

       The formatting options are as for "link_tree", with some additions.

       Required:

       current_url
           The link to the current page.  If one of the links equals this, then that is deemed to
           be the "active" link and is just displayed as a label rather than a link.  This is
           also used to determine which links to show and which ones to filter out.

       paths
           A reference to a list of paths: that is, URLs relative to the top of the site.

           For example, if the full URL is http://www.example.com/foo.html then the path is
           /foo.html

           This does not require that every possible path be given; all the intermediate paths
           will be figured out from the list.

       Options:

       append_list
           Array of paths to append to the top-level links.  They are used as-is, and are not
           part of the processing done to the "paths" list of paths. (see "prepend_list")

       descriptions
           Optional hash of descriptions, to put next to the links.  The keys of this hash are
           the paths.

       end_depth
           End your tree at this depth.  If zero, then go all the way.  By default this is set to
           the depth of the current_url.

       exclude_root_parent
           If this is true, then the "current_parent" display options are not used for the "root"
           ("/") path, it isn't counted as a "parent" of the current_url.

       hide
           If a path matches this string, don't include it in the tree.

       hide_ext
           If a site is hiding link extensions (such as using MultiViews with Apache) you may
           wish to hide the extensions (while using the full URLs to check various things).
           (default: 0 (false))

       labels
           Hash containing replacement labels for one or more paths.  If no label is given for
           '/' (the root path) then 'Home' will be used.

       last_subtree_head
           The string to prepend to the last lower-level tree.

       last_subtree_foot
           The string to append to the last lower-level tree.

       nohide
           If the path matches this string, it will be included even if it matches the 'hide'
           string.

       prefix_url
           A prefix to prepend to all the links. (default: empty string)

       prepend_list
           Array of paths to prepend to the top-level links.  They are used as-is, and are not
           part of the processing done to the "paths" list of paths.

       preserve_order
           Preserve the ordering of the paths in the input list of paths; otherwise the links
           will be sorted alphabetically.  (default: true)

       preserve_paths
           Do not extract intermediate paths or reorder the input list of paths.  This speeds
           things up, but assumes that the input paths are complete and in good order.  (default:
           false)

       start_depth
           Start your tree at this depth.  Zero is the root, level 1 is the files/sub-folders in
           the root, and so on.  (default: 1)

       top_level
           Decide which level is the "top" level.  Useful when you set the start_depth to
           something greater than 1.

Private Functions

       These functions cannot be exported.

   make_item
       $item = make_item(      this_label=>$label,      this_link=>$link,      hide_ext=>0,
            current_url=>$url,      current_parents=>\%current_parents,
            descriptions=>\%desc,      format=>\%format,
           );

       %format = (      pre_desc=>' ',      post_desc=>'',      pre_item=>'<li>',
            post_item=>'</li>'      pre_active_item=>'<em>',      post_active_item=>'</em>',
            pre_current_parent=>'<em>',      post_current_parent=>'</em>',      item_sep=>"\n");
       );

       Format a link item.

       See "link_list" for the formatting options.

       this_label
           The label of the required link.  If there is no label, this uses the base-name of the
           last part of the link, capitalizing it and replacing underscores and dashes with
           spaces.

       this_link
           The URL of the required link.

       current_url
           The link to the current page.  If one of the links equals this, then that is deemed to
           be the "active" link and is just displayed as a label rather than a link.

       current_parents
           URLs of the parents of the current item.

       descriptions
           Optional hash of descriptions, to put next to the links.  The keys of this hash are
           the links (not the labels).

       defer_post_item
           Don't add the 'post_item' string if this is true.  (needed for nested lists) (default:
           false)

       no_link
           Don't make a link for this, just a label.

   make_canonical
       my $new_url = make_canonical($url);

       Make a URL canonical; remove the 'index.*' and add on a needed '/' -- this assumes that
       directory names never have a '.' in them.

   get_index_path
       my $new_url = get_index_path($url);

       Get the "index" part of this path.  That is, if this path is not for an index-page, then
       get the parent index-page path for this path.  (Removes the trailing slash).

   get_index_parent
       my $new_url = get_index_parent($url);

       Get the parent of the "index" part of this path.  (Removes the trailing slash).

   path_depth
       my $depth = path_depth($url);

       Calculate the "depth" of the given path.

   link_is_active
           if (link_is_active(this_link=>$link, current_url=>$url))
           ...

       Check if the given link is "active", that is, if it matches the 'current_url'.

   traverse_lol
       $links = traverse_lol(\@list_of_lists,
           labels=>\%labels,
           tree_depth=>$depth
           current_format=>\%format,
           ...
           );

       Traverse the list of lists (of urls) to produce a nested collection of links.

       This consumes the list_of_lists!

   extract_all_paths
       my @all_paths = extract_all_paths(paths=>\@paths,
           preserve_order=>0);

       Extract all possible paths out of a list of paths.  Thus, if one has

       /foo/bar/baz.html

       then that would make

       / /foo/ /foo/bar/ /foo/bar/baz.html

       If 'preserve_order' is true, this preserves the ordering of the paths in the input list;
       otherwise the output paths are sorted alphabetically.

   extract_current_parents
           my %current_parents = extract_current_parents(current_url=>$url,
                                                     exclude_root_parent=>0);

       Extract the "parent" paths of the current url

       /foo/bar/baz.html

       then that would make

       / /foo/ /foo/bar/

       If 'exclude_root_parent' is true, then the '/' is excluded from the list of parents.

   build_lol
           my @lol = build_lol(
               paths=>\@paths,
               current_url=>$url,
               navbar_type=>'',
           );

       Build a list of lists of paths, given a simple list of paths.  Assumes that this list has
       already been filtered.

       paths
           Reference to list of paths; this is consumed.

   filter_out_paths
           my @filtered_paths = filter_out_paths(
               paths=>\@paths,
               current_url=>$url,
               hide=>$hide,
               nohide=>$nohide,
               start_depth=>$start_depth,
               end_depth=>$end_depth,
               top_level=>$top_level,
               navbar_type=>'',
           );

       Filter out the paths we don't want from our list of paths.  Returns a list of the paths we
       want.

   make_default_format
           my %default_format = make_default_format(%args);

       Make the default format hash from the args.  Returns a hash of format options.

   make_extra_formats
           my %formats = make_extra_formats(%args);

       Transforms the subtree_head and subtree_foot into the "formats" method of formatting.
       Returns a hash of hashes of format options.

REQUIRES

           Test::More

INSTALLATION

       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

       In order to install somewhere other than the default, such as in a directory under your
       home directory, like "/home/fred/perl" go

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

       as the first step instead.

       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.

       Therefore you will need to change the PERL5LIB variable to add /home/fred/perl/lib

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

SEE ALSO

       perl(1).

BUGS

       Please report any bugs or feature requests to the author.

AUTHOR

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

COPYRIGHT AND LICENCE

       Copyright (c) 2006 by Kathryn Andersen

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