1HTML::LinkList(3)     User Contributed Perl Documentation    HTML::LinkList(3)
2
3
4

NAME

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

VERSION

9       version 0.1701
10

SYNOPSIS

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

DESCRIPTION

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

FUNCTIONS

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=>' &gt; ',
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

Private Functions

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

REQUIRES

754           Test::More
755

INSTALLATION

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

SEE ALSO

790       perl(1).
791

BUGS

793       Please report any bugs or feature requests to the author.
794

AUTHOR

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.34.0                      2022-01-21                 HTML::LinkList(3)
Impressum