HTML::LinkList(3pm)

📦
version 0.1701 · 5 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

okay bestie, this is HTML::LinkList(3pm), coming at you from the User Contributed Perl Documentation, and it is literally all about making a 'smart' list of HTML links. 💅✨

🌟 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 has a whole bunch of functions for taking sets of URLs and labels and turning them into suitably formatted HTML. 💖 These links are "smart" because, if you give them the url of the current page, and any of the links in the list equal it, that item in the list gets formatted as a special label, not as a link. And that is a Good Thing, because bestie, the user would be so confused clicking on a link back to the current page. 😭

Many website systems have plugins for "smart" navbars, but those are specialized for that system only, and can't be reused elsewhere, forcing people to reinvent the wheel. So here is 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 a list of urls (and optional labels) while taking into account the "current" URL. ✨

This gives you 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)
        $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

okay so this one is THE tree builder and she eats every single time 💅

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

Give her a set of paths and she'll generate a whole tree of links in the style of link_tree. She figures out all the intermediate paths by herself and constructs the nested structure for you, clustering parents and children together. it's giving family reunion, no cap 🫶

The formatting options are as for link_tree.

Required 💖

  • paths — a reference to a list of paths, meaning 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

She does not require that every possible path be given — all the intermediate paths will be figured out from the list. she's doing the math for you bestie 🧮✨

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, and 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) ⚠️ like, she's trusting you completely here
  • 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.
$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; ',
    ...
    );

Give her the current url and she makes a breadcrumb trail out of it. classic. 🍞 By default it's laid out with '>' separators, but you can set it up to give a nested set of UL lists (as for full_tree) — so basically she can turn into a whole other girl when the vibes call for it.

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, and 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.
$links = nav_tree(
    paths=>\@list_of_paths,
    labels=>\%labels,
    current_url=>$url,
    hide=>$hide_regex,
    nohide=>$nohide_regex,
    preserve_order=>1,
    descriptions=>\%desc,
    ...
    );

This one takes a list of links plus the current URL and builds you a nested navigation tree, made up 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 the 'hide' option. 🫣

The formatting options are as for link_tree, with some additions — she's got extras, she's the main character.

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, meaning 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, and 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

Okay bestie, listen — these ones are locked in the vault. They are not exported, so don't come for them, they're for internal use only. Internal business. 💅

🛠️ 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");
);

So basically this one formats a link item. ✨ That's the whole job, and it does it gorgeously.

If you wanna know about all the formatting options, go peek at link_list — the lore lives there. 👑

The args, one by one:

  • this_label — the label of the link you're asking for. And if there's no label? No worries, it takes the base-name of the last part of the link, capitalizes it, and swaps all the underscores and dashes out for spaces. DIY label, slay.
  • this_link — the URL of the link you want. 🌈
  • current_url — the link to the current page. If any of the links matches this one, that link is deemed the "active" link, and it gets shown as just a label instead of a link. Main character treatment, honestly. 👑
  • current_parents — the URLs of the parents of the current item. 🫶
  • descriptions — optional hash of descriptions to put right next to the links. Heads up: the keys of this hash are the links, not the labels. Don't get it twisted. ⚠️
  • defer_post_item — don't add the 'post_item' string if this is true. It's needed for nested lists. (default: false)
  • no_link — don't make a link for this, just a label. Simple as that. ✨

🔗 make_canonical

my $new_url = make_canonical($url);

Makes a URL canonical — it yanks off the 'index.*' and adds on a needed '/'. FYI though: this assumes that directory names never have a '.' in them. That's the vibe it's operating on. 🫠

📂 get_index_path

my $new_url = get_index_path($url);

Gets the "index" part of this path. Meaning: if this path isn't for an index-page, then you get the parent index-page path for this path. (And yes, it removes the trailing slash. 🧹)

🧬 get_index_parent

my $new_url = get_index_parent($url);

Gets the parent of the "index" part of this path. (Removes the trailing slash. Again. The slash stays gone. ✂️)

📏 path_depth

my $depth = path_depth($url);

Calculates the "depth" of the given path. That's it, that's the function. 🌊

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

Checks if the given link is "active" — which is to say, whether it matches the 'current_url'. vibe check passed or not, no in-between. 💅

🌳 traverse_lol

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

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

⚠️ Heads up bestie: this consumes the list_of_lists! It's gone after. Not coming back. 💀

🗺️ extract_all_paths

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

Extracts every possible path out of a list of paths. So like, if you've got

/foo/bar/baz.html

then that would make

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

And if 'preserve_order' is true, this preserves the ordering of the paths in the input list; otherwise the output paths get sorted alphabetically. Pick your fighter. ⭐

🫂 extract_current_parents

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

Extracts the "parent" paths of the current url. So for

/foo/bar/baz.html

then that would make

/ /foo/ /foo/bar/

And if 'exclude_root_parent' is true, then the '/' gets excluded from the list of parents. Bye root, you're not invited. 🙈

🧱 build_lol

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

Builds a list of lists of paths, given a simple list of paths. And it assumes that this list has already been filtered — so do that first, okay? 🔥

  • paths — reference to list of paths; and yeah, this one is consumed. Gone. 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=>'',
);

Filters out the paths we don't want from our list of paths. Returns a list of the paths we do want. Curated. ✨

🎀 make_default_format

my %default_format = make_default_format(%args);

Makes the default format hash from the args. Returns a hash of format options. That's the whole glow-up. 💖

🌸 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. Layers on layers, hun. 🧚

📦 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 instead:

perl Build.PL
perl Build
perl Build test
perl Build install

And if you wanna install somewhere other than the default — like a directory under your home directory, say "/home/fred/perl" — then 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 so it can 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

🐛 BUGS

Please report any bugs or feature requests to the author. They wanna hear it, fr fr. 💌

👑 AUTHOR

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

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.

and that's the whole page bestie, we ate and left no crumbs 💅✨🎀 This one's perl v5.36.0, dated 2022-10-15 — HTML::LinkList(3pm), iconic as always. 🦋 Go build some link lists, you got this. 💖

📦 where this page comes from