Index


NAME

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

VERSION

This describes version 0.1503 of HTML::LinkList.

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

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.

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.

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