1HTML::LinkList(3) User Contributed Perl Documentation HTML::LinkList(3)
2
3
4
6 HTML::LinkList - Create a 'smart' list of HTML links.
7
9 version 0.1701
10
12 use HTML::LinkList qw(link_list);
13
14 # default formatting
15 my $html_links = link_list(current_url=>$url,
16 urls=>\@links_in_order,
17 labels=>\%labels,
18 descriptions=>\%desc);
19
20 # 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
33 # 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
48 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
54 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
59 The "link_list" function uses a simple list of links -- good for a
60 simple navbar.
61
62 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
66 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
70 The "breadcrumb_trail" function takes a url and makes a "breadcrumb
71 trail" from it.
72
73 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
80 use HTML::LinkList qw(link_list);
81
82 To export all functions do:
83
84 use HTML::LinkList ':all';
85
86 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
102 Generates a simple list of links, from list of urls (and optional
103 labels) taking into account of the "current" URL.
104
105 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
111 Required:
112
113 urls
114 The urls in the order you want them displayed. If this list is
115 empty, then nothing will be generated.
116
117 Options:
118
119 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
124 descriptions
125 Optional hash of descriptions, to put next to the links. The keys
126 of this hash are the urls.
127
128 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
133 item_sep
134 String to put between items.
135
136 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
141 links_head
142 String to begin the list with.
143
144 links_foot
145 String to end the list with.
146
147 pre_desc
148 String to prepend to each description.
149
150 post_desc
151 String to append to each description.
152
153 pre_item
154 String to prepend to each item.
155
156 post_item
157 String to append to each item.
158
159 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
164 pre_item_active
165 INSTEAD of the "pre_item" string, use this string for active items
166
167 post_active_item
168 An additional string to append to each active item, before
169 post_item.
170
171 prefix_url
172 A prefix to prepend to all the links. (default: empty string)
173
174 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
194 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
197 By default, this will return UL lists, but this is highly configurable.
198
199 Required:
200
201 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
205 Options:
206
207 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
212 descriptions
213 Optional hash of descriptions, to put next to the links. The keys
214 of this hash are the urls.
215
216 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
221 formats
222 A reference to a hash containing advanced format settings. For
223 example:
224
225 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
247 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
254 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
259 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
264 item_sep
265 The string to separate each item.
266
267 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
272 links_head
273 The string to prepend the top-level tree with. (default: <ul>)
274
275 links_foot
276 The string to append to the top-level tree. (default: </ul>)
277
278 pre_desc
279 String to prepend to each description.
280
281 post_desc
282 String to append to each description.
283
284 pre_item
285 String to prepend to each item. (default: <li>)
286
287 post_item
288 String to append to each item. (default: </li>)
289
290 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
295 pre_item_active
296 INSTEAD of the "pre_item" string, use this string for active items
297
298 post_active_item
299 An additional string to append to each active item, before
300 post_item. (default: </em>)
301
302 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
306 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
310 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
314 prefix_url
315 A prefix to prepend to all the links. (default: empty string)
316
317 subtree_head
318 The string to prepend to lower-level trees. (default: <ul>)
319
320 subtree_foot
321 The string to append to lower-level trees. (default: </ul>)
322
323 tree_sep
324 The string to separate each tree.
325
326 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
341 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
346 The formatting options are as for "link_tree".
347
348 Required:
349
350 paths
351 A reference to a list of paths: that is, URLs relative to the top
352 of the site.
353
354 For example, if the full URL is http://www.example.com/foo.html
355 then the path is /foo.html
356
357 If the full URL is http://www.example.com/~frednurk/foo.html then
358 the path is /foo.html
359
360 This does not require that every possible path be given; all the
361 intermediate paths will be figured out from the list.
362
363 Options:
364
365 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
370 descriptions
371 Optional hash of descriptions, to put next to the links. The keys
372 of this hash are the paths.
373
374 end_depth
375 End your tree at this depth. If zero, then go all the way. (see
376 "start_depth")
377
378 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
383 hide
384 If the path matches this string, don't include it in the tree.
385
386 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
391 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
395 last_subtree_head
396 The string to prepend to the last lower-level tree. Only used if
397 end_depth is not zero.
398
399 last_subtree_foot
400 The string to append to the last lower-level tree. Only used if
401 end_depth is not zero.
402
403 nohide
404 If the path matches this string, it will be included even if it
405 matches the 'hide' string.
406
407 prefix_url
408 A prefix to prepend to all the links. (default: empty string)
409
410 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
415 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
422 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
427 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
431 top_level
432 Decide which level is the "top" level. Useful when you set the
433 start_depth to something greater than 1.
434
435 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
453 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
457 The formatting options are as for "link_tree".
458
459 Required:
460
461 current_url
462 The current url to be made into a breadcrumb-trail.
463
464 Options:
465
466 descriptions
467 Optional hash of descriptions, to put next to the links. The keys
468 of this hash are the urls.
469
470 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
475 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
480 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
484 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
496 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
502 Optionally one can hide links which match match the 'hide' option.
503
504 The formatting options are as for "link_tree", with some additions.
505
506 Required:
507
508 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
514 paths
515 A reference to a list of paths: that is, URLs relative to the top
516 of the site.
517
518 For example, if the full URL is http://www.example.com/foo.html
519 then the path is /foo.html
520
521 This does not require that every possible path be given; all the
522 intermediate paths will be figured out from the list.
523
524 Options:
525
526 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
531 descriptions
532 Optional hash of descriptions, to put next to the links. The keys
533 of this hash are the paths.
534
535 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
539 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
544 hide
545 If a path matches this string, don't include it in the tree.
546
547 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
552 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
556 last_subtree_head
557 The string to prepend to the last lower-level tree.
558
559 last_subtree_foot
560 The string to append to the last lower-level tree.
561
562 nohide
563 If the path matches this string, it will be included even if it
564 matches the 'hide' string.
565
566 prefix_url
567 A prefix to prepend to all the links. (default: empty string)
568
569 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
574 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
578 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
583 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
587 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
594 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
601 %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
607 Format a link item.
608
609 See "link_list" for the formatting options.
610
611 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
616 this_link
617 The URL of the required link.
618
619 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
624 current_parents
625 URLs of the parents of the current item.
626
627 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
631 defer_post_item
632 Don't add the 'post_item' string if this is true. (needed for
633 nested lists) (default: false)
634
635 no_link
636 Don't make a link for this, just a label.
637
638 make_canonical
639 my $new_url = make_canonical($url);
640
641 Make a URL canonical; remove the 'index.*' and add on a needed '/' --
642 this assumes that directory names never have a '.' in them.
643
644 get_index_path
645 my $new_url = get_index_path($url);
646
647 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
651 get_index_parent
652 my $new_url = get_index_parent($url);
653
654 Get the parent of the "index" part of this path. (Removes the trailing
655 slash).
656
657 path_depth
658 my $depth = path_depth($url);
659
660 Calculate the "depth" of the given path.
661
662 link_is_active
663 if (link_is_active(this_link=>$link, current_url=>$url))
664 ...
665
666 Check if the given link is "active", that is, if it matches the
667 'current_url'.
668
669 traverse_lol
670 $links = traverse_lol(\@list_of_lists,
671 labels=>\%labels,
672 tree_depth=>$depth
673 current_format=>\%format,
674 ...
675 );
676
677 Traverse the list of lists (of urls) to produce a nested collection of
678 links.
679
680 This consumes the list_of_lists!
681
682 extract_all_paths
683 my @all_paths = extract_all_paths(paths=>\@paths,
684 preserve_order=>0);
685
686 Extract all possible paths out of a list of paths. Thus, if one has
687
688 /foo/bar/baz.html
689
690 then that would make
691
692 / /foo/ /foo/bar/ /foo/bar/baz.html
693
694 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
698 extract_current_parents
699 my %current_parents = extract_current_parents(current_url=>$url,
700 exclude_root_parent=>0);
701
702 Extract the "parent" paths of the current url
703
704 /foo/bar/baz.html
705
706 then that would make
707
708 / /foo/ /foo/bar/
709
710 If 'exclude_root_parent' is true, then the '/' is excluded from the
711 list of parents.
712
713 build_lol
714 my @lol = build_lol(
715 paths=>\@paths,
716 current_url=>$url,
717 navbar_type=>'',
718 );
719
720 Build a list of lists of paths, given a simple list of paths. Assumes
721 that this list has already been filtered.
722
723 paths
724 Reference to list of paths; this is consumed.
725
726 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
738 Filter out the paths we don't want from our list of paths. Returns a
739 list of the paths we want.
740
741 make_default_format
742 my %default_format = make_default_format(%args);
743
744 Make the default format hash from the args. Returns a hash of format
745 options.
746
747 make_extra_formats
748 my %formats = make_extra_formats(%args);
749
750 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
759 perl Build.PL
760 ./Build
761 ./Build test
762 ./Build install
763
764 Or, if you're on a platform (like DOS or Windows) that doesn't like the
765 "./" notation, you can do this:
766
767 perl Build.PL
768 perl Build
769 perl Build test
770 perl Build install
771
772 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
775 perl Build.PL --install_base /home/fred/perl
776
777 as the first step instead.
778
779 This will install the files underneath /home/fred/perl.
780
781 You will then need to make sure that you alter the PERL5LIB variable to
782 find the modules.
783
784 Therefore you will need to change the PERL5LIB variable to add
785 /home/fred/perl/lib
786
787 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
803 This program is free software; you can redistribute it and/or modify it
804 under the same terms as Perl itself.
805
806
807
808perl v5.32.1 2021-01-27 HTML::LinkList(3)