NAME

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

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.