1HTML::LinkList(3) User Contributed Perl Documentation HTML::LinkList(3)
2
6 HTML::LinkList - Create a 'smart' list of HTML links.
7
9 This describes version 0.1503 of HTML::LinkList.
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 post_active_item
165 An additional string to append to each active item, before
166 post_item.
167 prefix_url
169 A prefix to prepend to all the links. (default: empty string)
170 link_tree
172 $links = link_tree(
173 current_url=>$url,
174 link_tree=>\@list_of_lists,
175 labels=>\%labels,
176 descriptions=>\%desc,
177 pre_desc=>' ',
178 post_desc=>'',
179 links_head=>'<ul>',
180 links_foot=>'</ul>',
181 subtree_head=>'<ul>',
182 subtree_foot=>'</ul>',
183 pre_item=>'<li>',
184 post_item=>'</li>'
185 pre_active_item=>'<em>',
186 post_active_item=>'</em>',
187 item_sep=>"\n",
188 tree_sep=>"\n",
189 formats=>\%formats);
190 Generates nested lists of links from a list of lists of links. This is
192 useful for things such as table-of-contents or site maps.
193 By default, this will return UL lists, but this is highly configurable.
195 Required:
197 link_tree
199 A list of lists of urls, in the order you want them displayed. If
200 a url is not in this list, it will not be displayed.
201 Options:
203 current_url
205 The link to the current page. If one of the links equals this,
206 then that is deemed to be the "active" link and is just displayed
207 as a label rather than a link.
208 descriptions
210 Optional hash of descriptions, to put next to the links. The keys
211 of this hash are the urls.
212 exclude_root_parent
214 If this is true, then the "current_parent" display options are not
215 used for the "root" ("/") path, it isn't counted as a "parent" of
216 the current_url.
217 formats
219 A reference to a hash containing advanced format settings. For
220 example:
221 my %formats = (
223 # level 1 and onwards
224 '1' => {
225 tree_head=>"<ol>",
226 tree_foot=>"</ol>\n",
227 },
228 # level 2 and onwards
229 '2' => {
230 tree_head=>"<ul>",
231 tree_foot=>"</ul>\n",
232 },
233 # level 3 and onwards
234 '3' => {
235 pre_item=>'(',
236 post_item=>')',
237 item_sep=>",\n",
238 tree_sep=>' -> ',
239 tree_head=>"<br/>\n",
240 tree_foot=>"",
241 }
242 );
243 The formats hash enables you to control the formatting on a per-
245 level basis. Each key of the hash corresponds to a level-number;
246 the sub-hashes contain format arguments which will apply from that
247 level onwards. If an argument isn't given in the sub-hash, then it
248 will fall back to the previous level (or to the default, if there
249 is no setting for that format-argument for a previous level).
250 The only difference between the names of the arguments in the sub-
252 hash and in the global format arguments is that instead of
253 'subtree_head' and subtree_foot' it uses 'tree_head' and
254 'tree_foot'.
255 hide_ext
257 If a site is hiding link extensions (such as using MultiViews with
258 Apache) you may wish to hide the extensions (while using the full
259 URLs to check various things). (default: 0 (false))
260 item_sep
262 The string to separate each item.
263 labels
265 A hash whose keys are links and whose values are labels. These are
266 the labels for the links; if no label is given, then the last part
267 of the link is used for the label, with some formatting.
268 links_head
270 The string to prepend the top-level tree with. (default: <ul>)
271 links_foot
273 The string to append to the top-level tree. (default: </ul>)
274 pre_desc
276 String to prepend to each description.
277 post_desc
279 String to append to each description.
280 pre_item
282 String to prepend to each item. (default: <li>)
283 post_item
285 String to append to each item. (default: </li>)
286 pre_active_item
288 An additional string to put in front of each "active" item, after
289 pre_item. The "active" item is the link which matches
290 'current_url'. (default: <em>)
291 post_active_item
293 An additional string to append to each active item, before
294 post_item. (default: </em>)
295 pre_current_parent
297 An additional string to put in front of a link which is a parent of
298 the 'current_url' link, after pre_item.
299 post_current_parent
301 An additional string to append to a link which is a parent of the
302 'current_url' link, before post_item.
303 prefix_url
305 A prefix to prepend to all the links. (default: empty string)
306 subtree_head
308 The string to prepend to lower-level trees. (default: <ul>)
309 subtree_foot
311 The string to append to lower-level trees. (default: </ul>)
312 tree_sep
314 The string to separate each tree.
315 full_tree
317 $links = full_tree(
318 paths=>\@list_of_paths,
319 labels=>\%labels,
320 descriptions=>\%desc,
321 hide=>$hide_regex,
322 nohide=>$nohide_regex,
323 start_depth=>0,
324 end_depth=>0,
325 top_level=>0,
326 preserve_order=>0,
327 preserve_paths=>0,
328 ...
329 );
330 Given a set of paths this will generate a tree of links in the style of
332 link_tree. This will figure out all the intermediate paths and
333 construct the nested structure for you, clustering parents and children
334 together.
335 The formatting options are as for "link_tree".
337 Required:
339 paths
341 A reference to a list of paths: that is, URLs relative to the top
342 of the site.
343 For example, if the full URL is http://www.example.com/foo.html
345 then the path is /foo.html
346 If the full URL is http://www.example.com/~frednurk/foo.html then
348 the path is /foo.html
349 This does not require that every possible path be given; all the
351 intermediate paths will be figured out from the list.
352 Options:
354 append_list
356 Array of paths to append to the top-level links. They are used as-
357 is, and are not part of the processing done to the "paths" list of
358 paths. (see "prepend_list")
359 descriptions
361 Optional hash of descriptions, to put next to the links. The keys
362 of this hash are the paths.
363 end_depth
365 End your tree at this depth. If zero, then go all the way. (see
366 "start_depth")
367 exclude_root_parent
369 If this is true, then the "current_parent" display options are not
370 used for the "root" ("/") path, it isn't counted as a "parent" of
371 the current_url.
372 hide
374 If the path matches this string, don't include it in the tree.
375 hide_ext
377 If a site is hiding link extensions (such as using MultiViews with
378 Apache) you may wish to hide the extensions (while using the full
379 URLs to check various things). (default: 0 (false))
380 labels
382 Hash containing replacement labels for one or more paths. If no
383 label is given for '/' (the root path) then 'Home' will be used.
384 last_subtree_head
386 The string to prepend to the last lower-level tree. Only used if
387 end_depth is not zero.
388 last_subtree_foot
390 The string to append to the last lower-level tree. Only used if
391 end_depth is not zero.
392 nohide
394 If the path matches this string, it will be included even if it
395 matches the 'hide' string.
396 prefix_url
398 A prefix to prepend to all the links. (default: empty string)
399 prepend_list
401 Array of paths to prepend to the top-level links. They are used
402 as-is, and are not part of the processing done to the "paths" list
403 of paths.
404 preserve_order
406 Preserve the ordering of the paths in the input list of paths;
407 otherwise the links will be sorted alphabetically. Note that if
408 preserve_order is true, the structure is at the whims of the order
409 of the original list of paths, and so could end up odd-looking.
410 (default: false)
411 preserve_paths
413 Do not extract intermediate paths or reorder the input list of
414 paths. This speeds things up, but assumes that the input paths are
415 complete and in good order. (default: false)
416 start_depth
418 Start your tree at this depth. Zero is the root, level 1 is the
419 files/sub-folders in the root, and so on. (default: 0)
420 top_level
422 Decide which level is the "top" level. Useful when you set the
423 start_depth to something greater than 1.
424 breadcrumb_trail
426 $links = breadcrumb_trail(
427 current_url=>$url,
428 labels=>\%labels,
429 descriptions=>\%desc,
430 links_head=>'<p>',
431 links_foot=>"\n</p>",
432 subtree_head=>'',
433 subtree_foot=>"\n",
434 pre_item=>'',
435 post_item=>'',
436 pre_active_item=>'<em>',
437 post_active_item=>'</em>',
438 item_sep=>"\n",
439 tree_sep=>' > ',
440 ...
441 );
442 Given the current url, make a breadcrumb trail from it. By default,
444 this is laid out with '>' separators, but it can be set up to give a
445 nested set of UL lists (as for "full_tree").
446 The formatting options are as for "link_tree".
448 Required:
450 current_url
452 The current url to be made into a breadcrumb-trail.
453 Options:
455 descriptions
457 Optional hash of descriptions, to put next to the links. The keys
458 of this hash are the urls.
459 exclude_root_parent
461 If this is true, then the "current_parent" display options are not
462 used for the "root" ("/") path, it isn't counted as a "parent" of
463 the current_url.
464 hide_ext
466 If a site is hiding link extensions (such as using MultiViews with
467 Apache) you may wish to hide the extensions (while using the full
468 URLs to check various things). (default: 0 (false))
469 labels
471 Hash containing replacement labels for one or more URLS. If no
472 label is given for '/' (the root path) then 'Home' will be used.
473 nav_tree
475 $links = nav_tree(
476 paths=>\@list_of_paths,
477 labels=>\%labels,
478 current_url=>$url,
479 hide=>$hide_regex,
480 nohide=>$nohide_regex,
481 preserve_order=>1,
482 descriptions=>\%desc,
483 ...
484 );
485 This takes a list of links, and the current URL, and makes a nested
487 navigation tree, consisting of (a) the top-level links (b) the links
488 leading to the current URL (c) the links on the same level as the
489 current URL, (d) the related links just above this level, depending on
490 whether this is an index-page or a content page.
491 Optionally one can hide links which match match the 'hide' option.
493 The formatting options are as for "link_tree", with some additions.
495 Required:
497 current_url
499 The link to the current page. If one of the links equals this,
500 then that is deemed to be the "active" link and is just displayed
501 as a label rather than a link. This is also used to determine
502 which links to show and which ones to filter out.
503 paths
505 A reference to a list of paths: that is, URLs relative to the top
506 of the site.
507 For example, if the full URL is http://www.example.com/foo.html
509 then the path is /foo.html
510 This does not require that every possible path be given; all the
512 intermediate paths will be figured out from the list.
513 Options:
515 append_list
517 Array of paths to append to the top-level links. They are used as-
518 is, and are not part of the processing done to the "paths" list of
519 paths. (see "prepend_list")
520 descriptions
522 Optional hash of descriptions, to put next to the links. The keys
523 of this hash are the paths.
524 end_depth
526 End your tree at this depth. If zero, then go all the way. By
527 default this is set to the depth of the current_url.
528 exclude_root_parent
530 If this is true, then the "current_parent" display options are not
531 used for the "root" ("/") path, it isn't counted as a "parent" of
532 the current_url.
533 hide
535 If a path matches this string, don't include it in the tree.
536 hide_ext
538 If a site is hiding link extensions (such as using MultiViews with
539 Apache) you may wish to hide the extensions (while using the full
540 URLs to check various things). (default: 0 (false))
541 labels
543 Hash containing replacement labels for one or more paths. If no
544 label is given for '/' (the root path) then 'Home' will be used.
545 last_subtree_head
547 The string to prepend to the last lower-level tree.
548 last_subtree_foot
550 The string to append to the last lower-level tree.
551 nohide
553 If the path matches this string, it will be included even if it
554 matches the 'hide' string.
555 prefix_url
557 A prefix to prepend to all the links. (default: empty string)
558 prepend_list
560 Array of paths to prepend to the top-level links. They are used
561 as-is, and are not part of the processing done to the "paths" list
562 of paths.
563 preserve_order
565 Preserve the ordering of the paths in the input list of paths;
566 otherwise the links will be sorted alphabetically. (default: true)
567 preserve_paths
569 Do not extract intermediate paths or reorder the input list of
570 paths. This speeds things up, but assumes that the input paths are
571 complete and in good order. (default: false)
572 start_depth
574 Start your tree at this depth. Zero is the root, level 1 is the
575 files/sub-folders in the root, and so on. (default: 1)
576 top_level
578 Decide which level is the "top" level. Useful when you set the
579 start_depth to something greater than 1.
580
582 These functions cannot be exported.
583 make_item
585 $item = make_item( this_label=>$label, this_link=>$link,
586 hide_ext=>0, current_url=>$url,
587 current_parents=>\%current_parents, descriptions=>\%desc,
588 format=>\%format,
589 );
590 %format = ( pre_desc=>' ', post_desc=>'',
592 pre_item=>'<li>', post_item=>'</li>'
593 pre_active_item=>'<em>', post_active_item=>'</em>',
594 pre_current_parent=>'<em>', post_current_parent=>'</em>',
595 item_sep=>"\n"); );
596 Format a link item.
598 See "link_list" for the formatting options.
600 this_label
602 The label of the required link. If there is no label, this uses
603 the base-name of the last part of the link, capitalizing it and
604 replacing underscores and dashes with spaces.
605 this_link
607 The URL of the required link.
608 current_url
610 The link to the current page. If one of the links equals this,
611 then that is deemed to be the "active" link and is just displayed
612 as a label rather than a link.
613 current_parents
615 URLs of the parents of the current item.
616 descriptions
618 Optional hash of descriptions, to put next to the links. The keys
619 of this hash are the links (not the labels).
620 defer_post_item
622 Don't add the 'post_item' string if this is true. (needed for
623 nested lists) (default: false)
624 no_link
626 Don't make a link for this, just a label.
627 make_canonical
629 my $new_url = make_canonical($url);
630 Make a URL canonical; remove the 'index.*' and add on a needed '/' --
632 this assumes that directory names never have a '.' in them.
633 get_index_path
635 my $new_url = get_index_path($url);
636 Get the "index" part of this path. That is, if this path is not for an
638 index-page, then get the parent index-page path for this path.
639 (Removes the trailing slash).
640 get_index_parent
642 my $new_url = get_index_parent($url);
643 Get the parent of the "index" part of this path. (Removes the trailing
645 slash).
646 path_depth
648 my $depth = path_depth($url);
649 Calculate the "depth" of the given path.
651 link_is_active
653 if (link_is_active(this_link=>$link, current_url=>$url))
654 ...
655 Check if the given link is "active", that is, if it matches the
657 'current_url'.
658 traverse_lol
660 $links = traverse_lol(\@list_of_lists,
661 labels=>\%labels,
662 tree_depth=>$depth
663 current_format=>\%format,
664 ...
665 );
666 Traverse the list of lists (of urls) to produce a nested collection of
668 links.
669 This consumes the list_of_lists!
671 extract_all_paths
673 my @all_paths = extract_all_paths(paths=>\@paths,
674 preserve_order=>0);
675 Extract all possible paths out of a list of paths. Thus, if one has
677 /foo/bar/baz.html
679 then that would make
681 / /foo/ /foo/bar/ /foo/bar/baz.html
683 If 'preserve_order' is true, this preserves the ordering of the paths
685 in the input list; otherwise the output paths are sorted
686 alphabetically.
687 extract_current_parents
689 my %current_parents = extract_current_parents(current_url=>$url,
690 exclude_root_parent=>0);
691 Extract the "parent" paths of the current url
693 /foo/bar/baz.html
695 then that would make
697 / /foo/ /foo/bar/
699 If 'exclude_root_parent' is true, then the '/' is excluded from the
701 list of parents.
702 build_lol
704 my @lol = build_lol(
705 paths=>\@paths,
706 current_url=>$url,
707 navbar_type=>'',
708 );
709 Build a list of lists of paths, given a simple list of paths. Assumes
711 that this list has already been filtered.
712 paths
714 Reference to list of paths; this is consumed.
715 filter_out_paths
717 my @filtered_paths = filter_out_paths(
718 paths=>\@paths,
719 current_url=>$url,
720 hide=>$hide,
721 nohide=>$nohide,
722 start_depth=>$start_depth,
723 end_depth=>$end_depth,
724 top_level=>$top_level,
725 navbar_type=>'',
726 );
727 Filter out the paths we don't want from our list of paths. Returns a
729 list of the paths we want.
730 make_default_format
732 my %default_format = make_default_format(%args);
733 Make the default format hash from the args. Returns a hash of format
735 options.
736 make_extra_formats
738 my %formats = make_extra_formats(%args);
739 Transforms the subtree_head and subtree_foot into the "formats" method
741 of formatting. Returns a hash of hashes of format options.
742
744 Test::More
745
747 To install this module, run the following commands:
748 perl Build.PL
750 ./Build
751 ./Build test
752 ./Build install
753 Or, if you're on a platform (like DOS or Windows) that doesn't like the
755 "./" notation, you can do this:
756 perl Build.PL
758 perl Build
759 perl Build test
760 perl Build install
761 In order to install somewhere other than the default, such as in a
763 directory under your home directory, like "/home/fred/perl" go
764 perl Build.PL --install_base /home/fred/perl
766 as the first step instead.
768 This will install the files underneath /home/fred/perl.
770 You will then need to make sure that you alter the PERL5LIB variable to
772 find the modules.
773 Therefore you will need to change the PERL5LIB variable to add
775 /home/fred/perl/lib
776 PERL5LIB=/home/fred/perl/lib:${PERL5LIB}
778
780 perl(1).
781
783 Please report any bugs or feature requests to the author.
784
786 Kathryn Andersen (RUBYKAT)
787 perlkat AT katspace dot com
788 http://www.katspace.com/tools/html_linklist/
789
791 Copyright (c) 2006 by Kathryn Andersen
792 This program is free software; you can redistribute it and/or modify it
794 under the same terms as Perl itself.
795perl v5.12.0 2008-09-07 HTML::LinkList(3)