+package HTML::Element::Library;
+
+use 5.006001;
+use strict;
+use warnings;
+
+
+our $DEBUG = 0;
+#our $DEBUG = 1;
+
+use Array::Group qw(:all);
+use Carp qw(confess);
+use Data::Dumper;
+use HTML::Element;
+use List::MoreUtils qw/:all/;
+use Params::Validate qw(:all);
+use Scalar::Listify;
+#use Tie::Cycle;
+use List::Rotation::Cycle;
+
+our %EXPORT_TAGS = ( 'all' => [ qw() ] );
+our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
+our @EXPORT = qw();
+
+
+
+our $VERSION = '3.51';
+
+
+# Preloaded methods go here.
+
+sub HTML::Element::siblings {
+ my $element = shift;
+ my $p = $element->parent;
+ return () unless $p;
+ $p->content_list;
+}
+
+sub HTML::Element::sibdex {
+
+ my $element = shift;
+ firstidx { $_ eq $element } $element->siblings
+
+}
+
+sub HTML::Element::addr { goto &HTML::Element::sibdex }
+
+sub HTML::Element::replace_content {
+ my $elem = shift;
+ $elem->delete_content;
+ $elem->push_content(@_);
+}
+
+sub HTML::Element::wrap_content {
+ my($self, $wrap) = @_;
+ my $content = $self->content;
+ if (ref $content) {
+ $wrap->push_content(@$content);
+ @$content = ($wrap);
+ }
+ else {
+ $self->push_content($wrap);
+ }
+ $wrap;
+}
+
+sub HTML::Element::Library::super_literal {
+ my($text) = @_;
+
+ HTML::Element->new('~literal', text => $text);
+}
+
+
+sub HTML::Element::position {
+ # Report coordinates by chasing addr's up the
+ # HTML::ElementSuper tree. We know we've reached
+ # the top when a) there is no parent, or b) the
+ # parent is some HTML::Element unable to report
+ # it's position.
+ my $p = shift;
+ my @pos;
+ while ($p) {
+ my $a = $p->addr;
+ unshift(@pos, $a) if defined $a;
+ $p = $p->parent;
+ }
+ @pos;
+}
+
+
+sub HTML::Element::content_handler {
+ my ($tree, $id_name, $content) = @_;
+
+ $tree->set_child_content(id => $id_name, $content);
+
+}
+
+
+sub make_counter {
+ my $i = 1;
+ sub {
+ shift() . ':' . $i++
+ }
+}
+
+
+sub HTML::Element::iter {
+ my ($tree, $p, @data) = @_;
+
+ # warn 'P: ' , $p->attr('id') ;
+ # warn 'H: ' , $p->as_HTML;
+
+ # my $id_incr = make_counter;
+ my @item = map {
+ my $new_item = clone $p;
+ $new_item->replace_content($_);
+ # $new_item->attr('id', $id_incr->( $p->attr('id') ));
+ $new_item;
+ } @data;
+
+ $p->replace_with(@item);
+
+}
+
+
+sub HTML::Element::iter2 {
+
+ my $tree = shift;
+
+ #warn "INPUT TO TABLE2: ", Dumper \@_;
+
+ my %p = validate(
+ @_, {
+ wrapper_ld => { default => ['_tag' => 'dl'] },
+ wrapper_data => 1,
+ wrapper_proc => { default => undef },
+ item_ld => { default => sub {
+ my $tree = shift;
+ [
+ $tree->look_down('_tag' => 'dt'),
+ $tree->look_down('_tag' => 'dd')
+ ];
+ }
+ },
+ item_data => { default => sub { my ($wrapper_data) = @_;
+ shift(@{$wrapper_data}) ;
+ }},
+ item_proc => {
+ default => sub {
+ my ($item_elems, $item_data, $row_count) = @_;
+ $item_elems->[$_]->replace_content($item_data->[$_]) for (0,1) ;
+ $item_elems;
+ }},
+ splice => { default => sub {
+ my ($container, @item_elems) = @_;
+ $container->splice_content(0, 2, @item_elems);
+ }
+ },
+ debug => {default => 0}
+ }
+ );
+
+ warn "wrapper_data: " . Dumper $p{wrapper_data} if $p{debug} ;
+
+ my $container = ref_or_ld($tree, $p{wrapper_ld});
+ warn "wrapper_(preproc): " . $container->as_HTML if $p{debug} ;
+ $p{wrapper_proc}->($container) if defined $p{wrapper_proc} ;
+ warn "wrapper_(postproc): " . $container->as_HTML if $p{debug} ;
+
+ my $_item_elems = $p{item_ld}->($container);
+
+
+
+ my $row_count;
+ my @item_elem;
+ {
+ my $item_data = $p{item_data}->($p{wrapper_data});
+ last unless defined $item_data;
+
+ warn Dumper("item_data", $item_data);
+
+
+ my $item_elems = [ map { $_->clone } @{$_item_elems} ] ;
+
+ if ($p{debug}) {
+ for (@{$item_elems}) {
+ warn "ITEM_ELEMS ", $_->as_HTML;
+ }
+ }
+
+ my $new_item_elems = $p{item_proc}->($item_elems, $item_data, ++$row_count);
+
+ if ($p{debug}) {
+ for (@{$new_item_elems}) {
+ warn "NEWITEM_ELEMS ", $_->as_HTML;
+ }
+ }
+
+
+ push @item_elem, @{$new_item_elems} ;
+
+ redo;
+ }
+
+ warn "pushing " . @item_elem . " elems " if $p{debug} ;
+
+ $p{splice}->($container, @item_elem);
+
+}
+
+sub HTML::Element::dual_iter {
+ my ($parent, $data) = @_;
+
+ my ($prototype_a, $prototype_b) = $parent->content_list;
+
+ # my $id_incr = make_counter;
+
+ my $i;
+
+ @$data %2 == 0 or
+ confess 'dataset does not contain an even number of members';
+
+ my @iterable_data = ngroup 2 => @$data;
+
+ my @item = map {
+ my ($new_a, $new_b) = map { clone $_ } ($prototype_a, $prototype_b) ;
+ $new_a->splice_content(0,1, $_->[0]);
+ $new_b->splice_content(0,1, $_->[1]);
+ #$_->attr('id', $id_incr->($_->attr('id'))) for ($new_a, $new_b) ;
+ ($new_a, $new_b)
+ } @iterable_data;
+
+ $parent->splice_content(0, 2, @item);
+
+}
+
+
+sub HTML::Element::set_child_content {
+ my $tree = shift;
+ my $content = pop;
+ my @look_down = @_;
+
+ my $content_tag = $tree->look_down(@look_down);
+
+ unless ($content_tag) {
+ warn "criteria [@look_down] not found";
+ return;
+ }
+
+ $content_tag->replace_content($content);
+
+}
+
+sub HTML::Element::highlander {
+ my ($tree, $local_root_id, $aref, @arg) = @_;
+
+ ref $aref eq 'ARRAY' or confess
+ "must supply array reference";
+
+ my @aref = @$aref;
+ @aref % 2 == 0 or confess
+ "supplied array ref must have an even number of entries";
+
+ warn __PACKAGE__ if $DEBUG;
+
+ my $survivor;
+ while (my ($id, $test) = splice @aref, 0, 2) {
+ warn $id if $DEBUG;
+ if ($test->(@arg)) {
+ $survivor = $id;
+ last;
+ }
+ }
+
+
+ my @id_survivor = (id => $survivor);
+ my $survivor_node = $tree->look_down(@id_survivor);
+# warn $survivor;
+# warn $local_root_id;
+# warn $node;
+
+ warn "survivor: $survivor" if $DEBUG;
+ warn "tree: " . $tree->as_HTML if $DEBUG;
+
+ $survivor_node or die "search for @id_survivor failed in tree($tree): " . $tree->as_HTML;
+
+ my $survivor_node_parent = $survivor_node->parent;
+ $survivor_node = $survivor_node->clone;
+ $survivor_node_parent->replace_content($survivor_node);
+
+ warn "new tree: " . $tree->as_HTML if $DEBUG;
+
+ $survivor_node;
+}
+
+
+sub HTML::Element::highlander2 {
+ my $tree = shift;
+
+ my %p = validate(@_, {
+ cond => { type => ARRAYREF },
+ cond_arg => { type => ARRAYREF,
+ default => []
+ },
+ debug => { default => 0 }
+ }
+ );
+
+
+ my @cond = @{$p{cond}};
+ @cond % 2 == 0 or confess
+ "supplied array ref must have an even number of entries";
+
+ warn __PACKAGE__ if $p{debug};
+
+ my @cond_arg = @{$p{cond_arg}};
+
+ my $survivor; my $then;
+ while (my ($id, $if_then) = splice @cond, 0, 2) {
+
+ warn $id if $p{debug};
+ my ($if, $_then);
+
+ if (ref $if_then eq 'ARRAY') {
+ ($if, $_then) = @$if_then;
+ } else {
+ ($if, $_then) = ($if_then, sub {});
+ }
+
+ if ($if->(@cond_arg)) {
+ $survivor = $id;
+ $then = $_then;
+ last;
+ }
+
+ }
+
+ my @ld = (ref $survivor eq 'ARRAY')
+ ? @$survivor
+ : (id => $survivor)
+ ;
+
+ warn "survivor: ", $survivor if $p{debug};
+ warn "survivor_ld: ", Dumper \@ld if $p{debug};
+
+
+ my $survivor_node = $tree->look_down(@ld);
+
+ $survivor_node or confess
+ "search for @ld failed in tree($tree): " . $tree->as_HTML;
+
+ my $survivor_node_parent = $survivor_node->parent;
+ $survivor_node = $survivor_node->clone;
+ $survivor_node_parent->replace_content($survivor_node);
+
+
+ # **************** NEW FUNCTIONALITY *******************
+
+ # apply transforms on survivor node
+
+
+ warn "SURV::pre_trans " . $survivor_node->as_HTML if $p{debug};
+ $then->($survivor_node, @cond_arg);
+ warn "SURV::post_trans " . $survivor_node->as_HTML if $p{debug};
+
+ # **************** NEW FUNCTIONALITY *******************
+
+
+
+
+ $survivor_node;
+}
+
+
+sub overwrite_action {
+ my ($mute_node, %X) = @_;
+
+ $mute_node->attr($X{local_attr}{name} => $X{local_attr}{value}{new});
+}
+
+
+sub HTML::Element::overwrite_attr {
+ my $tree = shift;
+
+ $tree->mute_elem(@_, \&overwrite_action);
+}
+
+
+
+sub HTML::Element::mute_elem {
+ my ($tree, $mute_attr, $closures, $post_hook) = @_;
+
+ warn "my mute_node = $tree->look_down($mute_attr => qr/.*/) ;";
+ my @mute_node = $tree->look_down($mute_attr => qr/.*/) ;
+
+ for my $mute_node (@mute_node) {
+ my ($local_attr,$mute_key) = split /\s+/, $mute_node->attr($mute_attr);
+ my $local_attr_value_current = $mute_node->attr($local_attr);
+ my $local_attr_value_new = $closures->{$mute_key}->($tree, $mute_node, $local_attr_value_current);
+ $post_hook->(
+ $mute_node,
+ tree => $tree,
+ local_attr => {
+ name => $local_attr,
+ value => {
+ current => $local_attr_value_current,
+ new => $local_attr_value_new
+ }
+ }
+ ) if ($post_hook) ;
+ }
+}
+
+
+
+sub HTML::Element::table {
+
+ my ($s, %table) = @_;
+
+ my $table = {};
+
+ # use Data::Dumper; warn Dumper \%table;
+
+ # ++$DEBUG if $table{debug} ;
+
+
+ # Get the table element
+ $table->{table_node} = $s->look_down(id => $table{gi_table});
+ $table->{table_node} or confess
+ "table tag not found via (id => $table{gi_table}";
+
+ # Get the prototype tr element(s)
+ my @table_gi_tr = listify $table{gi_tr} ;
+ my @iter_node = map
+ {
+ my $tr = $table->{table_node}->look_down(id => $_);
+ $tr or confess "tr with id => $_ not found";
+ $tr;
+ } @table_gi_tr;
+
+ warn "found " . @iter_node . " iter nodes " if $DEBUG;
+ # tie my $iter_node, 'Tie::Cycle', \@iter_node;
+ my $iter_node = List::Rotation::Cycle->new(@iter_node);
+
+ # warn $iter_node;
+ warn Dumper ($iter_node, \@iter_node) if $DEBUG;
+
+ # $table->{content} = $table{content};
+ #$table->{parent} = $table->{table_node}->parent;
+
+
+ # $table->{table_node}->detach;
+ # $_->detach for @iter_node;
+
+ my @table_rows;
+
+ {
+ my $row = $table{tr_data}->($table, $table{table_data});
+ last unless defined $row;
+
+ # get a sample table row and clone it.
+ my $I = $iter_node->next;
+ warn "I: $I" if $DEBUG;
+ my $new_iter_node = $I->clone;
+
+
+ $table{td_data}->($new_iter_node, $row);
+ push @table_rows, $new_iter_node;
+
+ redo;
+ }
+
+ if (@table_rows) {
+
+ my $replace_with_elem = $s->look_down(id => shift @table_gi_tr) ;
+ for (@table_gi_tr) {
+ $s->look_down(id => $_)->detach;
+ }
+
+ $replace_with_elem->replace_with(@table_rows);
+
+ }
+
+}
+
+sub ref_or_ld {
+
+ my ($tree, $slot) = @_;
+
+ if (ref($slot) eq 'CODE') {
+ $slot->($tree);
+ } else {
+ $tree->look_down(@$slot);
+ }
+}
+
+
+
+sub HTML::Element::table2 {
+
+ my $tree = shift;
+
+
+
+ my %p = validate(
+ @_, {
+ table_ld => { default => ['_tag' => 'table'] },
+ table_data => 1,
+ table_proc => { default => undef },
+
+ tr_ld => { default => ['_tag' => 'tr'] },
+ tr_data => { default => sub { my ($self, $data) = @_;
+ shift(@{$data}) ;
+ }},
+ tr_base_id => { default => undef },
+ tr_proc => { default => sub {} },
+ td_proc => 1,
+ debug => {default => 0}
+ }
+ );
+
+ warn "INPUT TO TABLE2: ", Dumper \@_ if $p{debug};
+
+ warn "table_data: " . Dumper $p{table_data} if $p{debug} ;
+
+ my $table = {};
+
+ # use Data::Dumper; warn Dumper \%table;
+
+ # ++$DEBUG if $table{debug} ;
+
+ # Get the table element
+ warn 1;
+ $table->{table_node} = ref_or_ld( $tree, $p{table_ld} ) ;
+ warn 2;
+ $table->{table_node} or confess
+ "table tag not found via " . Dumper($p{table_ld}) ;
+
+ warn "table: " . $table->{table_node}->as_HTML if $p{debug};
+
+
+ # Get the prototype tr element(s)
+ my @proto_tr = ref_or_ld( $table->{table_node}, $p{tr_ld} ) ;
+
+ warn "found " . @proto_tr . " iter nodes " if $p{debug};
+
+ @proto_tr or return ;
+
+ if ($p{debug}) {
+ warn $_->as_HTML for @proto_tr;
+ }
+ my $proto_tr = List::Rotation::Cycle->new(@proto_tr);
+
+ my $tr_parent = $proto_tr[0]->parent;
+ warn "parent element of trs: " . $tr_parent->as_HTML if $p{debug};
+
+ my $row_count;
+
+ my @table_rows;
+
+ {
+ my $row = $p{tr_data}->($table, $p{table_data}, $row_count);
+ warn "data row: " . Dumper $row if $p{debug};
+ last unless defined $row;
+
+ # wont work: my $new_iter_node = $table->{iter_node}->clone;
+ my $new_tr_node = $proto_tr->next->clone;
+ warn "new_tr_node: $new_tr_node" if $p{debug};
+
+ $p{tr_proc}->($tree, $new_tr_node, $row, $p{tr_base_id}, ++$row_count)
+ if defined $p{tr_proc};
+
+ warn "data row redux: " . Dumper $row if $p{debug};
+ warn 3.3;
+
+ $p{td_proc}->($new_tr_node, $row);
+ push @table_rows, $new_tr_node;
+
+ warn 4.4;
+
+ redo;
+ }
+
+ $_->detach for @proto_tr;
+
+ $tr_parent->push_content(@table_rows) if (@table_rows) ;
+
+}
+
+
+sub HTML::Element::unroll_select {
+
+ my ($s, %select) = @_;
+
+ my $select = {};
+
+ my $select_node = $s->look_down(id => $select{select_label});
+
+ my $option = $select_node->look_down('_tag' => 'option');
+
+# warn $option;
+
+
+ $option->detach;
+
+ while (my $row = $select{data_iter}->($select{data}))
+ {
+# warn Dumper($row);
+ my $o = $option->clone;
+ $o->attr('value', $select{option_value}->($row));
+ $o->attr('SELECTED', 1) if ($select{option_selected}->($row)) ;
+
+ $o->replace_content($select{option_content}->($row));
+ $select_node->push_content($o);
+ }
+
+
+}
+
+
+
+sub HTML::Element::set_sibling_content {
+ my ($elt, $content) = @_;
+
+ $elt->parent->splice_content($elt->pindex + 1, 1, $content);
+
+}
+
+sub HTML::TreeBuilder::parse_string {
+ my ($package, $string) = @_;
+
+ my $h = HTML::TreeBuilder->new;
+ HTML::TreeBuilder->parse($string);
+
+}
+
+
+
+1;
+__END__
+# Below is stub documentation for your module. You'd better edit it!
+
+=head1 NAME
+
+HTML::Element::Library - HTML::Element convenience functions
+
+=head1 SYNOPSIS
+
+ use HTML::Element::Library;
+ use HTML::TreeBuilder;
+
+=head1 DESCRIPTION
+
+This method provides API calls for common actions on trees when using
+L<HTML::Tree>.
+
+=head1 METHODS
+
+The test suite contains examples of each of these methods in a
+file C<t/$method.t>
+
+=head2 Positional Querying Methods
+
+=head3 $elem->siblings
+
+Return a list of all nodes under the same parent.
+
+=head3 $elem->sibdex
+
+Return the index of C<$elem> into the array of siblings of which it is
+a part. L<HTML::ElementSuper> calls this method C<addr> but I don't think
+that is a descriptive name. And such naming is deceptively close to the
+C<address> function of C<HTML::Element>. HOWEVER, in the interest of
+backwards compatibility, both methods are available.
+
+=head3 $elem->addr
+
+Same as sibdex
+
+=head3 $elem->position()
+
+Returns the coordinates of this element in the tree it inhabits.
+This is accomplished by succesively calling addr() on ancestor
+elements until either a) an element that does not support these
+methods is found, or b) there are no more parents. The resulting
+list is the n-dimensional coordinates of the element in the tree.
+
+=head2 Element Decoration Methods
+
+=head3 HTML::Element::Library::super_literal($text)
+
+In L<HTML::Element>, Sean Burke discusses super-literals. They are
+text which does not get escaped. Great for includng Javascript in
+HTML. Also great for including foreign language into a document.
+
+So, you basically toss C<super_literal> your text and back comes
+your text wrapped in a C<~literal> element.
+
+One of these days, I'll around to writing a nice C<EXPORT> section.
+
+=head2 Tree Rewriting Methods
+
+=head3 $elem->replace_content(@new_elem)
+
+Replaces all of C<$elem>'s content with C<@new_elem>.
+
+=head3 $elem->wrap_content($wrapper_element)
+
+Wraps the existing content in the provided element. If the provided element
+happens to be a non-element, a push_content is performed instead.
+
+=head3 $elem->set_child_content(@look_down, $content)
+
+ This method looks down $tree using the criteria specified in @look_down using the the HTML::Element look_down() method.
+
+After finding the node, it detaches the node's content and pushes $content as the node's content.
+
+=head3 $tree->content_handler($sid_value , $content)
+
+This is a convenience method. Because the look_down criteria will often simply be:
+
+ id => 'fixme'
+
+to find things like:
+
+ <a id=fixme href=http://www.somesite.org>replace_content</a>
+
+You can call this method to shorten your typing a bit. You can simply type
+
+ $elem->content_handler( fixme => 'new text' )
+
+Instead of typing:
+
+ $elem->set_child_content(sid => 'fixme', 'new text')
+
+=head3 $tree->highlander($subtree_span_id, $conditionals, @conditionals_args)
+
+This allows for "if-then-else" style processing. Highlander was a movie in
+which only one would survive. Well, in terms of a tree when looking at a
+structure that you want to process in C<if-then-else> style, only one child
+will survive. For example, given this HTML template:
+
+ <span klass="highlander" id="age_dialog">
+ <span id="under10">
+ Hello, does your mother know you're
+ using her AOL account?
+ </span>
+ <span id="under18">
+ Sorry, you're not old enough to enter
+ (and too dumb to lie about your age)
+ </span>
+ <span id="welcome">
+ Welcome
+ </span>
+ </span>
+
+We only want one child of the C<span> tag with id C<age_dialog> to remain
+based on the age of the person visiting the page.
+
+So, let's setup a call that will prune the subtree as a function of age:
+
+ sub process_page {
+ my $age = shift;
+ my $tree = HTML::TreeBuilder->new_from_file('t/html/highlander.html');
+
+ $tree->highlander
+ (age_dialog =>
+ [
+ under10 => sub { $_[0] < 10} ,
+ under18 => sub { $_[0] < 18} ,
+ welcome => sub { 1 }
+ ],
+ $age
+ );
+
+And there we have it. If the age is less than 10, then the node with
+id C<under10> remains. For age less than 18, the node with id C<under18>
+remains.
+Otherwise our "else" condition fires and the child with id C<welcome> remains.
+
+=head3 $tree->highlander2($tree, $conditionals, @conditionals_args)
+
+Right around the same time that C<table2()> came into being, Seamstress
+began to tackle tougher and tougher processing problems. It became clear that
+a more powerful highlander was needed... one that not only snipped the tree
+of the nodes that should not survive, but one that allows for
+post-processing of the survivor node. And one that was more flexible with
+how to find the nodes to snip.
+
+Thus (drum roll) C<highlander2()>.
+
+So let's look at our HTML which requires post-selection processing:
+
+ <span klass="highlander" id="age_dialog">
+ <span id="under10">
+ Hello, little <span id=age>AGE</span>-year old,
+ does your mother know you're using her AOL account?
+ </span>
+ <span id="under18">
+ Sorry, you're only <span id=age>AGE</span>
+ (and too dumb to lie about your age)
+ </span>
+ <span id="welcome">
+ Welcome, isn't it good to be <span id=age>AGE</span> years old?
+ </span>
+</span>
+
+In this case, a branch survives, but it has dummy data in it. We must take
+the surviving segment of HTML and rewrite the age C<span> with the age.
+Here is how we use C<highlander2()> to do so:
+
+ sub replace_age {
+ my $branch = shift;
+ my $age = shift;
+ $branch->look_down(id => 'age')->replace_content($age);
+ }
+
+ my $if_then = $tree->look_down(id => 'age_dialog');
+
+ $if_then->highlander2(
+ cond => [
+ under10 => [
+ sub { $_[0] < 10} ,
+ \&replace_age
+ ],
+ under18 => [
+ sub { $_[0] < 18} ,
+ \&replace_age
+ ],
+ welcome => [
+ sub { 1 },
+ \&replace_age
+ ]
+ ],
+ cond_arg => [ $age ]
+ );
+
+We pass it the tree (C<$if_then>), an arrayref of conditions
+(C<cond>) and an arrayref of arguments which are passed to the
+C<cond>s and to the replacement subs.
+
+The C<under10>, C<under18> and C<welcome> are id attributes in the
+tree of the siblings of which only one will survive. However,
+should you need to do
+more complex look-downs to find the survivor,
+then supply an array ref instead of a simple
+scalar:
+
+
+ $if_then->highlander2(
+ cond => [
+ [class => 'r12'] => [
+ sub { $_[0] < 10} ,
+ \&replace_age
+ ],
+ [class => 'z22'] => [
+ sub { $_[0] < 18} ,
+ \&replace_age
+ ],
+ [class => 'w88'] => [
+ sub { 1 },
+ \&replace_age
+ ]
+ ],
+ cond_arg => [ $age ]
+ );
+
+
+=head3 $tree->overwrite_attr($mutation_attr => $mutating_closures)
+
+This method is designed for taking a tree and reworking a set of nodes in
+a stereotyped fashion. For instance let's say you have 3 remote image
+archives, but you don't want to put long URLs in your img src
+tags for reasons of abstraction, re-use and brevity. So instead you do this:
+
+ <img src="/img/smiley-face.jpg" fixup="src lnc">
+ <img src="/img/hot-babe.jpg" fixup="src playboy">
+ <img src="/img/footer.jpg" fixup="src foobar">
+
+and then when the tree of HTML is being processed, you make this call:
+
+ my %closures = (
+ lnc => sub { my ($tree, $mute_node, $attr_value)= @_; "http://lnc.usc.edu$attr_value" },
+ playboy => sub { my ($tree, $mute_node, $attr_value)= @_; "http://playboy.com$attr_value" }
+ foobar => sub { my ($tree, $mute_node, $attr_value)= @_; "http://foobar.info$attr_value" }
+ )
+
+ $tree->overwrite_attr(fixup => \%closures) ;
+
+and the tags come out modified like so:
+
+ <img src="http://lnc.usc.edu/img/smiley-face.jpg" fixup="src lnc">
+ <img src="http://playboy.com/img/hot-babe.jpg" fixup="src playboy">
+ <img src="http://foobar.info/img/footer.jpg" fixup="src foobar">
+
+=head3 $tree->mute_elem($mutation_attr => $mutating_closures, [ $post_hook ] )
+
+This is a generalization of C<overwrite_attr>. C<overwrite_attr>
+assumes the return value of the
+closure is supposed overwrite an attribute value and does it for you.
+C<mute_elem> is a more general function which does nothing but
+hand the closure the element and let it mutate it as it jolly well pleases :)
+
+In fact, here is the implementation of C<overwrite_attr>
+to give you a taste of how C<mute_attr> is used:
+
+ sub overwrite_action {
+ my ($mute_node, %X) = @_;
+
+ $mute_node->attr($X{local_attr}{name} => $X{local_attr}{value}{new});
+ }
+
+
+ sub HTML::Element::overwrite_attr {
+ my $tree = shift;
+
+ $tree->mute_elem(@_, \&overwrite_action);
+ }
+
+
+
+
+=head2 Tree-Building Methods: Unrolling an array via a single sample element (<ul> container)
+
+This is best described by example. Given this HTML:
+
+ <strong>Here are the things I need from the store:</strong>
+ <ul>
+ <li class="store_items">Sample item</li>
+ </ul>
+
+We can unroll it like so:
+
+ my $li = $tree->look_down(class => 'store_items');
+
+ my @items = qw(bread butter vodka);
+
+ $tree->iter($li => @items);
+
+To produce this:
+
+
+ <html>
+ <head></head>
+ <body>Here are the things I need from the store:
+ <ul>
+ <li class="store_items">bread</li>
+ <li class="store_items">butter</li>
+ <li class="store_items">vodka</li>
+ </ul>
+ </body>
+ </html>
+
+=head2 Tree-Building Methods: Unrolling an array via n sample elements (<dl> container)
+
+C<iter()> was fine for awhile, but some things
+(e.g. definition lists) need a more general function to make them easy to
+do. Hence C<iter2()>. This function will be explained by example of unrolling
+a simple definition list.
+
+So here's our mock-up HTML from the designer:
+
+ <dl class="dual_iter" id="service_plan">
+ <dt>
+ Artist
+ </dt>
+ <dd>
+ A person who draws blood.
+ </dd>
+
+ <dt>
+ Musician
+ </dt>
+ <dd>
+ A clone of Iggy Pop.
+ </dd>
+
+ <dt>
+ Poet
+ </dt>
+ <dd>
+ A relative of Edgar Allan Poe.
+ </dd>
+
+ <dt class="adstyle">sample header</dt>
+ <dd class="adstyle2">sample data</dd>
+
+ </dl>
+
+
+And we want to unroll our data set:
+
+ my @items = (
+ ['the pros' => 'never have to worry about service again'],
+ ['the cons' => 'upfront extra charge on purchase'],
+ ['our choice' => 'go with the extended service plan']
+ );
+
+
+Now, let's make this problem a bit harder to show off the power of C<iter2()>.
+Let's assume that we want only the last <dt> and it's accompanying <dd>
+(the one with "sample data") to be used as the sample data
+for unrolling with our data set. Let's further assume that we want them to
+remain in the final output.
+
+So now, the API to C<iter2()> will be discussed and we will explain how our
+goal of getting our data into HTML fits into the API.
+
+=over 4
+
+=item * wrapper_ld
+
+This is how to look down and find the container of all the elements we will
+be unrolling. The <dl> tag is the container for the dt and dd tags we will be
+unrolling.
+
+If you pass an anonymous subroutine, then it is presumed that execution of
+this subroutine will return the HTML::Element representing the container tag.
+If you pass an array ref, then this will be dereferenced and passed to
+C<HTML::Element::look_down()>.
+
+default value: C<< ['_tag' => 'dl'] >>
+
+Based on the mock HTML above, this default is fine for finding our container
+tag. So let's move on.
+
+=item * wrapper_data
+
+This is an array reference of data that we will be putting into the container.
+You must supply this. C<@items> above is our C<wrapper_data>.
+
+=item * wrapper_proc
+
+After we find the container via C<wrapper_ld>, we may want to pre-process
+some aspect of this tree. In our case the first two sets of dt and dd need
+to be removed, leaving the last dt and dd. So, we supply a C<wrapper_proc>
+which will do this.
+
+default: undef
+
+=item * item_ld
+
+This anonymous subroutine returns an array ref of C<HTML::Element>s that will
+be cloned and populated with item data
+(item data is a "row" of C<wrapper_data>).
+
+default: returns an arrayref consisting of the dt and dd element inside the
+container.
+
+=item * item_data
+
+This is a subroutine that takes C<wrapper_data> and retrieves one "row"
+to be "pasted" into the array ref of C<HTML::Element>s found via C<item_ld>.
+I hope that makes sense.
+
+default: shifts C<wrapper_data>.
+
+=item * item_proc
+
+This is a subroutine that takes the C<item_data> and the C<HTML::Element>s
+found via C<item_ld> and produces an arrayref of C<HTML::Element>s which will
+eventually be spliced into the container.
+
+Note that this subroutine MUST return the new items. This is done
+So that more items than were passed in can be returned. This is
+useful when, for example, you must return 2 dts for an input data item.
+And when would you do this? When a single term has multiple spellings
+for instance.
+
+default: expects C<item_data> to be an arrayref of two elements and
+C<item_elems> to be an arrayref of two C<HTML::Element>s. It replaces the
+content of the C<HTML::Element>s with the C<item_data>.
+
+=item * splice
+
+After building up an array of C<@item_elems>, the subroutine passed as
+C<splice> will be given the parent container HTML::Element and the
+C<@item_elems>. How the C<@item_elems> end up in the container is up to this
+routine: it could put half of them in. It could unshift them or whatever.
+
+default: C<< $container->splice_content(0, 2, @item_elems) >>
+In other words, kill the 2 sample elements with the newly generated
+@item_elems
+
+=back
+
+So now that we have documented the API, let's see the call we need:
+
+ $tree->iter2(
+ # default wrapper_ld ok.
+ wrapper_data => \@items,
+ wrapper_proc => sub {
+ my ($container) = @_;
+
+ # only keep the last 2 dts and dds
+ my @content_list = $container->content_list;
+ $container->splice_content(0, @content_list - 2);
+ },
+
+ # default item_ld is fine.
+ # default item_data is fine.
+ # default item_proc is fine.
+ splice => sub {
+ my ($container, @item_elems) = @_;
+ $container->unshift_content(@item_elems);
+ },
+ debug => 1,
+ );
+
+
+=head2 Tree-Building Methods: Select Unrolling
+
+The C<unroll_select> method has this API:
+
+ $tree->unroll_select(
+ select_label => $id_label,
+ option_value => $closure, # how to get option value from data row
+ option_content => $closure, # how to get option content from data row
+ option_selected => $closure, # boolean to decide if SELECTED
+ data => $data # the data to be put into the SELECT
+ data_iter => $closure # the thing that will get a row of data
+ );
+
+Here's an example:
+
+ $tree->unroll_select(
+ select_label => 'clan_list',
+ option_value => sub { my $row = shift; $row->clan_id },
+ option_content => sub { my $row = shift; $row->clan_name },
+ option_selected => sub { my $row = shift; $row->selected },
+ data => \@query_results,
+ data_iter => sub { my $data = shift; $data->next }
+ )
+
+
+
+=head2 Tree-Building Methods: Table Generation
+
+Matthew Sisk has a much more intuitive (imperative)
+way to generate tables via his module
+L<HTML::ElementTable|HTML::ElementTable>.
+However, for those with callback fever, the following
+method is available. First, we look at a nuts and bolts way to build a table
+using only standard L<HTML::Tree> API calls. Then the C<table> method
+available here is discussed.
+
+=head3 Sample Model
+
+ package Simple::Class;
+
+ use Set::Array;
+
+ my @name = qw(bob bill brian babette bobo bix);
+ my @age = qw(99 12 44 52 12 43);
+ my @weight = qw(99 52 80 124 120 230);
+
+
+ sub new {
+ my $this = shift;
+ bless {}, ref($this) || $this;
+ }
+
+ sub load_data {
+ my @data;
+
+ for (0 .. 5) {
+ push @data, {
+ age => $age[rand $#age] + int rand 20,
+ name => shift @name,
+ weight => $weight[rand $#weight] + int rand 40
+ }
+ }
+
+ Set::Array->new(@data);
+ }
+
+
+ 1;
+
+
+=head4 Sample Usage:
+
+ my $data = Simple::Class->load_data;
+ ++$_->{age} for @$data
+
+=head3 Inline Code to Unroll a Table
+
+=head4 HTML
+
+ <html>
+
+ <table id="load_data">
+
+ <tr> <th>name</th><th>age</th><th>weight</th> </tr>
+
+ <tr id="iterate">
+
+ <td id="name"> NATURE BOY RIC FLAIR </td>
+ <td id="age"> 35 </td>
+ <td id="weight"> 220 </td>
+
+ </tr>
+
+ </table>
+
+ </html>
+
+
+=head4 The manual way (*NOT* recommended)
+
+ require 'simple-class.pl';
+ use HTML::Seamstress;
+
+ # load the view
+ my $seamstress = HTML::Seamstress->new_from_file('simple.html');
+
+ # load the model
+ my $o = Simple::Class->new;
+ my $data = $o->load_data;
+
+ # find the <table> and <tr>
+ my $table_node = $seamstress->look_down('id', 'load_data');
+ my $iter_node = $table_node->look_down('id', 'iterate');
+ my $table_parent = $table_node->parent;
+
+
+ # drop the sample <table> and <tr> from the HTML
+ # only add them in if there is data in the model
+ # this is achieved via the $add_table flag
+
+ $table_node->detach;
+ $iter_node->detach;
+ my $add_table;
+
+ # Get a row of model data
+ while (my $row = shift @$data) {
+
+ # We got row data. Set the flag indicating ok to hook the table into the HTML
+ ++$add_table;
+
+ # clone the sample <tr>
+ my $new_iter_node = $iter_node->clone;
+
+ # find the tags labeled name age and weight and
+ # set their content to the row data
+ $new_iter_node->content_handler($_ => $row->{$_})
+ for qw(name age weight);
+
+ $table_node->push_content($new_iter_node);
+
+ }
+
+ # reattach the table to the HTML tree if we loaded data into some table rows
+
+ $table_parent->push_content($table_node) if $add_table;
+
+ print $seamstress->as_HTML;
+
+
+
+=head3 $tree->table() : API call to Unroll a Table
+
+ require 'simple-class.pl';
+ use HTML::Seamstress;
+
+ # load the view
+ my $seamstress = HTML::Seamstress->new_from_file('simple.html');
+ # load the model
+ my $o = Simple::Class->new;
+
+ $seamstress->table
+ (
+ # tell seamstress where to find the table, via the method call
+ # ->look_down('id', $gi_table). Seamstress detaches the table from the
+ # HTML tree automatically if no table rows can be built
+
+ gi_table => 'load_data',
+
+ # tell seamstress where to find the tr. This is a bit useless as
+ # the <tr> usually can be found as the first child of the parent
+
+ gi_tr => 'iterate',
+
+ # the model data to be pushed into the table
+
+ table_data => $o->load_data,
+
+ # the way to take the model data and obtain one row
+ # if the table data were a hashref, we would do:
+ # my $key = (keys %$data)[0]; my $val = $data->{$key}; delete $data->{$key}
+
+ tr_data => sub { my ($self, $data) = @_;
+ shift(@{$data}) ;
+ },
+
+ # the way to take a row of data and fill the <td> tags
+
+ td_data => sub { my ($tr_node, $tr_data) = @_;
+ $tr_node->content_handler($_ => $tr_data->{$_})
+ for qw(name age weight) }
+
+ );
+
+
+ print $seamstress->as_HTML;
+
+
+
+=head4 Looping over Multiple Sample Rows
+
+* HTML
+
+ <html>
+
+ <table id="load_data" CELLPADDING=8 BORDER=2>
+
+ <tr> <th>name</th><th>age</th><th>weight</th> </tr>
+
+ <tr id="iterate1" BGCOLOR="white" >
+
+ <td id="name"> NATURE BOY RIC FLAIR </td>
+ <td id="age"> 35 </td>
+ <td id="weight"> 220 </td>
+
+ </tr>
+ <tr id="iterate2" BGCOLOR="#CCCC99">
+
+ <td id="name"> NATURE BOY RIC FLAIR </td>
+ <td id="age"> 35 </td>
+ <td id="weight"> 220 </td>
+
+ </tr>
+
+ </table>
+
+ </html>
+
+
+* Only one change to last API call.
+
+This:
+
+ gi_tr => 'iterate',
+
+becomes this:
+
+ gi_tr => ['iterate1', 'iterate2']
+
+=head3 $tree->table2() : New API Call to Unroll a Table
+
+After 2 or 3 years with C<table()>, I began to develop
+production websites with it and decided it needed a cleaner
+interface, particularly in the area of handling the fact that
+C<id> tags will be the same after cloning a table row.
+
+First, I will give a dry listing of the function's argument parameters.
+This will not be educational most likely. A better way to understand how
+to use the function is to read through the incremental unrolling of the
+function's interface given in conversational style after the dry listing.
+But take your pick. It's the same information given in two different
+ways.
+
+=head4 Dry/technical parameter documentation
+
+C<< $tree->table2(%param) >> takes the following arguments:
+
+=over
+
+=item * C<< table_ld => $look_down >> : optional
+
+How to find the C<table> element in C<$tree>. If C<$look_down> is an
+arrayref, then use C<look_down>. If it is a CODE ref, then call it,
+passing it C<$tree>.
+
+Defaults to C<< ['_tag' => 'table'] >> if not passed in.
+
+=item * C<< table_data => $tabular_data >> : required
+
+The data to fill the table with. I<Must> be passed in.
+
+=item * C<< table_proc => $code_ref >> : not implemented
+
+A subroutine to do something to the table once it is found.
+Not currently implemented. Not obviously necessary. Just
+created because there is a C<tr_proc> and C<td_proc>.
+
+=item * C<< tr_ld => $look_down >> : optional
+
+Same as C<table_ld> but for finding the table row elements. Please note
+that the C<tr_ld> is done on the table node that was found I<instead>
+of the whole HTML tree. This makes sense. The C<tr>s that you want exist
+below the table that was just found.
+
+Defaults to C<< ['_tag' => 'tr'] >> if not passed in.
+
+=item * C<< tr_data => $code_ref >> : optional
+
+How to take the C<table_data> and return a row. Defaults to:
+
+ sub { my ($self, $data) = @_;
+ shift(@{$data}) ;
+ }
+
+=item * C<< tr_proc => $code_ref >> : optional
+
+Something to do to the table row we are about to add to the
+table we are making. Defaults to a routine which makes the C<id>
+attribute unique:
+
+ sub {
+ my ($self, $tr, $tr_data, $tr_base_id, $row_count) = @_;
+ $tr->attr(id => sprintf "%s_%d", $tr_base_id, $row_count);
+ }
+
+=item * C<< td_proc => $code_ref >> : required
+
+This coderef will take the row of data and operate on the C<td> cells that
+are children of the C<tr>. See C<t/table2.t> for several usage examples.
+
+Here's a sample one:
+
+ sub {
+ my ($tr, $data) = @_;
+ my @td = $tr->look_down('_tag' => 'td');
+ for my $i (0..$#td) {
+ $td[$i]->splice_content(0, 1, $data->[$i]);
+ }
+ }
+
+=cut
+
+=head4 Conversational parameter documentation
+
+The first thing you need is a table. So we need a look down for that. If you
+don't give one, it defaults to
+
+ ['_tag' => 'table']
+
+What good is a table to display in without data to display?!
+So you must supply a scalar representing your tabular
+data source. This scalar might be an array reference, a C<next>able iterator,
+a DBI statement handle. Whatever it is, it can be iterated through to build
+up rows of table data.
+These two required fields (the way to find the table and the data to
+display in the table) are C<table_ld> and C<table_data>
+respectively. A little more on C<table_ld>. If this happens to be a CODE ref,
+then execution
+of the code ref is presumed to return the C<HTML::Element>
+representing the table in the HTML tree.
+
+Next, we get the row or rows which serve as sample C<tr> elements by doing
+a C<look_down> from the C<table_elem>. While normally one sample row
+is enough to unroll a table, consider when you have alternating
+table rows. This API call would need one of each row so that it can
+cycle through the
+sample rows as it loops through the data.
+Alternatively, you could always just use one row and
+make the necessary changes to the single C<tr> row by
+mutating the element in C<tr_proc>,
+discussed below. The default C<tr_ld> is
+C<< ['_tag' => 'tr'] >> but you can overwrite it. Note well, if you overwrite
+it with a subroutine, then it is expected that the subroutine will return
+the C<HTML::Element>(s)
+which are C<tr> element(s).
+The reason a subroutine might be preferred is in the case
+that the HTML designers gave you 8 sample C<tr> rows but only one
+prototype row is needed.
+So you can write a subroutine, to splice out the 7 rows you don't need
+and leave the one sample
+row remaining so that this API call can clone it and supply it to
+the C<tr_proc> and C<td_proc> calls.
+
+Now, as we move through the table rows with table data,
+we need to do two different things on
+each table row:
+
+=over 4
+
+=item * get one row of data from the C<table_data> via C<tr_data>
+
+The default procedure assumes the C<table_data> is an array reference and
+shifts a row off of it:
+
+ sub { my ($self, $data) = @_;
+ shift(@{$data}) ;
+ }
+
+Your function MUST return undef when there is no more rows to lay out.
+
+=item * take the C<tr> element and mutate it via C<tr_proc>
+
+The default procedure simply makes the id of the table row unique:
+
+ sub { my ($self, $tr, $tr_data, $row_count, $root_id) = @_;
+ $tr->attr(id => sprintf "%s_%d", $root_id, $row_count);
+ }
+
+=back
+
+Now that we have our row of data, we call C<td_proc> so that it can
+take the data and the C<td> cells in this C<tr> and process them.
+This function I<must> be supplied.
+
+
+=head3 Whither a Table with No Rows
+
+Often when a table has no rows, we want to display a message
+indicating this to the view. Use conditional processing to decide what
+to display:
+
+ <span id=no_data>
+ <table><tr><td>No Data is Good Data</td></tr></table>
+ </span>
+ <span id=load_data>
+ <html>
+
+ <table id="load_data">
+
+ <tr> <th>name</th><th>age</th><th>weight</th> </tr>
+
+ <tr id="iterate">
+
+ <td id="name"> NATURE BOY RIC FLAIR </td>
+ <td id="age"> 35 </td>
+ <td id="weight"> 220 </td>
+
+ </tr>
+
+ </table>
+
+ </html>
+
+ </span>
+
+
+
+
+=head1 SEE ALSO
+
+=over
+
+=item * L<HTML::Tree>
+
+A perl package for creating and manipulating HTML trees
+
+=item * L<HTML::ElementTable>
+
+An L<HTML::Tree> - based module which allows for manipulation of HTML
+trees using cartesian coordinations.
+
+=item * L<HTML::Seamstress>
+
+An L<HTML::Tree> - based module inspired by
+XMLC (L<http://xmlc.enhydra.org>), allowing for dynamic
+HTML generation via tree rewriting.
+
+=head1 TODO
+
+=over
+
+=item * highlander2
+
+currently the API expects the subtrees to survive or be pruned to be
+identified by id:
+
+ $if_then->highlander2([
+ under10 => sub { $_[0] < 10} ,
+ under18 => sub { $_[0] < 18} ,
+ welcome => [
+ sub { 1 },
+ sub {
+ my $branch = shift;
+ $branch->look_down(id => 'age')->replace_content($age);
+ }
+ ]
+ ],
+ $age
+ );
+
+but, it should be more flexible. the C<under10>, and C<under18> are
+expected to be ids in the tree... but it is not hard to have a check to
+see if this field is an array reference and if it, then to do a look
+down instead:
+
+ $if_then->highlander2([
+ [class => 'under10'] => sub { $_[0] < 10} ,
+ [class => 'under18'] => sub { $_[0] < 18} ,
+ [class => 'welcome'] => [
+ sub { 1 },
+ sub {
+ my $branch = shift;
+ $branch->look_down(id => 'age')->replace_content($age);
+ }
+ ]
+ ],
+ $age
+ );
+
+
+
+=cut
+
+=head1 SEE ALSO
+
+L<HTML::Seamstress>
+
+=head1 AUTHOR
+
+Terrence Brannon, E<lt>tbone@cpan.orgE<gt>
+
+Many thanks to BARBIE for his RT bug report.
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright (C) 2004 by Terrence Brannon
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself, either Perl version 5.8.4 or,
+at your option, any later version of Perl 5 you may have available.
+
+
+=cut