Take me over?

The maintainer of this distribution is looking for someone to take over! If you're interested then please contact them via email.

NAME

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

VERSION

This describes version 0.08 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=>" :: ");

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.

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.

The "nav_bar" function creates a set of links designed to be used as an "across the top" 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,
	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.

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.
prefix_url: A prefix to prepend to all the links. (default: empty string)
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.
urls: The urls in the order you want them displayed. If this list is empty, then nothing will be generated.
descriptions: Optional hash of descriptions, to put next to the links. The keys of this hash are the urls.
links_head: String to begin the list with.
links_foot: String to end the list with.
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'.
post_active_item: An additional string to append to each active item, before post_item.
item_sep: String to put between items.

link_tree

    $links = link_tree(
	current_url=>$url,
	link_tree=>\@list_of_lists,
	labels=>\%labels,
	descriptions=>\%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");

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.

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.
prefix_url: A prefix to prepend to all the links. (default: empty string)
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.
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.
descriptions: Optional hash of descriptions, to put next to the links. The keys of this hash are the urls.
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>)
subtree_head: The string to prepend to lower-level trees. (default: <ul>)
subtree_foot: The string to append to lower-level trees. (default: </ul>)
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: )
post_active_item: An additional string to append to each active item, before post_item. (default: )
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.
post_current_parent: An additional string to append to a link which is a parent of the 'current_url' link, before post_item.
item_sep: The string to separate each item.
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,
	...
	);

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".

Options:

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.

labels

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

descriptions

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

prefix_url

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

hide

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

nohide

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

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)

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)

end_depth

End your tree at this depth. If zero, then go all the way.

top_level

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

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.

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".

Options:

current_url: The current url to be made into a breadcrumb-trail.
labels: Hash containing replacement labels for one or more URLS. If no label is given for '/' (the root path) then 'Home' will be used.
descriptions: Optional hash of descriptions, to put next to the links. The keys of this hash are the urls.

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.

Options:

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.

labels

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

descriptions

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

hide

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

nohide

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

preserve_order

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

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.

    $links = nav_bar(
	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 multi-level navigation bar related to the current_url, where links at the same "level" in the hierarchy are grouped together, and then links on the next level, and so on. It's intended for an across-the-top navbar; if you have a very deep hierarchy it may be better to use "nav_tree".

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

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

Options:

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.

labels

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

descriptions

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

hide

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

nohide

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

preserve_order

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

pre_level

String to put in front of a level group.

post_level

String to append to a level group.

level_sep

String to separate the levels.

pre_level_parent

String to put in front of the link which is the parent of this level.

post_level_parent

String to append to the link which is the parent of this level.

Private Functions

These functions cannot be exported.

make_item

$item = make_item( this_label=>$label, this_link=>$link, current_url=>$url, current_parents=>\%current_parents, descriptions=>\%desc, pre_item=>'<li>', post_item=>'</li>' 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.

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 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 ... );

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

Extract the "parent" paths of the current url

/foo/bar/baz.html

then that would make

/ /foo/ /foo/bar/

build_lol

    my @lol = build_lol(
	paths=>\@paths,
	current_url=>$url,
	do_navbar=>0,
    );

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,
	do_navbar=>0,
    );

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

traverse_levels

$links = traverse_levels(\@list_of_lists, labels=>\%labels, ... );

Expects a list, where each item is a reference to a list of links; or a list of links plus one list of a list of links -- the latter is an indicator of the parent(s) of this level.

Creates a list-grid of items.

build_levels

    my @lol = build_levels(
	paths=>\@paths,
	current_url=>$url,
    );

Build a "grid" of paths, given a simple list of paths. The first item contains a list of items at 'start_depth', then the following items contain lists of items at lower depth, with optional filtering if we are doing a navbar.

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}

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

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

To install HTML::LinkList, copy and paste the appropriate command in to your terminal.

cpanm

cpanm HTML::LinkList

CPAN shell

perl -MCPAN -e shell
install HTML::LinkList

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

Take me over?

NAME

VERSION

SYNOPSIS

DESCRIPTION

FUNCTIONS

link_list

link_tree

full_tree

breadcrumb_trail

nav_tree

nav_bar

Private Functions

make_item

make_canonical

get_index_path

get_index_parent

path_depth

link_is_active

traverse_lol

extract_all_paths

extract_current_parents

build_lol

filter_out_paths

traverse_levels

build_levels

REQUIRES

INSTALLATION

SEE ALSO

BUGS

AUTHOR

COPYRIGHT AND LICENCE

Module Install Instructions