The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
RUBYKAT / HTML-LinkList-0.1701 / README.mkdn

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';

$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:

Options:

$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:

Options:

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:

Options:

$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:

Options:

$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:

Options:

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=>'

  • ', post_item=>'
    • ' pre_active_item=>'', post_active_item=>'', pre_current_parent=>'', post_current_parent=>'', item_sep=>"\n"); );

    Format a link item.

    See "link_list" for the formatting options.

    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.

    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.

    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.