]> iEval git - html-element-library.git/blob - lib/HTML/Element/Library.pod
Tidy POD
[html-element-library.git] / lib / HTML / Element / Library.pod
1 =encoding utf-8
2
3 =head1 NAME
4
5 HTML::Element::Library - HTML::Element convenience functions
6
7 =head1 SYNOPSIS
8
9 use HTML::Element::Library;
10 use HTML::TreeBuilder;
11
12 =head1 DESCRIPTION
13
14 This method provides API calls for common actions on trees when using
15 L<HTML::Tree>.
16
17 =head1 METHODS
18
19 The test suite contains examples of each of these methods in a file
20 C<t/$method.t>
21
22 =head2 Positional Querying Methods
23
24 =head3 $elem->siblings
25
26 Return a list of all nodes under the same parent.
27
28 =head3 $elem->sibdex
29
30 Return the index of C<$elem> into the array of siblings of which it is
31 a part. L<HTML::ElementSuper> calls this method C<addr> but I don't
32 think that is a descriptive name. And such naming is deceptively close
33 to the C<address> function of C<HTML::Element>. HOWEVER, in the
34 interest of backwards compatibility, both methods are available.
35
36 =head3 $elem->addr
37
38 Same as sibdex
39
40 =head3 $elem->position()
41
42 Returns the coordinates of this element in the tree it inhabits. This
43 is accomplished by succesively calling addr() on ancestor elements
44 until either a) an element that does not support these methods is
45 found, or b) there are no more parents. The resulting list is the
46 n-dimensional coordinates of the element in the tree.
47
48 =head2 Element Decoration Methods
49
50 =head3 HTML::Element::Library::super_literal($text)
51
52 In L<HTML::Element>, Sean Burke discusses super-literals. They are
53 text which does not get escaped. Great for includng Javascript in
54 HTML. Also great for including foreign language into a document.
55
56 So, you basically toss C<super_literal> your text and back comes your
57 text wrapped in a C<~literal> element.
58
59 One of these days, I'll around to writing a nice C<EXPORT> section.
60
61 =head2 Tree Rewriting Methods
62
63 =head3 "de-prepping" HTML
64
65 Oftentimes, the HTML to be worked with will have multiple sample rows:
66
67 <OL>
68 <LI>bread
69 <LI>butter
70 <LI>beer
71 <LI>bacon
72 </OL>
73
74 But, before you begin to rewrite the HTML with your model data, you
75 typically only want 1 or 2 sample rows.
76
77 Thus, you want to "crunch" the multiple sample rows to a specified
78 amount. Hence the C<crunch> method:
79
80 $tree->crunch(look_down => [ '_tag' => 'li' ], leave => 2) ;
81
82 The C<leave> argument defaults to 1 if not given. The call above would
83 "crunch" the above 4 sample rows to:
84
85 <OL>
86 <LI>bread
87 <LI>butter
88 </OL>
89
90 =head3 Simplifying calls to HTML::FillInForm
91
92 Since HTML::FillInForm gets and returns strings, using HTML::Element
93 instances becomes tedious:
94
95 1. Seamstress has an HTML tree that it wants the form filled in on
96 2. Seamstress converts this tree to a string
97 3. FillInForm parses the string into an HTML tree and then fills in the form
98 4. FillInForm converts the HTML tree to a string
99 5. Seamstress re-parses the HTML for additional processing
100
101 I've filed a bug about this:
102 L<https://rt.cpan.org/Ticket/Display.html?id=44105>
103
104 This function, fillinform, allows you to pass a tree to fillinform
105 (along with your data structure) and get back a tree:
106
107 my $new_tree = $html_tree->fillinform($data_structure);
108
109 =head3 Mapping a hashref to HTML elements
110
111 It is very common to get a hashref of data from some external source -
112 flat file, database, XML, etc. Therefore, it is important to have a
113 convenient way of mapping this data to HTML.
114
115 As it turns out, there are 3 ways to do this in
116 HTML::Element::Library. The most strict and structured way to do this
117 is with C<content_handler>. Two other methods, C<hashmap> and
118 C<datamap> require less manual mapping and may prove even more easy to
119 use in certain cases.
120
121 As is usual with Perl, a practical example is always best. So let's
122 take some sample HTML:
123
124 <h1>user data</h1>
125 <span id="name">?</span>
126 <span id="email">?</span>
127 <span id="gender">?</span>
128
129 Now, let's say our data structure is this:
130
131 $ref = { email => 'jim@beam.com', gender => 'lots' } ;
132
133 And let's start with the most strict way to get what you want:
134
135 $tree->content_handler(email => $ref->{email} , gender => $ref->{gender}) ;
136
137 In this case, you manually state the mapping between id tags and
138 hashref keys and then C<content_handler> retrieves the hashref data
139 and pops it in the specified place.
140
141 Now let's look at the two (actually 2 and a half) other hash-mapping
142 methods.
143
144 $tree->hashmap(id => $ref);
145
146 Now, what this function does is super-destructive. It finds every
147 element in the tree with an attribute named id (since 'id' is a
148 parameter, it could find every element with some other attribute also)
149 and replaces the content of those elements with the hashref value.
150
151 So, in the case above, the
152
153 <span id="name">?</span>
154
155 would come out as
156
157 <span id="name"></span>
158
159 (it would be blank) - because there is nothing in the hash with that
160 value, so it substituted
161
162 $ref->{name}
163
164 which was blank and emptied the contents.
165
166 Now, let's assume we want to protect name from being auto-assigned.
167 Here is what you do:
168
169 $tree->hashmap(id => $ref, ['name']);
170
171 That last array ref is an exclusion list.
172
173 But wouldnt it be nice if you could do a hashmap, but only assigned
174 things which are defined in the hashref? C<< defmap() >> to the
175 rescue:
176
177 $tree->defmap(id => $ref);
178
179 does just that, so
180
181 <span id="name">?</span>
182
183 would be left alone.
184
185 =head4 $elem->hashmap($attr_name, \%hashref, \@excluded, $debug)
186
187 This method is designed to take a hashref and populate a series of
188 elements. For example:
189
190 <table>
191 <tr sclass="tr" class="alt" align="left" valign="top">
192 <td smap="people_id">1</td>
193 <td smap="phone">(877) 255-3239</td>
194 <td smap="password">*********</td>
195 </tr>
196 </table>
197
198 In the table above, there are several attributes named C<< smap >>. If
199 we have a hashref whose keys are the same:
200
201 my %data = (people_id => 888, phone => '444-4444', password => 'dont-you-dare-render');
202
203 Then a single API call allows us to populate the HTML while excluding
204 those ones we dont:
205
206 $tree->hashmap(smap => \%data, ['password']);
207
208 Note: the other way to prevent rendering some of the hash mapping is
209 to not give that element the attr you plan to use for hash mapping.
210
211 Also note: the function C<< hashmap >> has a simple easy-to-type API.
212 Interally, it calls C<< hash_map >> (which has a more verbose keyword
213 calling API). Thus, the above call to C<hashmap()> results in this
214 call:
215
216 $tree->hash_map(hash => \%data, to_attr => 'sid', excluding => ['password']);
217
218 =head4 $elem->defmap($attr_name, \%hashref, $debug)
219
220 C<defmap> was described above.
221
222 =head3 $elem->replace_content(@new_elem)
223
224 Replaces all of C<$elem>'s content with C<@new_elem>.
225
226 =head3 $elem->wrap_content($wrapper_element)
227
228 Wraps the existing content in the provided element. If the provided
229 element happens to be a non-element, a push_content is performed
230 instead.
231
232 =head3 $elem->set_child_content(@look_down, $content)
233
234 This method looks down $tree using the criteria specified in
235 @look_down using the the HTML::Element look_down() method.
236
237 After finding the node, it detaches the node's content and pushes
238 $content as the node's content.
239
240 =head3 $tree->content_handler(%id_content)
241
242 This is a convenience method. Because the look_down criteria will
243 often simply be:
244
245 id => 'fixme'
246
247 to find things like:
248
249 <a id=fixme href=http://www.somesite.org>replace_content</a>
250
251 You can call this method to shorten your typing a bit. You can simply
252 type
253
254 $elem->content_handler( fixme => 'new text' )
255
256 Instead of typing:
257
258 $elem->set_child_content(sid => 'fixme', 'new text')
259
260 ALSO NOTE: you can pass a hash whose keys are C<id>s and whose values
261 are the content you want there and it will perform the replacement on
262 each hash member:
263
264 my %id_content = (name => "Terrence Brannon",
265 email => 'tbrannon@in.com',
266 balance => 666,
267 content => $main_content);
268 $tree->content_handler(%id_content);
269
270 =head3 $tree->highlander($subtree_span_id, $conditionals, @conditionals_args)
271
272 This allows for "if-then-else" style processing. Highlander was a
273 movie in which only one would survive. Well, in terms of a tree when
274 looking at a structure that you want to process in C<if-then-else>
275 style, only one child will survive. For example, given this HTML
276 template:
277
278 <span klass="highlander" id="age_dialog">
279 <span id="under10">
280 Hello, does your mother know you're
281 using her AOL account?
282 </span>
283 <span id="under18">
284 Sorry, you're not old enough to enter
285 (and too dumb to lie about your age)
286 </span>
287 <span id="welcome">
288 Welcome
289 </span>
290 </span>
291
292 We only want one child of the C<span> tag with id C<age_dialog> to
293 remain based on the age of the person visiting the page.
294
295 So, let's setup a call that will prune the subtree as a function of
296 age:
297
298 sub process_page {
299 my $age = shift;
300 my $tree = HTML::TreeBuilder->new_from_file('t/html/highlander.html');
301
302 $tree->highlander
303 (age_dialog =>
304 [
305 under10 => sub { $_[0] < 10},
306 under18 => sub { $_[0] < 18},
307 welcome => sub { 1 }
308 ],
309 $age
310 );
311
312 And there we have it. If the age is less than 10, then the node with
313 id C<under10> remains. For age less than 18, the node with id
314 C<under18> remains. Otherwise our "else" condition fires and the child
315 with id C<welcome> remains.
316
317 =head3 $tree->passover(@id_of_element)
318
319 In some cases, you know exactly which element(s) should survive. In
320 this case, you can simply call C<passover> to remove it's (their)
321 siblings. For the HTML above, you could delete C<under10> and
322 C<welcome> by simply calling:
323
324 $tree->passover('under18');
325
326 Because passover takes an array, you can specify several children to
327 preserve.
328
329 =head3 $tree->highlander2($tree, $conditionals, @conditionals_args)
330
331 Right around the same time that C<table2()> came into being,
332 Seamstress began to tackle tougher and tougher processing problems. It
333 became clear that a more powerful highlander was needed... one that
334 not only snipped the tree of the nodes that should not survive, but
335 one that allows for post-processing of the survivor node. And one that
336 was more flexible with how to find the nodes to snip.
337
338 Thus (drum roll) C<highlander2()>.
339
340 So let's look at our HTML which requires post-selection processing:
341
342 <span klass="highlander" id="age_dialog">
343 <span id="under10">
344 Hello, little <span id=age>AGE</span>-year old,
345 does your mother know you're using her AOL account?
346 </span>
347 <span id="under18">
348 Sorry, you're only <span id=age>AGE</span>
349 (and too dumb to lie about your age)
350 </span>
351 <span id="welcome">
352 Welcome, isn't it good to be <span id=age>AGE</span> years old?
353 </span>
354 </span>
355
356 In this case, a branch survives, but it has dummy data in it. We must
357 take the surviving segment of HTML and rewrite the age C<span> with
358 the age. Here is how we use C<highlander2()> to do so:
359
360 sub replace_age {
361 my $branch = shift;
362 my $age = shift;
363 $branch->look_down(id => 'age')->replace_content($age);
364 }
365
366 my $if_then = $tree->look_down(id => 'age_dialog');
367
368 $if_then->highlander2(
369 cond => [
370 under10 => [
371 sub { $_[0] < 10} ,
372 \&replace_age
373 ],
374 under18 => [
375 sub { $_[0] < 18} ,
376 \&replace_age
377 ],
378 welcome => [
379 sub { 1 },
380 \&replace_age
381 ]
382 ],
383 cond_arg => [ $age ]
384 );
385
386 We pass it the tree (C<$if_then>), an arrayref of conditions (C<cond>)
387 and an arrayref of arguments which are passed to the C<cond>s and to
388 the replacement subs.
389
390 The C<under10>, C<under18> and C<welcome> are id attributes in the
391 tree of the siblings of which only one will survive. However, should
392 you need to do more complex look-downs to find the survivor, then
393 supply an array ref instead of a simple scalar:
394
395 $if_then->highlander2(
396 cond => [
397 [class => 'r12'] => [
398 sub { $_[0] < 10} ,
399 \&replace_age
400 ],
401 [class => 'z22'] => [
402 sub { $_[0] < 18} ,
403 \&replace_age
404 ],
405 [class => 'w88'] => [
406 sub { 1 },
407 \&replace_age
408 ]
409 ],
410 cond_arg => [ $age ]
411 );
412
413 =head3 $tree->overwrite_attr($mutation_attr => $mutating_closures)
414
415 This method is designed for taking a tree and reworking a set of nodes
416 in a stereotyped fashion. For instance let's say you have 3 remote
417 image archives, but you don't want to put long URLs in your img src
418 tags for reasons of abstraction, re-use and brevity. So instead you do
419 this:
420
421 <img src="/img/smiley-face.jpg" fixup="src lnc">
422 <img src="/img/hot-babe.jpg" fixup="src playboy">
423 <img src="/img/footer.jpg" fixup="src foobar">
424
425 and then when the tree of HTML is being processed, you make this call:
426
427 my %closures = (
428 lnc => sub { my ($tree, $mute_node, $attr_value)= @_; "http://lnc.usc.edu$attr_value" },
429 playboy => sub { my ($tree, $mute_node, $attr_value)= @_; "http://playboy.com$attr_value" }
430 foobar => sub { my ($tree, $mute_node, $attr_value)= @_; "http://foobar.info$attr_value" }
431 )
432
433 $tree->overwrite_attr(fixup => \%closures) ;
434
435 and the tags come out modified like so:
436
437 <img src="http://lnc.usc.edu/img/smiley-face.jpg" fixup="src lnc">
438 <img src="http://playboy.com/img/hot-babe.jpg" fixup="src playboy">
439 <img src="http://foobar.info/img/footer.jpg" fixup="src foobar">
440
441 =head3 $tree->mute_elem($mutation_attr => $mutating_closures, [ $post_hook ] )
442
443 This is a generalization of C<overwrite_attr>. C<overwrite_attr>
444 assumes the return value of the closure is supposed overwrite an
445 attribute value and does it for you. C<mute_elem> is a more general
446 function which does nothing but hand the closure the element and let
447 it mutate it as it jolly well pleases :)
448
449 In fact, here is the implementation of C<overwrite_attr> to give you a
450 taste of how C<mute_attr> is used:
451
452 sub overwrite_action {
453 my ($mute_node, %X) = @_;
454
455 $mute_node->attr($X{local_attr}{name} => $X{local_attr}{value}{new});
456 }
457
458
459 sub HTML::Element::overwrite_attr {
460 my $tree = shift;
461
462 $tree->mute_elem(@_, \&overwrite_action);
463 }
464
465 =head2 Tree-Building Methods
466
467 =head3 Unrolling an array via a single sample element (<ul> container)
468
469 This is best described by example. Given this HTML:
470
471 <strong>Here are the things I need from the store:</strong>
472 <ul>
473 <li class="store_items">Sample item</li>
474 </ul>
475
476 We can unroll it like so:
477
478 my $li = $tree->look_down(class => 'store_items');
479
480 my @items = qw(bread butter vodka);
481
482 $tree->iter($li => @items);
483
484 To produce this:
485
486 <html>
487 <head></head>
488 <body>Here are the things I need from the store:
489 <ul>
490 <li class="store_items">bread</li>
491 <li class="store_items">butter</li>
492 <li class="store_items">vodka</li>
493 </ul>
494 </body>
495 </html>
496
497 Now, you might be wondering why the API call is:
498
499 $tree->iter($li => @items)
500
501 instead of:
502
503 $li->iter(@items)
504
505 and there is no good answer. The latter would be more concise and it
506 is what I should have done.
507
508 =head3 Unrolling an array via n sample elements (<dl> container)
509
510 C<iter()> was fine for awhile, but some things (e.g. definition lists)
511 need a more general function to make them easy to do. Hence
512 C<iter2()>. This function will be explained by example of unrolling a
513 simple definition list.
514
515 So here's our mock-up HTML from the designer:
516
517 <dl class="dual_iter" id="service_plan">
518 <dt>Artist</dt>
519 <dd>A person who draws blood.</dd>
520
521 <dt>Musician</dt>
522 <dd>A clone of Iggy Pop.</dd>
523
524 <dt>Poet</dt>
525 <dd>A relative of Edgar Allan Poe.</dd>
526
527 <dt class="adstyle">sample header</dt>
528 <dd class="adstyle2">sample data</dd>
529 </dl>
530
531
532 And we want to unroll our data set:
533
534 my @items = (
535 ['the pros' => 'never have to worry about service again'],
536 ['the cons' => 'upfront extra charge on purchase'],
537 ['our choice' => 'go with the extended service plan']
538 );
539
540
541 Now, let's make this problem a bit harder to show off the power of
542 C<iter2()>. Let's assume that we want only the last <dt> and it's
543 accompanying <dd> (the one with "sample data") to be used as the
544 sample data for unrolling with our data set. Let's further assume that
545 we want them to remain in the final output.
546
547 So now, the API to C<iter2()> will be discussed and we will explain
548 how our goal of getting our data into HTML fits into the API.
549
550 =over 4
551
552 =item * wrapper_ld
553
554 This is how to look down and find the container of all the elements we
555 will be unrolling. The <dl> tag is the container for the dt and dd
556 tags we will be unrolling.
557
558 If you pass an anonymous subroutine, then it is presumed that
559 execution of this subroutine will return the HTML::Element
560 representing the container tag. If you pass an array ref, then this
561 will be dereferenced and passed to C<HTML::Element::look_down()>.
562
563 default value: C<< ['_tag' => 'dl'] >>
564
565 Based on the mock HTML above, this default is fine for finding our
566 container tag. So let's move on.
567
568 =item * wrapper_data
569
570 This is an array reference of data that we will be putting into the
571 container. You must supply this. C<@items> above is our
572 C<wrapper_data>.
573
574 =item * wrapper_proc
575
576 After we find the container via C<wrapper_ld>, we may want to
577 pre-process some aspect of this tree. In our case the first two sets
578 of dt and dd need to be removed, leaving the last dt and dd. So, we
579 supply a C<wrapper_proc> which will do this.
580
581 default: undef
582
583 =item * item_ld
584
585 This anonymous subroutine returns an array ref of C<HTML::Element>s
586 that will be cloned and populated with item data (item data is a "row"
587 of C<wrapper_data>).
588
589 default: returns an arrayref consisting of the dt and dd element
590 inside the container.
591
592 =item * item_data
593
594 This is a subroutine that takes C<wrapper_data> and retrieves one
595 "row" to be "pasted" into the array ref of C<HTML::Element>s found via
596 C<item_ld>. I hope that makes sense.
597
598 default: shifts C<wrapper_data>.
599
600 =item * item_proc
601
602 This is a subroutine that takes the C<item_data> and the
603 C<HTML::Element>s found via C<item_ld> and produces an arrayref of
604 C<HTML::Element>s which will eventually be spliced into the container.
605
606 Note that this subroutine MUST return the new items. This is done So
607 that more items than were passed in can be returned. This is useful
608 when, for example, you must return 2 dts for an input data item. And
609 when would you do this? When a single term has multiple spellings for
610 instance.
611
612 default: expects C<item_data> to be an arrayref of two elements and
613 C<item_elems> to be an arrayref of two C<HTML::Element>s. It replaces
614 the content of the C<HTML::Element>s with the C<item_data>.
615
616 =item * splice
617
618 After building up an array of C<@item_elems>, the subroutine passed as
619 C<splice> will be given the parent container HTML::Element and the
620 C<@item_elems>. How the C<@item_elems> end up in the container is up
621 to this routine: it could put half of them in. It could unshift them
622 or whatever.
623
624 default: C<< $container->splice_content(0, 2, @item_elems) >> In other
625 words, kill the 2 sample elements with the newly generated @item_elems
626
627 =back
628
629 So now that we have documented the API, let's see the call we need:
630
631 $tree->iter2(
632 # default wrapper_ld ok.
633 wrapper_data => \@items,
634 wrapper_proc => sub {
635 my ($container) = @_;
636
637 # only keep the last 2 dts and dds
638 my @content_list = $container->content_list;
639 $container->splice_content(0, @content_list - 2);
640 },
641
642 # default item_ld is fine.
643 # default item_data is fine.
644 # default item_proc is fine.
645 splice => sub {
646 my ($container, @item_elems) = @_;
647 $container->unshift_content(@item_elems);
648 },
649 debug => 1,
650 );
651
652 =head3 Select Unrolling
653
654 The C<unroll_select> method has this API:
655
656 $tree->unroll_select(
657 select_label => $id_label,
658 option_value => $closure, # how to get option value from data row
659 option_content => $closure, # how to get option content from data row
660 option_selected => $closure, # boolean to decide if SELECTED
661 data => $data # the data to be put into the SELECT
662 data_iter => $closure # the thing that will get a row of data
663 debug => $boolean,
664 append => $boolean, # remove the sample <OPTION> data or append?
665 );
666
667 Here's an example:
668
669 $tree->unroll_select(
670 select_label => 'clan_list',
671 option_value => sub { my $row = shift; $row->clan_id },
672 option_content => sub { my $row = shift; $row->clan_name },
673 option_selected => sub { my $row = shift; $row->selected },
674 data => \@query_results,
675 data_iter => sub { my $data = shift; $data->next },
676 append => 0,
677 debug => 0
678 );
679
680 =head2 Tree-Building Methods: Table Generation
681
682 Matthew Sisk has a much more intuitive (imperative) way to generate
683 tables via his module L<HTML::ElementTable|HTML::ElementTable>.
684
685 However, for those with callback fever, the following method is
686 available. First, we look at a nuts and bolts way to build a table
687 using only standard L<HTML::Tree> API calls. Then the C<table> method
688 available here is discussed.
689
690 =head3 Sample Model
691
692 package Simple::Class;
693
694 use Set::Array;
695
696 my @name = qw(bob bill brian babette bobo bix);
697 my @age = qw(99 12 44 52 12 43);
698 my @weight = qw(99 52 80 124 120 230);
699
700
701 sub new {
702 my $this = shift;
703 bless {}, ref($this) || $this;
704 }
705
706 sub load_data {
707 my @data;
708
709 for (0 .. 5) {
710 push @data, {
711 age => $age[rand $#age] + int rand 20,
712 name => shift @name,
713 weight => $weight[rand $#weight] + int rand 40
714 }
715 }
716
717 Set::Array->new(@data);
718 }
719
720 1;
721
722 =head4 Sample Usage:
723
724 my $data = Simple::Class->load_data;
725 ++$_->{age} for @$data
726
727 =head3 Inline Code to Unroll a Table
728
729 =head4 HTML
730
731 <html>
732 <table id="load_data">
733 <tr> <th>name</th><th>age</th><th>weight</th> </tr>
734 <tr id="iterate">
735 <td id="name"> NATURE BOY RIC FLAIR </td>
736 <td id="age"> 35 </td>
737 <td id="weight"> 220 </td>
738 </tr>
739 </table>
740 </html>
741
742
743 =head4 The manual way (*NOT* recommended)
744
745 require 'simple-class.pl';
746 use HTML::Seamstress;
747
748 # load the view
749 my $seamstress = HTML::Seamstress->new_from_file('simple.html');
750
751 # load the model
752 my $o = Simple::Class->new;
753 my $data = $o->load_data;
754
755 # find the <table> and <tr>
756 my $table_node = $seamstress->look_down('id', 'load_data');
757 my $iter_node = $table_node->look_down('id', 'iterate');
758 my $table_parent = $table_node->parent;
759
760
761 # drop the sample <table> and <tr> from the HTML
762 # only add them in if there is data in the model
763 # this is achieved via the $add_table flag
764
765 $table_node->detach;
766 $iter_node->detach;
767 my $add_table;
768
769 # Get a row of model data
770 while (my $row = shift @$data) {
771
772 # We got row data. Set the flag indicating ok to hook the table into the HTML
773 ++$add_table;
774
775 # clone the sample <tr>
776 my $new_iter_node = $iter_node->clone;
777
778 # find the tags labeled name age and weight and
779 # set their content to the row data
780 $new_iter_node->content_handler($_ => $row->{$_})
781 for qw(name age weight);
782
783 $table_node->push_content($new_iter_node);
784
785 }
786
787 # reattach the table to the HTML tree if we loaded data into some table rows
788
789 $table_parent->push_content($table_node) if $add_table;
790
791 print $seamstress->as_HTML;
792
793 =head3 $tree->table() : API call to Unroll a Table
794
795 require 'simple-class.pl';
796 use HTML::Seamstress;
797
798 # load the view
799 my $seamstress = HTML::Seamstress->new_from_file('simple.html');
800 # load the model
801 my $o = Simple::Class->new;
802
803 $seamstress->table
804 (
805 # tell seamstress where to find the table, via the method call
806 # ->look_down('id', $gi_table). Seamstress detaches the table from the
807 # HTML tree automatically if no table rows can be built
808
809 gi_table => 'load_data',
810
811 # tell seamstress where to find the tr. This is a bit useless as
812 # the <tr> usually can be found as the first child of the parent
813
814 gi_tr => 'iterate',
815
816 # the model data to be pushed into the table
817
818 table_data => $o->load_data,
819
820 # the way to take the model data and obtain one row
821 # if the table data were a hashref, we would do:
822 # my $key = (keys %$data)[0]; my $val = $data->{$key}; delete $data->{$key}
823
824 tr_data => sub {
825 my ($self, $data) = @_;
826 shift @{$data} ;
827 },
828
829 # the way to take a row of data and fill the <td> tags
830
831 td_data => sub {
832 my ($tr_node, $tr_data) = @_;
833 $tr_node->content_handler($_ => $tr_data->{$_})
834 for qw(name age weight)
835 }
836 );
837
838 print $seamstress->as_HTML;
839
840 =head4 Looping over Multiple Sample Rows
841
842 * HTML
843
844 <html>
845 <table id="load_data" CELLPADDING=8 BORDER=2>
846 <tr> <th>name</th><th>age</th><th>weight</th> </tr>
847 <tr id="iterate1" BGCOLOR="white" >
848 <td id="name"> NATURE BOY RIC FLAIR </td>
849 <td id="age"> 35 </td>
850 <td id="weight"> 220 </td>
851 </tr>
852 <tr id="iterate2" BGCOLOR="#CCCC99">
853 <td id="name"> NATURE BOY RIC FLAIR </td>
854 <td id="age"> 35 </td>
855 <td id="weight"> 220 </td>
856 </tr>
857 </table>
858 </html>
859
860 * Only one change to last API call.
861
862 This:
863
864 gi_tr => 'iterate',
865
866 becomes this:
867
868 gi_tr => ['iterate1', 'iterate2']
869
870 =head3 $tree->table2() : New API Call to Unroll a Table
871
872 After 2 or 3 years with C<table()>, I began to develop production
873 websites with it and decided it needed a cleaner interface,
874 particularly in the area of handling the fact that C<id> tags will be
875 the same after cloning a table row.
876
877 First, I will give a dry listing of the function's argument
878 parameters. This will not be educational most likely. A better way to
879 understand how to use the function is to read through the incremental
880 unrolling of the function's interface given in conversational style
881 after the dry listing. But take your pick. It's the same information
882 given in two different ways.
883
884 =head4 Dry/technical parameter documentation
885
886 C<< $tree->table2(%param) >> takes the following arguments:
887
888 =over
889
890 =item * C<< table_ld => $look_down >> : optional
891
892 How to find the C<table> element in C<$tree>. If C<$look_down> is an
893 arrayref, then use C<look_down>. If it is a CODE ref, then call it,
894 passing it C<$tree>.
895
896 Defaults to C<< ['_tag' => 'table'] >> if not passed in.
897
898 =item * C<< table_data => $tabular_data >> : required
899
900 The data to fill the table with. I<Must> be passed in.
901
902 =item * C<< table_proc => $code_ref >> : not implemented
903
904 A subroutine to do something to the table once it is found. Not
905 currently implemented. Not obviously necessary. Just created because
906 there is a C<tr_proc> and C<td_proc>.
907
908 =item * C<< tr_ld => $look_down >> : optional
909
910 Same as C<table_ld> but for finding the table row elements. Please
911 note that the C<tr_ld> is done on the table node that was found
912 I<instead> of the whole HTML tree. This makes sense. The C<tr>s that
913 you want exist below the table that was just found.
914
915 Defaults to C<< ['_tag' => 'tr'] >> if not passed in.
916
917 =item * C<< tr_data => $code_ref >> : optional
918
919 How to take the C<table_data> and return a row. Defaults to:
920
921 sub { my ($self, $data) = @_;
922 shift(@{$data}) ;
923 }
924
925 =item * C<< tr_proc => $code_ref >> : optional
926
927 Something to do to the table row we are about to add to the table we
928 are making. Defaults to a routine which makes the C<id> attribute
929 unique:
930
931 sub {
932 my ($self, $tr, $tr_data, $tr_base_id, $row_count) = @_;
933 $tr->attr(id => sprintf "%s_%d", $tr_base_id, $row_count);
934 }
935
936 =item * C<< td_proc => $code_ref >> : required
937
938 This coderef will take the row of data and operate on the C<td> cells
939 that are children of the C<tr>. See C<t/table2.t> for several usage
940 examples.
941
942 Here's a sample one:
943
944 sub {
945 my ($tr, $data) = @_;
946 my @td = $tr->look_down('_tag' => 'td');
947 for my $i (0..$#td) {
948 $td[$i]->splice_content(0, 1, $data->[$i]);
949 }
950 }
951
952 =cut
953
954 =head4 Conversational parameter documentation
955
956 The first thing you need is a table. So we need a look down for that.
957 If you don't give one, it defaults to
958
959 ['_tag' => 'table']
960
961 What good is a table to display in without data to display?! So you
962 must supply a scalar representing your tabular data source. This
963 scalar might be an array reference, a C<next>able iterator, a DBI
964 statement handle. Whatever it is, it can be iterated through to build
965 up rows of table data. These two required fields (the way to find the
966 table and the data to display in the table) are C<table_ld> and
967 C<table_data> respectively. A little more on C<table_ld>. If this
968 happens to be a CODE ref, then execution of the code ref is presumed
969 to return the C<HTML::Element> representing the table in the HTML
970 tree.
971
972 Next, we get the row or rows which serve as sample C<tr> elements by
973 doing a C<look_down> from the C<table_elem>. While normally one sample
974 row is enough to unroll a table, consider when you have alternating
975 table rows. This API call would need one of each row so that it can
976 cycle through the sample rows as it loops through the data.
977 Alternatively, you could always just use one row and make the
978 necessary changes to the single C<tr> row by mutating the element in
979 C<tr_proc>, discussed below. The default C<tr_ld> is C<< ['_tag' =>
980 'tr'] >> but you can overwrite it. Note well, if you overwrite it with
981 a subroutine, then it is expected that the subroutine will return the
982 C<HTML::Element>(s) which are C<tr> element(s). The reason a
983 subroutine might be preferred is in the case that the HTML designers
984 gave you 8 sample C<tr> rows but only one prototype row is needed. So
985 you can write a subroutine, to splice out the 7 rows you don't need
986 and leave the one sample row remaining so that this API call can clone
987 it and supply it to the C<tr_proc> and C<td_proc> calls.
988
989 Now, as we move through the table rows with table data, we need to do
990 two different things on each table row:
991
992 =over 4
993
994 =item * get one row of data from the C<table_data> via C<tr_data>
995
996 The default procedure assumes the C<table_data> is an array reference
997 and shifts a row off of it:
998
999 sub {
1000 my ($self, $data) = @_;
1001 shift @{$data};
1002 }
1003
1004 Your function MUST return undef when there is no more rows to lay out.
1005
1006 =item * take the C<tr> element and mutate it via C<tr_proc>
1007
1008 The default procedure simply makes the id of the table row unique:
1009
1010 sub {
1011 my ($self, $tr, $tr_data, $row_count, $root_id) = @_;
1012 $tr->attr(id => sprintf "%s_%d", $root_id, $row_count);
1013 }
1014
1015 =back
1016
1017 Now that we have our row of data, we call C<td_proc> so that it can
1018 take the data and the C<td> cells in this C<tr> and process them. This
1019 function I<must> be supplied.
1020
1021 =head3 Whither a Table with No Rows
1022
1023 Often when a table has no rows, we want to display a message
1024 indicating this to the view. Use conditional processing to decide what
1025 to display:
1026
1027 <span id=no_data>
1028 <table><tr><td>No Data is Good Data</td></tr></table>
1029 </span>
1030 <span id=load_data>
1031 <html>
1032 <table id="load_data">
1033 <tr> <th>name</th><th>age</th><th>weight</th> </tr>
1034 <tr id="iterate">
1035 <td id="name"> NATURE BOY RIC FLAIR </td>
1036 <td id="age"> 35 </td>
1037 <td id="weight"> 220 </td>
1038 </tr>
1039 </table>
1040 </html>
1041 </span>
1042
1043 =head2 Tree-Killing Methods
1044
1045 =head3 $tree->prune
1046
1047 This removes any nodes from the tree which consist of nothing or
1048 nothing but whitespace. See also delete_ignorable_whitespace in
1049 L<HTML::Element>.
1050
1051 =head2 Loltree Functions
1052
1053 A loltree is an arrayref consisting of arrayrefs which is used by C<<
1054 new_from__lol >> in L<HTML::Element> to produce HTML trees. The CPAN
1055 distro L<XML::Element::Tolol> creates such XML trees by parsing XML
1056 files, analagous to L<XML::Toolkit>. The purpose of the functions in
1057 this section is to allow you manipulate a loltree programmatically.
1058
1059 These could not be methods because if you bless a loltree, then
1060 HTML::Tree will barf.
1061
1062 =head3 HTML::Element::newchild($lol, $parent_label, @newchild)
1063
1064 Given this initial loltree:
1065
1066 my $initial_lol = [ note => [ shopping => [ item => 'sample' ] ] ];
1067
1068 This code:
1069
1070 sub shopping_items {
1071 my @shopping_items = map { [ item => _ ] } qw(bread butter beans);
1072 @shopping_items;
1073 }
1074
1075 my $new_lol = HTML::Element::newnode($initial_lol, item => shopping_items());
1076
1077 will replace the single sample with a list of shopping items:
1078
1079 [
1080 'note',
1081 [
1082 'shopping',
1083 [
1084 'item',
1085 'bread'
1086 ],
1087 [
1088 'item',
1089 'butter'
1090 ],
1091 [
1092 'item',
1093 'beans'
1094 ]
1095
1096 ]
1097 ];
1098
1099 Thanks to kcott and the other Perlmonks in this thread:
1100 http://www.perlmonks.org/?node_id=912416
1101
1102
1103 =head1 SEE ALSO
1104
1105 =head2 L<HTML::Tree>
1106
1107 A perl package for creating and manipulating HTML trees.
1108
1109 =head2 L<HTML::ElementTable>
1110
1111 An L<HTML::Tree> - based module which allows for manipulation of HTML
1112 trees using cartesian coordinations.
1113
1114 =head2 L<HTML::Seamstress>
1115
1116 An L<HTML::Tree> - based module inspired by XMLC
1117 (L<http://xmlc.enhydra.org>), allowing for dynamic HTML generation via
1118 tree rewriting.
1119
1120 =head2 Push-style templating systems
1121
1122 A comprehensive cross-language
1123 L<list of push-style templating systems|http://perlmonks.org/?node_id=674225>.
1124
1125 =head1 TODO
1126
1127 =over
1128
1129 =item * highlander2
1130
1131 currently the API expects the subtrees to survive or be pruned to be
1132 identified by id:
1133
1134 $if_then->highlander2([
1135 under10 => sub { $_[0] < 10} ,
1136 under18 => sub { $_[0] < 18} ,
1137 welcome => [
1138 sub { 1 },
1139 sub {
1140 my $branch = shift;
1141 $branch->look_down(id => 'age')->replace_content($age);
1142 }
1143 ]
1144 ], $age);
1145
1146 but, it should be more flexible. the C<under10>, and C<under18> are
1147 expected to be ids in the tree... but it is not hard to have a check
1148 to see if this field is an array reference and if it, then to do a
1149 look down instead:
1150
1151 $if_then->highlander2([
1152 [class => 'under10'] => sub { $_[0] < 10} ,
1153 [class => 'under18'] => sub { $_[0] < 18} ,
1154 [class => 'welcome'] => [
1155 sub { 1 },
1156 sub {
1157 my $branch = shift;
1158 $branch->look_down(id => 'age')->replace_content($age);
1159 }
1160 ]
1161 ], $age);
1162
1163 =head1 AUTHOR and ACKS
1164
1165 Terrence Brannon, E<lt>tbone@cpan.orgE<gt>
1166
1167 I appreciate the feedback from M. David Moussa Leo Keita regarding
1168 some issues with the test suite, namely (1) CRLF leading to test
1169 breakage in F<t/crunch.t> and (2) using the wrong module in
1170 F<t/prune.t> thus not having the right functionality available.
1171
1172 Many thanks to BARBIE for his RT bug report.
1173
1174 Many thanks to perlmonk kcott for his work on array rewriting:
1175 L<http://www.perlmonks.org/?node_id=912416>. It was crucial in the
1176 development of newchild.
1177
1178 =head2 Source Repo
1179
1180 The source is at L<http://github.com/metaperl/html-element-library/tree/master>
1181
1182 =head1 COPYRIGHT AND LICENSE
1183
1184 Copyright (C) 2004 by Terrence Brannon
1185
1186 This library is free software; you can redistribute it and/or modify
1187 it under the same terms as Perl itself, either Perl version 5.8.4 or,
1188 at your option, any later version of Perl 5 you may have available.
1189
1190
1191 =cut
This page took 0.108622 seconds and 5 git commands to generate.