Debian Codegraph @

README

raw
1 NAME
2
3 HTML::LinkList - Create a 'smart' list of HTML links.
4
5 SYNOPSIS
6
7 use HTML::LinkList qw(link_list);
8
9 # default formatting
10 my $html_links = link_list(current_url=>$url,
11 urls=>\@links_in_order,
12 labels=>\%labels,
13 descriptions=>\%desc);
14
15 # paragraph with ' :: ' separators
16 my $html_links = link_list(current_url=>$url,
17 urls=>\@links_in_order,
18 labels=>\%labels,
19 descriptions=>\%desc,
20 links_head=>'<p>',
21 links_foot=>'</p>',
22 pre_item=>'',
23 post_item=>''
24 pre_active_item=>'<em>',
25 post_active_item=>'</em>',
26 item_sep=>" :: ");
27
28 # multi-level list
29 my $html_links = link_tree(
30 current_url=>$url,
31 link_tree=>\@list_of_lists,
32 labels=>\%labels,
33 descriptions=>\%desc);
34
35 DESCRIPTION
36
37 This module contains a number of functions for taking sets of URLs and
38 labels and creating suitably formatted HTML. These links are "smart"
39 because, if given the url of the current page, if any of the links in
40 the list equal it, that item in the list will be formatted as a special
41 label, not as a link; this is a Good Thing, since the user would be
42 confused by clicking on a link back to the current page.
43
44 While many website systems have plugins for "smart" navbars, they are
45 specialized for that system only, and can't be reused elsewhere,
46 forcing people to reinvent the wheel. I hereby present one wheel, free
47 to be reused by anybody; just the simple functions, a backend, which
48 can be plugged into whatever system you want.
49
50 The default format for the HTML is to make an unordered list, but there
51 are many options, enabling one to have a flatter layout with any
52 separators you desire, or a more complicated list with differing
53 formats for different levels.
54
55 The "link_list" function uses a simple list of links -- good for a
56 simple navbar.
57
58 The "link_tree" function takes a set of nested links and makes the HTML
59 for them -- good for making a table of contents, or a more complicated
60 navbar.
61
62 The "full_tree" function takes a list of paths and makes a full tree of
63 all the pages and index-pages in those paths -- good for making a site
64 map.
65
66 The "breadcrumb_trail" function takes a url and makes a "breadcrumb
67 trail" from it.
68
69 The "nav_tree" function creates a set of nested links to be used as a
70 multi-level navbar; one can give it a list of paths (as for full_tree)
71 and it will only show the links related to the current URL.
72
73 FUNCTIONS
74
75 To export a function, add it to the 'use' call.
76
77 use HTML::LinkList qw(link_list);
78
79 To export all functions do:
80
81 use HTML::LinkList ':all';
82
83 link_list
84
85 $links = link_list(
86 current_url=>$url,
87 urls=>\@links_in_order,
88 labels=>\%labels,
89 descriptions=>\%desc,
90 pre_desc=>' ',
91 post_desc=>'',
92 links_head=>'<ul>',
93 links_foot=>'</ul>',
94 pre_item=>'<li>',
95 post_item=>'</li>'
96 pre_active_item=>'<em>',
97 post_active_item=>'</em>',
98 item_sep=>"\n");
99
100 Generates a simple list of links, from list of urls (and optional
101 labels) taking into account of the "current" URL.
102
103 This provides a large number of options to customize the appearance of
104 the list. The default setup is for a simple UL list, but setting the
105 options can enable you to make it something other than a list
106 altogether, or add in CSS styles or classes to make it look just like
107 you want.
108
109 Required:
110
111 urls
112
113 The urls in the order you want them displayed. If this list is empty,
114 then nothing will be generated.
115
116 Options:
117
118 current_url
119
120 The link to the current page. If one of the links equals this, then
121 that is deemed to be the "active" link and is just displayed as a
122 label rather than a link.
123
124 descriptions
125
126 Optional hash of descriptions, to put next to the links. The keys of
127 this hash are the urls.
128
129 hide_ext
130
131 If a site is hiding link extensions (such as using MultiViews with
132 Apache) you may wish to hide the extensions (while using the full
133 URLs to check various things). (default: 0 (false))
134
135 item_sep
136
137 String to put between items.
138
139 labels
140
141 A hash whose keys are links and whose values are labels. These are
142 the labels for the links; if no label is given, then the last part of
143 the link is used for the label, with some formatting.
144
145 links_head
146
147 String to begin the list with.
148
149 links_foot
150
151 String to end the list with.
152
153 pre_desc
154
155 String to prepend to each description.
156
157 post_desc
158
159 String to append to each description.
160
161 pre_item
162
163 String to prepend to each item.
164
165 post_item
166
167 String to append to each item.
168
169 pre_active_item
170
171 An additional string to put in front of each "active" item, after
172 pre_item. The "active" item is the link which matches 'current_url'.
173
174 pre_item_active
175
176 INSTEAD of the "pre_item" string, use this string for active items
177
178 post_active_item
179
180 An additional string to append to each active item, before post_item.
181
182 prefix_url
183
184 A prefix to prepend to all the links. (default: empty string)
185
186 link_tree
187
188 $links = link_tree(
189 current_url=>$url,
190 link_tree=>\@list_of_lists,
191 labels=>\%labels,
192 descriptions=>\%desc,
193 pre_desc=>' ',
194 post_desc=>'',
195 links_head=>'<ul>',
196 links_foot=>'</ul>',
197 subtree_head=>'<ul>',
198 subtree_foot=>'</ul>',
199 pre_item=>'<li>',
200 post_item=>'</li>'
201 pre_active_item=>'<em>',
202 post_active_item=>'</em>',
203 item_sep=>"\n",
204 tree_sep=>"\n",
205 formats=>\%formats);
206
207 Generates nested lists of links from a list of lists of links. This is
208 useful for things such as table-of-contents or site maps.
209
210 By default, this will return UL lists, but this is highly configurable.
211
212 Required:
213
214 link_tree
215
216 A list of lists of urls, in the order you want them displayed. If a
217 url is not in this list, it will not be displayed.
218
219 Options:
220
221 current_url
222
223 The link to the current page. If one of the links equals this, then
224 that is deemed to be the "active" link and is just displayed as a
225 label rather than a link.
226
227 descriptions
228
229 Optional hash of descriptions, to put next to the links. The keys of
230 this hash are the urls.
231
232 exclude_root_parent
233
234 If this is true, then the "current_parent" display options are not
235 used for the "root" ("/") path, it isn't counted as a "parent" of the
236 current_url.
237
238 formats
239
240 A reference to a hash containing advanced format settings. For
241 example:
242
243 my %formats = (
244 # level 1 and onwards
245 '1' => {
246 tree_head=>"<ol>",
247 tree_foot=>"</ol>\n",
248 },
249 # level 2 and onwards
250 '2' => {
251 tree_head=>"<ul>",
252 tree_foot=>"</ul>\n",
253 },
254 # level 3 and onwards
255 '3' => {
256 pre_item=>'(',
257 post_item=>')',
258 item_sep=>",\n",
259 tree_sep=>' -> ',
260 tree_head=>"<br/>\n",
261 tree_foot=>"",
262 }
263 );
264
265 The formats hash enables you to control the formatting on a per-level
266 basis. Each key of the hash corresponds to a level-number; the
267 sub-hashes contain format arguments which will apply from that level
268 onwards. If an argument isn't given in the sub-hash, then it will
269 fall back to the previous level (or to the default, if there is no
270 setting for that format-argument for a previous level).
271
272 The only difference between the names of the arguments in the
273 sub-hash and in the global format arguments is that instead of
274 'subtree_head' and subtree_foot' it uses 'tree_head' and 'tree_foot'.
275
276 hide_ext
277
278 If a site is hiding link extensions (such as using MultiViews with
279 Apache) you may wish to hide the extensions (while using the full
280 URLs to check various things). (default: 0 (false))
281
282 item_sep
283
284 The string to separate each item.
285
286 labels
287
288 A hash whose keys are links and whose values are labels. These are
289 the labels for the links; if no label is given, then the last part of
290 the link is used for the label, with some formatting.
291
292 links_head
293
294 The string to prepend the top-level tree with. (default: <ul>)
295
296 links_foot
297
298 The string to append to the top-level tree. (default: </ul>)
299
300 pre_desc
301
302 String to prepend to each description.
303
304 post_desc
305
306 String to append to each description.
307
308 pre_item
309
310 String to prepend to each item. (default: <li>)
311
312 post_item
313
314 String to append to each item. (default: </li>)
315
316 pre_active_item
317
318 An additional string to put in front of each "active" item, after
319 pre_item. The "active" item is the link which matches 'current_url'.
320 (default: <em>)
321
322 pre_item_active
323
324 INSTEAD of the "pre_item" string, use this string for active items
325
326 post_active_item
327
328 An additional string to append to each active item, before post_item.
329 (default: </em>)
330
331 pre_current_parent
332
333 An additional string to put in front of a link which is a parent of
334 the 'current_url' link, after pre_item.
335
336 pre_item_current_parent
337
338 INSTEAD of the "pre_item" string, use this for links which are
339 parents of the 'current_url' link.
340
341 post_current_parent
342
343 An additional string to append to a link which is a parent of the
344 'current_url' link, before post_item.
345
346 prefix_url
347
348 A prefix to prepend to all the links. (default: empty string)
349
350 subtree_head
351
352 The string to prepend to lower-level trees. (default: <ul>)
353
354 subtree_foot
355
356 The string to append to lower-level trees. (default: </ul>)
357
358 tree_sep
359
360 The string to separate each tree.
361
362 full_tree
363
364 $links = full_tree(
365 paths=>\@list_of_paths,
366 labels=>\%labels,
367 descriptions=>\%desc,
368 hide=>$hide_regex,
369 nohide=>$nohide_regex,
370 start_depth=>0,
371 end_depth=>0,
372 top_level=>0,
373 preserve_order=>0,
374 preserve_paths=>0,
375 ...
376 );
377
378 Given a set of paths this will generate a tree of links in the style of
379 link_tree. This will figure out all the intermediate paths and
380 construct the nested structure for you, clustering parents and children
381 together.
382
383 The formatting options are as for "link_tree".
384
385 Required:
386
387 paths
388
389 A reference to a list of paths: that is, URLs relative to the top of
390 the site.
391
392 For example, if the full URL is http://www.example.com/foo.html then
393 the path is /foo.html
394
395 If the full URL is http://www.example.com/~frednurk/foo.html then the
396 path is /foo.html
397
398 This does not require that every possible path be given; all the
399 intermediate paths will be figured out from the list.
400
401 Options:
402
403 append_list
404
405 Array of paths to append to the top-level links. They are used as-is,
406 and are not part of the processing done to the "paths" list of paths.
407 (see "prepend_list")
408
409 descriptions
410
411 Optional hash of descriptions, to put next to the links. The keys of
412 this hash are the paths.
413
414 end_depth
415
416 End your tree at this depth. If zero, then go all the way. (see
417 "start_depth")
418
419 exclude_root_parent
420
421 If this is true, then the "current_parent" display options are not
422 used for the "root" ("/") path, it isn't counted as a "parent" of the
423 current_url.
424
425 hide
426
427 If the path matches this string, don't include it in the tree.
428
429 hide_ext
430
431 If a site is hiding link extensions (such as using MultiViews with
432 Apache) you may wish to hide the extensions (while using the full
433 URLs to check various things). (default: 0 (false))
434
435 labels
436
437 Hash containing replacement labels for one or more paths. If no label
438 is given for '/' (the root path) then 'Home' will be used.
439
440 last_subtree_head
441
442 The string to prepend to the last lower-level tree. Only used if
443 end_depth is not zero.
444
445 last_subtree_foot
446
447 The string to append to the last lower-level tree. Only used if
448 end_depth is not zero.
449
450 nohide
451
452 If the path matches this string, it will be included even if it
453 matches the 'hide' string.
454
455 prefix_url
456
457 A prefix to prepend to all the links. (default: empty string)
458
459 prepend_list
460
461 Array of paths to prepend to the top-level links. They are used
462 as-is, and are not part of the processing done to the "paths" list of
463 paths.
464
465 preserve_order
466
467 Preserve the ordering of the paths in the input list of paths;
468 otherwise the links will be sorted alphabetically. Note that if
469 preserve_order is true, the structure is at the whims of the order of
470 the original list of paths, and so could end up odd-looking.
471 (default: false)
472
473 preserve_paths
474
475 Do not extract intermediate paths or reorder the input list of paths.
476 This speeds things up, but assumes that the input paths are complete
477 and in good order. (default: false)
478
479 start_depth
480
481 Start your tree at this depth. Zero is the root, level 1 is the
482 files/sub-folders in the root, and so on. (default: 0)
483
484 top_level
485
486 Decide which level is the "top" level. Useful when you set the
487 start_depth to something greater than 1.
488
489 breadcrumb_trail
490
491 $links = breadcrumb_trail(
492 current_url=>$url,
493 labels=>\%labels,
494 descriptions=>\%desc,
495 links_head=>'<p>',
496 links_foot=>"\n</p>",
497 subtree_head=>'',
498 subtree_foot=>"\n",
499 pre_item=>'',
500 post_item=>'',
501 pre_active_item=>'<em>',
502 post_active_item=>'</em>',
503 item_sep=>"\n",
504 tree_sep=>' &gt; ',
505 ...
506 );
507
508 Given the current url, make a breadcrumb trail from it. By default,
509 this is laid out with '>' separators, but it can be set up to give a
510 nested set of UL lists (as for "full_tree").
511
512 The formatting options are as for "link_tree".
513
514 Required:
515
516 current_url
517
518 The current url to be made into a breadcrumb-trail.
519
520 Options:
521
522 descriptions
523
524 Optional hash of descriptions, to put next to the links. The keys of
525 this hash are the urls.
526
527 exclude_root_parent
528
529 If this is true, then the "current_parent" display options are not
530 used for the "root" ("/") path, it isn't counted as a "parent" of the
531 current_url.
532
533 hide_ext
534
535 If a site is hiding link extensions (such as using MultiViews with
536 Apache) you may wish to hide the extensions (while using the full
537 URLs to check various things). (default: 0 (false))
538
539 labels
540
541 Hash containing replacement labels for one or more URLS. If no label
542 is given for '/' (the root path) then 'Home' will be used.
543
544 nav_tree
545
546 $links = nav_tree(
547 paths=>\@list_of_paths,
548 labels=>\%labels,
549 current_url=>$url,
550 hide=>$hide_regex,
551 nohide=>$nohide_regex,
552 preserve_order=>1,
553 descriptions=>\%desc,
554 ...
555 );
556
557 This takes a list of links, and the current URL, and makes a nested
558 navigation tree, consisting of (a) the top-level links (b) the links
559 leading to the current URL (c) the links on the same level as the
560 current URL, (d) the related links just above this level, depending on
561 whether this is an index-page or a content page.
562
563 Optionally one can hide links which match match the 'hide' option.
564
565 The formatting options are as for "link_tree", with some additions.
566
567 Required:
568
569 current_url
570
571 The link to the current page. If one of the links equals this, then
572 that is deemed to be the "active" link and is just displayed as a
573 label rather than a link. This is also used to determine which links
574 to show and which ones to filter out.
575
576 paths
577
578 A reference to a list of paths: that is, URLs relative to the top of
579 the site.
580
581 For example, if the full URL is http://www.example.com/foo.html then
582 the path is /foo.html
583
584 This does not require that every possible path be given; all the
585 intermediate paths will be figured out from the list.
586
587 Options:
588
589 append_list
590
591 Array of paths to append to the top-level links. They are used as-is,
592 and are not part of the processing done to the "paths" list of paths.
593 (see "prepend_list")
594
595 descriptions
596
597 Optional hash of descriptions, to put next to the links. The keys of
598 this hash are the paths.
599
600 end_depth
601
602 End your tree at this depth. If zero, then go all the way. By default
603 this is set to the depth of the current_url.
604
605 exclude_root_parent
606
607 If this is true, then the "current_parent" display options are not
608 used for the "root" ("/") path, it isn't counted as a "parent" of the
609 current_url.
610
611 hide
612
613 If a path matches this string, don't include it in the tree.
614
615 hide_ext
616
617 If a site is hiding link extensions (such as using MultiViews with
618 Apache) you may wish to hide the extensions (while using the full
619 URLs to check various things). (default: 0 (false))
620
621 labels
622
623 Hash containing replacement labels for one or more paths. If no label
624 is given for '/' (the root path) then 'Home' will be used.
625
626 last_subtree_head
627
628 The string to prepend to the last lower-level tree.
629
630 last_subtree_foot
631
632 The string to append to the last lower-level tree.
633
634 nohide
635
636 If the path matches this string, it will be included even if it
637 matches the 'hide' string.
638
639 prefix_url
640
641 A prefix to prepend to all the links. (default: empty string)
642
643 prepend_list
644
645 Array of paths to prepend to the top-level links. They are used
646 as-is, and are not part of the processing done to the "paths" list of
647 paths.
648
649 preserve_order
650
651 Preserve the ordering of the paths in the input list of paths;
652 otherwise the links will be sorted alphabetically. (default: true)
653
654 preserve_paths
655
656 Do not extract intermediate paths or reorder the input list of paths.
657 This speeds things up, but assumes that the input paths are complete
658 and in good order. (default: false)
659
660 start_depth
661
662 Start your tree at this depth. Zero is the root, level 1 is the
663 files/sub-folders in the root, and so on. (default: 1)
664
665 top_level
666
667 Decide which level is the "top" level. Useful when you set the
668 start_depth to something greater than 1.
669
670 Private Functions
671
672 These functions cannot be exported.
673
674 make_item
675
676 $item = make_item( this_label=>$label, this_link=>$link, hide_ext=>0,
677 current_url=>$url, current_parents=>\%current_parents,
678 descriptions=>\%desc, format=>\%format, );
679
680 %format = ( pre_desc=>' ', post_desc=>'', pre_item=>'<li>',
681 post_item=>'</li>' pre_active_item=>'<em>', post_active_item=>'</em>',
682 pre_current_parent=>'<em>', post_current_parent=>'</em>',
683 item_sep=>"\n"); );
684
685 Format a link item.
686
687 See "link_list" for the formatting options.
688
689 this_label
690
691 The label of the required link. If there is no label, this uses the
692 base-name of the last part of the link, capitalizing it and replacing
693 underscores and dashes with spaces.
694
695 this_link
696
697 The URL of the required link.
698
699 current_url
700
701 The link to the current page. If one of the links equals this, then
702 that is deemed to be the "active" link and is just displayed as a
703 label rather than a link.
704
705 current_parents
706
707 URLs of the parents of the current item.
708
709 descriptions
710
711 Optional hash of descriptions, to put next to the links. The keys of
712 this hash are the links (not the labels).
713
714 defer_post_item
715
716 Don't add the 'post_item' string if this is true. (needed for nested
717 lists) (default: false)
718
719 no_link
720
721 Don't make a link for this, just a label.
722
723 make_canonical
724
725 my $new_url = make_canonical($url);
726
727 Make a URL canonical; remove the 'index.*' and add on a needed '/' --
728 this assumes that directory names never have a '.' in them.
729
730 get_index_path
731
732 my $new_url = get_index_path($url);
733
734 Get the "index" part of this path. That is, if this path is not for an
735 index-page, then get the parent index-page path for this path. (Removes
736 the trailing slash).
737
738 get_index_parent
739
740 my $new_url = get_index_parent($url);
741
742 Get the parent of the "index" part of this path. (Removes the trailing
743 slash).
744
745 path_depth
746
747 my $depth = path_depth($url);
748
749 Calculate the "depth" of the given path.
750
751 link_is_active
752
753 if (link_is_active(this_link=>$link, current_url=>$url))
754 ...
755
756 Check if the given link is "active", that is, if it matches the
757 'current_url'.
758
759 traverse_lol
760
761 $links = traverse_lol(\@list_of_lists, labels=>\%labels,
762 tree_depth=>$depth current_format=>\%format, ... );
763
764 Traverse the list of lists (of urls) to produce a nested collection of
765 links.
766
767 This consumes the list_of_lists!
768
769 extract_all_paths
770
771 my @all_paths = extract_all_paths(paths=>\@paths, preserve_order=>0);
772
773 Extract all possible paths out of a list of paths. Thus, if one has
774
775 /foo/bar/baz.html
776
777 then that would make
778
779 / /foo/ /foo/bar/ /foo/bar/baz.html
780
781 If 'preserve_order' is true, this preserves the ordering of the paths
782 in the input list; otherwise the output paths are sorted
783 alphabetically.
784
785 extract_current_parents
786
787 my %current_parents = extract_current_parents(current_url=>$url,
788 exclude_root_parent=>0);
789
790 Extract the "parent" paths of the current url
791
792 /foo/bar/baz.html
793
794 then that would make
795
796 / /foo/ /foo/bar/
797
798 If 'exclude_root_parent' is true, then the '/' is excluded from the
799 list of parents.
800
801 build_lol
802
803 my @lol = build_lol(
804 paths=>\@paths,
805 current_url=>$url,
806 navbar_type=>'',
807 );
808
809 Build a list of lists of paths, given a simple list of paths. Assumes
810 that this list has already been filtered.
811
812 paths
813
814 Reference to list of paths; this is consumed.
815
816 filter_out_paths
817
818 my @filtered_paths = filter_out_paths(
819 paths=>\@paths,
820 current_url=>$url,
821 hide=>$hide,
822 nohide=>$nohide,
823 start_depth=>$start_depth,
824 end_depth=>$end_depth,
825 top_level=>$top_level,
826 navbar_type=>'',
827 );
828
829 Filter out the paths we don't want from our list of paths. Returns a
830 list of the paths we want.
831
832 make_default_format
833
834 my %default_format = make_default_format(%args);
835
836 Make the default format hash from the args. Returns a hash of format
837 options.
838
839 make_extra_formats
840
841 my %formats = make_extra_formats(%args);
842
843 Transforms the subtree_head and subtree_foot into the "formats" method
844 of formatting. Returns a hash of hashes of format options.
845
846 REQUIRES
847
848 Test::More
849
850 INSTALLATION
851
852 To install this module, run the following commands:
853
854 perl Build.PL
855 ./Build
856 ./Build test
857 ./Build install
858
859 Or, if you're on a platform (like DOS or Windows) that doesn't like the
860 "./" notation, you can do this:
861
862 perl Build.PL
863 perl Build
864 perl Build test
865 perl Build install
866
867 In order to install somewhere other than the default, such as in a
868 directory under your home directory, like "/home/fred/perl" go
869
870 perl Build.PL --install_base /home/fred/perl
871
872 as the first step instead.
873
874 This will install the files underneath /home/fred/perl.
875
876 You will then need to make sure that you alter the PERL5LIB variable to
877 find the modules.
878
879 Therefore you will need to change the PERL5LIB variable to add
880 /home/fred/perl/lib
881
882 PERL5LIB=/home/fred/perl/lib:${PERL5LIB}
883
884 SEE ALSO
885
886 perl(1).
887
888 BUGS
889
890 Please report any bugs or feature requests to the author.
891
892 AUTHOR
893
894 Kathryn Andersen (RUBYKAT)
895 perlkat AT katspace dot com
896 http://www.katspace.com/tools/html_linklist/
897
898 COPYRIGHT AND LICENCE
899
900 Copyright (c) 2006 by Kathryn Andersen
901
902 This program is free software; you can redistribute it and/or modify it
903 under the same terms as Perl itself.
904