1HTML::LinkList(3) User Contributed Perl Documentation HTML::LinkList(3)
2
6 HTML::LinkList - Create a 'smart' list of HTML links.
7
9 version 0.1701
10
12 use HTML::LinkList qw(link_list);
13 # default formatting
15 my $html_links = link_list(current_url=>$url,
16 urls=>\@links_in_order,
17 labels=>\%labels,
18 descriptions=>\%desc);
19 # paragraph with ' :: ' separators
21 my $html_links = link_list(current_url=>$url,
22 urls=>\@links_in_order,
23 labels=>\%labels,
24 descriptions=>\%desc,
25 links_head=>'<p>',
26 links_foot=>'</p>',
27 pre_item=>'',
28 post_item=>''
29 pre_active_item=>'<em>',
30 post_active_item=>'</em>',
31 item_sep=>" :: ");
32 # multi-level list
34 my $html_links = link_tree(
35 current_url=>$url,
36 link_tree=>\@list_of_lists,
37 labels=>\%labels,
38 descriptions=>\%desc);
39
41 This module contains a number of functions for taking sets of URLs and
42 labels and creating suitably formatted HTML. These links are "smart"
43 because, if given the url of the current page, if any of the links in
44 the list equal it, that item in the list will be formatted as a special
45 label, not as a link; this is a Good Thing, since the user would be
46 confused by clicking on a link back to the current page.
47 While many website systems have plugins for "smart" navbars, they are
49 specialized for that system only, and can't be reused elsewhere,
50 forcing people to reinvent the wheel. I hereby present one wheel, free
51 to be reused by anybody; just the simple functions, a backend, which
52 can be plugged into whatever system you want.
53 The default format for the HTML is to make an unordered list, but there
55 are many options, enabling one to have a flatter layout with any
56 separators you desire, or a more complicated list with differing
57 formats for different levels.
58 The "link_list" function uses a simple list of links -- good for a
60 simple navbar.
61 The "link_tree" function takes a set of nested links and makes the HTML
63 for them -- good for making a table of contents, or a more complicated
64 navbar.
65 The "full_tree" function takes a list of paths and makes a full tree of
67 all the pages and index-pages in those paths -- good for making a site
68 map.
69 The "breadcrumb_trail" function takes a url and makes a "breadcrumb
71 trail" from it.
72 The "nav_tree" function creates a set of nested links to be used as a
74 multi-level navbar; one can give it a list of paths (as for full_tree)
75 and it will only show the links related to the current URL.
76
78 To export a function, add it to the 'use' call.
79 use HTML::LinkList qw(link_list);
81 To export all functions do:
83 use HTML::LinkList ':all';
85 link_list
87 $links = link_list(
88 current_url=>$url,
89 urls=>\@links_in_order,
90 labels=>\%labels,
91 descriptions=>\%desc,
92 pre_desc=>' ',
93 post_desc=>'',
94 links_head=>'<ul>',
95 links_foot=>'</ul>',
96 pre_item=>'<li>',
97 post_item=>'</li>'
98 pre_active_item=>'<em>',
99 post_active_item=>'</em>',
100 item_sep=>"\n");
101 Generates a simple list of links, from list of urls (and optional
103 labels) taking into account of the "current" URL.
104 This provides a large number of options to customize the appearance of
106 the list. The default setup is for a simple UL list, but setting the
107 options can enable you to make it something other than a list
108 altogether, or add in CSS styles or classes to make it look just like
109 you want.
110 Required:
112 urls
114 The urls in the order you want them displayed. If this list is
115 empty, then nothing will be generated.
116 Options:
118 current_url
120 The link to the current page. If one of the links equals this,
121 then that is deemed to be the "active" link and is just displayed
122 as a label rather than a link.
123 descriptions
125 Optional hash of descriptions, to put next to the links. The keys
126 of this hash are the urls.
127 hide_ext
129 If a site is hiding link extensions (such as using MultiViews with
130 Apache) you may wish to hide the extensions (while using the full
131 URLs to check various things). (default: 0 (false))
132 item_sep
134 String to put between items.
135 labels
137 A hash whose keys are links and whose values are labels. These are
138 the labels for the links; if no label is given, then the last part
139 of the link is used for the label, with some formatting.
140 links_head
142 String to begin the list with.
143 links_foot
145 String to end the list with.
146 pre_desc
148 String to prepend to each description.
149 post_desc
151 String to append to each description.
152 pre_item
154 String to prepend to each item.
155 post_item
157 String to append to each item.
158 pre_active_item
160 An additional string to put in front of each "active" item, after
161 pre_item. The "active" item is the link which matches
162 'current_url'.
163 pre_item_active
165 INSTEAD of the "pre_item" string, use this string for active items
166 post_active_item
168 An additional string to append to each active item, before
169 post_item.
170 prefix_url
172 A prefix to prepend to all the links. (default: empty string)
173 link_tree
175 $links = link_tree(
176 current_url=>$url,
177 link_tree=>\@list_of_lists,
178 labels=>\%labels,
179 descriptions=>\%desc,
180 pre_desc=>' ',
181 post_desc=>'',
182 links_head=>'<ul>',
183 links_foot=>'</ul>',
184 subtree_head=>'<ul>',
185 subtree_foot=>'</ul>',
186 pre_item=>'<li>',
187 post_item=>'</li>'
188 pre_active_item=>'<em>',
189 post_active_item=>'</em>',
190 item_sep=>"\n",
191 tree_sep=>"\n",
192 formats=>\%formats);
193 Generates nested lists of links from a list of lists of links. This is
195 useful for things such as table-of-contents or site maps.
196 By default, this will return UL lists, but this is highly configurable.
198 Required:
200 link_tree
202 A list of lists of urls, in the order you want them displayed. If
203 a url is not in this list, it will not be displayed.
204 Options:
206 current_url
208 The link to the current page. If one of the links equals this,
209 then that is deemed to be the "active" link and is just displayed
210 as a label rather than a link.
211 descriptions
213 Optional hash of descriptions, to put next to the links. The keys
214 of this hash are the urls.
215 exclude_root_parent
217 If this is true, then the "current_parent" display options are not
218 used for the "root" ("/") path, it isn't counted as a "parent" of
219 the current_url.
220 formats
222 A reference to a hash containing advanced format settings. For
223 example:
224 my %formats = (
226 # level 1 and onwards
227 '1' => {
228 tree_head=>"<ol>",
229 tree_foot=>"</ol>\n",
230 },
231 # level 2 and onwards
232 '2' => {
233 tree_head=>"<ul>",
234 tree_foot=>"</ul>\n",
235 },
236 # level 3 and onwards
237 '3' => {
238 pre_item=>'(',
239 post_item=>')',
240 item_sep=>",\n",
241 tree_sep=>' -> ',
242 tree_head=>"<br/>\n",
243 tree_foot=>"",
244 }
245 );
246 The formats hash enables you to control the formatting on a per-
248 level basis. Each key of the hash corresponds to a level-number;
249 the sub-hashes contain format arguments which will apply from that
250 level onwards. If an argument isn't given in the sub-hash, then it
251 will fall back to the previous level (or to the default, if there
252 is no setting for that format-argument for a previous level).
253 The only difference between the names of the arguments in the sub-
255 hash and in the global format arguments is that instead of
256 'subtree_head' and subtree_foot' it uses 'tree_head' and
257 'tree_foot'.
258 hide_ext
260 If a site is hiding link extensions (such as using MultiViews with
261 Apache) you may wish to hide the extensions (while using the full
262 URLs to check various things). (default: 0 (false))
263 item_sep
265 The string to separate each item.
266 labels
268 A hash whose keys are links and whose values are labels. These are
269 the labels for the links; if no label is given, then the last part
270 of the link is used for the label, with some formatting.
271 links_head
273 The string to prepend the top-level tree with. (default: <ul>)
274 links_foot
276 The string to append to the top-level tree. (default: </ul>)
277 pre_desc
279 String to prepend to each description.
280 post_desc
282 String to append to each description.
283 pre_item
285 String to prepend to each item. (default: <li>)
286 post_item
288 String to append to each item. (default: </li>)
289 pre_active_item
291 An additional string to put in front of each "active" item, after
292 pre_item. The "active" item is the link which matches
293 'current_url'. (default: <em>)
294 pre_item_active
296 INSTEAD of the "pre_item" string, use this string for active items
297 post_active_item
299 An additional string to append to each active item, before
300 post_item. (default: </em>)
301 pre_current_parent
303 An additional string to put in front of a link which is a parent of
304 the 'current_url' link, after pre_item.
305 pre_item_current_parent
307 INSTEAD of the "pre_item" string, use this for links which are
308 parents of the 'current_url' link.
309 post_current_parent
311 An additional string to append to a link which is a parent of the
312 'current_url' link, before post_item.
313 prefix_url
315 A prefix to prepend to all the links. (default: empty string)
316 subtree_head
318 The string to prepend to lower-level trees. (default: <ul>)
319 subtree_foot
321 The string to append to lower-level trees. (default: </ul>)
322 tree_sep
324 The string to separate each tree.
325 full_tree
327 $links = full_tree(
328 paths=>\@list_of_paths,
329 labels=>\%labels,
330 descriptions=>\%desc,
331 hide=>$hide_regex,
332 nohide=>$nohide_regex,
333 start_depth=>0,
334 end_depth=>0,
335 top_level=>0,
336 preserve_order=>0,
337 preserve_paths=>0,
338 ...
339 );
340 Given a set of paths this will generate a tree of links in the style of
342 link_tree. This will figure out all the intermediate paths and
343 construct the nested structure for you, clustering parents and children
344 together.
345 The formatting options are as for "link_tree".
347 Required:
349 paths
351 A reference to a list of paths: that is, URLs relative to the top
352 of the site.
353 For example, if the full URL is http://www.example.com/foo.html
355 then the path is /foo.html
356 If the full URL is http://www.example.com/~frednurk/foo.html then
358 the path is /foo.html
359 This does not require that every possible path be given; all the
361 intermediate paths will be figured out from the list.
362 Options:
364 append_list
366 Array of paths to append to the top-level links. They are used as-
367 is, and are not part of the processing done to the "paths" list of
368 paths. (see "prepend_list")
369 descriptions
371 Optional hash of descriptions, to put next to the links. The keys
372 of this hash are the paths.
373 end_depth
375 End your tree at this depth. If zero, then go all the way. (see
376 "start_depth")
377 exclude_root_parent
379 If this is true, then the "current_parent" display options are not
380 used for the "root" ("/") path, it isn't counted as a "parent" of
381 the current_url.
382 hide
384 If the path matches this string, don't include it in the tree.
385 hide_ext
387 If a site is hiding link extensions (such as using MultiViews with
388 Apache) you may wish to hide the extensions (while using the full
389 URLs to check various things). (default: 0 (false))
390 labels
392 Hash containing replacement labels for one or more paths. If no
393 label is given for '/' (the root path) then 'Home' will be used.
394 last_subtree_head
396 The string to prepend to the last lower-level tree. Only used if
397 end_depth is not zero.
398 last_subtree_foot
400 The string to append to the last lower-level tree. Only used if
401 end_depth is not zero.
402 nohide
404 If the path matches this string, it will be included even if it
405 matches the 'hide' string.
406 prefix_url
408 A prefix to prepend to all the links. (default: empty string)
409 prepend_list
411 Array of paths to prepend to the top-level links. They are used
412 as-is, and are not part of the processing done to the "paths" list
413 of paths.
414 preserve_order
416 Preserve the ordering of the paths in the input list of paths;
417 otherwise the links will be sorted alphabetically. Note that if
418 preserve_order is true, the structure is at the whims of the order
419 of the original list of paths, and so could end up odd-looking.
420 (default: false)
421 preserve_paths
423 Do not extract intermediate paths or reorder the input list of
424 paths. This speeds things up, but assumes that the input paths are
425 complete and in good order. (default: false)
426 start_depth
428 Start your tree at this depth. Zero is the root, level 1 is the
429 files/sub-folders in the root, and so on. (default: 0)
430 top_level
432 Decide which level is the "top" level. Useful when you set the
433 start_depth to something greater than 1.
434 breadcrumb_trail
436 $links = breadcrumb_trail(
437 current_url=>$url,
438 labels=>\%labels,
439 descriptions=>\%desc,
440 links_head=>'<p>',
441 links_foot=>"\n</p>",
442 subtree_head=>'',
443 subtree_foot=>"\n",
444 pre_item=>'',
445 post_item=>'',
446 pre_active_item=>'<em>',
447 post_active_item=>'</em>',
448 item_sep=>"\n",
449 tree_sep=>' > ',
450 ...
451 );
452 Given the current url, make a breadcrumb trail from it. By default,
454 this is laid out with '>' separators, but it can be set up to give a
455 nested set of UL lists (as for "full_tree").
456 The formatting options are as for "link_tree".
458 Required:
460 current_url
462 The current url to be made into a breadcrumb-trail.
463 Options:
465 descriptions
467 Optional hash of descriptions, to put next to the links. The keys
468 of this hash are the urls.
469 exclude_root_parent
471 If this is true, then the "current_parent" display options are not
472 used for the "root" ("/") path, it isn't counted as a "parent" of
473 the current_url.
474 hide_ext
476 If a site is hiding link extensions (such as using MultiViews with
477 Apache) you may wish to hide the extensions (while using the full
478 URLs to check various things). (default: 0 (false))
479 labels
481 Hash containing replacement labels for one or more URLS. If no
482 label is given for '/' (the root path) then 'Home' will be used.
483 nav_tree
485 $links = nav_tree(
486 paths=>\@list_of_paths,
487 labels=>\%labels,
488 current_url=>$url,
489 hide=>$hide_regex,
490 nohide=>$nohide_regex,
491 preserve_order=>1,
492 descriptions=>\%desc,
493 ...
494 );
495 This takes a list of links, and the current URL, and makes a nested
497 navigation tree, consisting of (a) the top-level links (b) the links
498 leading to the current URL (c) the links on the same level as the
499 current URL, (d) the related links just above this level, depending on
500 whether this is an index-page or a content page.
501 Optionally one can hide links which match match the 'hide' option.
503 The formatting options are as for "link_tree", with some additions.
505 Required:
507 current_url
509 The link to the current page. If one of the links equals this,
510 then that is deemed to be the "active" link and is just displayed
511 as a label rather than a link. This is also used to determine
512 which links to show and which ones to filter out.
513 paths
515 A reference to a list of paths: that is, URLs relative to the top
516 of the site.
517 For example, if the full URL is http://www.example.com/foo.html
519 then the path is /foo.html
520 This does not require that every possible path be given; all the
522 intermediate paths will be figured out from the list.
523 Options:
525 append_list
527 Array of paths to append to the top-level links. They are used as-
528 is, and are not part of the processing done to the "paths" list of
529 paths. (see "prepend_list")
530 descriptions
532 Optional hash of descriptions, to put next to the links. The keys
533 of this hash are the paths.
534 end_depth
536 End your tree at this depth. If zero, then go all the way. By
537 default this is set to the depth of the current_url.
538 exclude_root_parent
540 If this is true, then the "current_parent" display options are not
541 used for the "root" ("/") path, it isn't counted as a "parent" of
542 the current_url.
543 hide
545 If a path matches this string, don't include it in the tree.
546 hide_ext
548 If a site is hiding link extensions (such as using MultiViews with
549 Apache) you may wish to hide the extensions (while using the full
550 URLs to check various things). (default: 0 (false))
551 labels
553 Hash containing replacement labels for one or more paths. If no
554 label is given for '/' (the root path) then 'Home' will be used.
555 last_subtree_head
557 The string to prepend to the last lower-level tree.
558 last_subtree_foot
560 The string to append to the last lower-level tree.
561 nohide
563 If the path matches this string, it will be included even if it
564 matches the 'hide' string.
565 prefix_url
567 A prefix to prepend to all the links. (default: empty string)
568 prepend_list
570 Array of paths to prepend to the top-level links. They are used
571 as-is, and are not part of the processing done to the "paths" list
572 of paths.
573 preserve_order
575 Preserve the ordering of the paths in the input list of paths;
576 otherwise the links will be sorted alphabetically. (default: true)
577 preserve_paths
579 Do not extract intermediate paths or reorder the input list of
580 paths. This speeds things up, but assumes that the input paths are
581 complete and in good order. (default: false)
582 start_depth
584 Start your tree at this depth. Zero is the root, level 1 is the
585 files/sub-folders in the root, and so on. (default: 1)
586 top_level
588 Decide which level is the "top" level. Useful when you set the
589 start_depth to something greater than 1.
590
592 These functions cannot be exported.
593 make_item
595 $item = make_item( this_label=>$label, this_link=>$link,
596 hide_ext=>0, current_url=>$url,
597 current_parents=>\%current_parents, descriptions=>\%desc,
598 format=>\%format,
599 );
600 %format = ( pre_desc=>' ', post_desc=>'',
602 pre_item=>'<li>', post_item=>'</li>'
603 pre_active_item=>'<em>', post_active_item=>'</em>',
604 pre_current_parent=>'<em>', post_current_parent=>'</em>',
605 item_sep=>"\n"); );
606 Format a link item.
608 See "link_list" for the formatting options.
610 this_label
612 The label of the required link. If there is no label, this uses
613 the base-name of the last part of the link, capitalizing it and
614 replacing underscores and dashes with spaces.
615 this_link
617 The URL of the required link.
618 current_url
620 The link to the current page. If one of the links equals this,
621 then that is deemed to be the "active" link and is just displayed
622 as a label rather than a link.
623 current_parents
625 URLs of the parents of the current item.
626 descriptions
628 Optional hash of descriptions, to put next to the links. The keys
629 of this hash are the links (not the labels).
630 defer_post_item
632 Don't add the 'post_item' string if this is true. (needed for
633 nested lists) (default: false)
634 no_link
636 Don't make a link for this, just a label.
637 make_canonical
639 my $new_url = make_canonical($url);
640 Make a URL canonical; remove the 'index.*' and add on a needed '/' --
642 this assumes that directory names never have a '.' in them.
643 get_index_path
645 my $new_url = get_index_path($url);
646 Get the "index" part of this path. That is, if this path is not for an
648 index-page, then get the parent index-page path for this path.
649 (Removes the trailing slash).
650 get_index_parent
652 my $new_url = get_index_parent($url);
653 Get the parent of the "index" part of this path. (Removes the trailing
655 slash).
656 path_depth
658 my $depth = path_depth($url);
659 Calculate the "depth" of the given path.
661 link_is_active
663 if (link_is_active(this_link=>$link, current_url=>$url))
664 ...
665 Check if the given link is "active", that is, if it matches the
667 'current_url'.
668 traverse_lol
670 $links = traverse_lol(\@list_of_lists,
671 labels=>\%labels,
672 tree_depth=>$depth
673 current_format=>\%format,
674 ...
675 );
676 Traverse the list of lists (of urls) to produce a nested collection of
678 links.
679 This consumes the list_of_lists!
681 extract_all_paths
683 my @all_paths = extract_all_paths(paths=>\@paths,
684 preserve_order=>0);
685 Extract all possible paths out of a list of paths. Thus, if one has
687 /foo/bar/baz.html
689 then that would make
691 / /foo/ /foo/bar/ /foo/bar/baz.html
693 If 'preserve_order' is true, this preserves the ordering of the paths
695 in the input list; otherwise the output paths are sorted
696 alphabetically.
697 extract_current_parents
699 my %current_parents = extract_current_parents(current_url=>$url,
700 exclude_root_parent=>0);
701 Extract the "parent" paths of the current url
703 /foo/bar/baz.html
705 then that would make
707 / /foo/ /foo/bar/
709 If 'exclude_root_parent' is true, then the '/' is excluded from the
711 list of parents.
712 build_lol
714 my @lol = build_lol(
715 paths=>\@paths,
716 current_url=>$url,
717 navbar_type=>'',
718 );
719 Build a list of lists of paths, given a simple list of paths. Assumes
721 that this list has already been filtered.
722 paths
724 Reference to list of paths; this is consumed.
725 filter_out_paths
727 my @filtered_paths = filter_out_paths(
728 paths=>\@paths,
729 current_url=>$url,
730 hide=>$hide,
731 nohide=>$nohide,
732 start_depth=>$start_depth,
733 end_depth=>$end_depth,
734 top_level=>$top_level,
735 navbar_type=>'',
736 );
737 Filter out the paths we don't want from our list of paths. Returns a
739 list of the paths we want.
740 make_default_format
742 my %default_format = make_default_format(%args);
743 Make the default format hash from the args. Returns a hash of format
745 options.
746 make_extra_formats
748 my %formats = make_extra_formats(%args);
749 Transforms the subtree_head and subtree_foot into the "formats" method
751 of formatting. Returns a hash of hashes of format options.
752
754 Test::More
755
757 To install this module, run the following commands:
758 perl Build.PL
760 ./Build
761 ./Build test
762 ./Build install
763 Or, if you're on a platform (like DOS or Windows) that doesn't like the
765 "./" notation, you can do this:
766 perl Build.PL
768 perl Build
769 perl Build test
770 perl Build install
771 In order to install somewhere other than the default, such as in a
773 directory under your home directory, like "/home/fred/perl" go
774 perl Build.PL --install_base /home/fred/perl
776 as the first step instead.
778 This will install the files underneath /home/fred/perl.
780 You will then need to make sure that you alter the PERL5LIB variable to
782 find the modules.
783 Therefore you will need to change the PERL5LIB variable to add
785 /home/fred/perl/lib
786 PERL5LIB=/home/fred/perl/lib:${PERL5LIB}
788
790 perl(1).
791
793 Please report any bugs or feature requests to the author.
794
796 Kathryn Andersen (RUBYKAT)
797 perlkat AT katspace dot com
798 http://www.katspace.com/tools/html_linklist/
799
801 Copyright (c) 2006 by Kathryn Andersen
802 This program is free software; you can redistribute it and/or modify it
804 under the same terms as Perl itself.
805perl v5.34.0 2022-01-21 HTML::LinkList(3)