hash_map method about to be public for real

[html-element-library.git] / lib / HTML / Element / Library.pm

diff --git a/lib/HTML/Element/Library.pm b/lib/HTML/Element/Library.pm
index 03958537bf76139cf8f75e7c55edd43f1f39a9e7..7c6cf7557808cc42dc40b5c89fa4b55a27dc470f 100644 (file)
--- a/lib/HTML/Element/Library.pm
+++ b/lib/HTML/Element/Library.pm
@@ -12,6 +12,7 @@ use Array::Group qw(:all);
 use Carp qw(confess);
 use Data::Dumper;
 use HTML::Element;
+use List::Util qw(first);
 use List::MoreUtils qw/:all/;
 use Params::Validate qw(:all);
 use Scalar::Listify;
@@ -36,21 +37,40 @@ sub HTML::Element::siblings {
   $p->content_list;
 }
 
+sub HTML::Element::hash_map {
+    my $container = shift;
+
+    my %p = validate(@_, {
+                         hash => { type => HASHREF },
+                         to_attr => 1,
+                         excluding => { type => ARRAYREF },
+                         debug => { default => 0 },
+                        });
+
+    my @same_as = $container->look_down('_attr' => $p{to_attr});
+
+    for my $same_as (@same_as) {
+       next if first { $same_as->attr($p{to_attr})  eq $_ } @{$p{excluding}} ;
+       my $hash_key =  $same_as->attr($p{to_attr}) ;
+       $same_as->replace_content( $p{hash}->{$hash_key} ) ;
+    }
+
+}
+
+
 sub HTML::Element::passover {
   my ($tree, $child_id) = @_;
   
-  #warn "ARGS:   my ($tree, $child)";
+  warn "ARGS:   my ($tree, $child_id)" if $DEBUG;
+  warn $tree->as_HTML(undef, ' ') if $DEBUG;
 
   my $exodus = $tree->look_down(id => $child_id);
 
-  my @s = HTML::Element::siblings($exodus);
+  warn "E: $exodus" if $DEBUG;
 
-  warn "sibling count", scalar @s;
-  warn "siblings", join ':', @s;
+  my @s = HTML::Element::siblings($exodus);
 
   for my $s (@s) {
-    warn "SIBLING: $s";
-    warn "ref sib", ref $s;
     next unless ref $s;
     if ($s->attr('id') eq $child_id) {
       ;
@@ -116,9 +136,12 @@ sub HTML::Element::position {
 
 
 sub HTML::Element::content_handler {
-  my ($tree, $id_name, $content) = @_;
+  my ($tree, %content_hash) = @_;
+
+  for my $k (keys %content_hash) {
+      $tree->set_child_content(id => $k, $content_hash{$k});      
+  }
 
-  $tree->set_child_content(id => $id_name, $content);
 
 }
 
@@ -190,6 +213,7 @@ sub HTML::Element::iter2 {
   warn "wrapper_data: " . Dumper $p{wrapper_data} if $p{debug} ;
 
   my $container = ref_or_ld($tree, $p{wrapper_ld});
+  warn "container: " . $container if $p{debug} ;
   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} ;
@@ -557,9 +581,9 @@ sub HTML::Element::table2 {
   #  ++$DEBUG if $table{debug} ;
 
   # Get the table element
-  warn 1;
+  #warn 1;
   $table->{table_node} = ref_or_ld( $tree, $p{table_ld} ) ;
-  warn 2;
+  #warn 2;
   $table->{table_node} or confess
     "table tag not found via " . Dumper($p{table_ld}) ;
 
@@ -598,12 +622,12 @@ sub HTML::Element::table2 {
        if defined $p{tr_proc};
 
     warn  "data row redux: " . Dumper $row if $p{debug};
-    warn 3.3;
+    #warn 3.3;
 
     $p{td_proc}->($new_tr_node, $row);
     push @table_rows, $new_tr_node;
 
-    warn 4.4;
+    #warn 4.4;
 
     redo;
   }
@@ -727,6 +751,31 @@ One of these days, I'll around to writing a nice C<EXPORT> section.
 
 =head2 Tree Rewriting Methods
 
+=head3 $elem->hash_map(hash => \%h, to_attr => $attr, excluding => \@excluded)
+
+This method is designed to take a hashref and populate a series of elements. For example:
+
+
+  <table>
+    <tr sclass="tr" class="alt" align="left" valign="top">
+      <td sid="people_id">1</td>
+      <td sid="phone">(877) 255-3239</td>
+      <td sid="password">*********</td>
+    </tr>
+  </table>
+
+In the table above, there are several attributes named C<sid>. If we have a hashref whose keys are the same:
+
+  my %data = (people_id => 888, phone => '444-4444', password => 'dont-you-dare-render');
+
+Then a single API call allows us to populate the HTML while excluding those ones we dont:
+
+  $tree->hash_map(hash => \%data, to_attr => 'sid', excluding => ['password']);
+
+Of course, the other way to prevent rendering some of the hash mapping is to not give that element the attr
+you plan to use for hash mapping.
+
+
 =head3 $elem->replace_content(@new_elem)
 
 Replaces all of C<$elem>'s content with C<@new_elem>. 
@@ -742,7 +791,7 @@ happens to be a non-element, a push_content is performed instead.
 
 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)
+=head3 $tree->content_handler(%id_content)
 
 This is a convenience method. Because the look_down criteria will often simply be:
 
@@ -760,6 +809,15 @@ Instead of typing:
 
   $elem->set_child_content(sid => 'fixme', 'new text') 
 
+PLEASE NOTE: you can pass a hash whose keys are C<id>s and whose values are the content you want there and it will perform the replacement on each hash member:
+
+  my %id_content = (name => "Terrence Brannon",      
+                    email => 'tbrannon@in.com',
+                    balance => 666,                         
+                    content => $main_content);             
+
+  $tree->content_handler(%id_content);  
+
 =head3 $tree->highlander($subtree_span_id, $conditionals, @conditionals_args)
 
 This allows for "if-then-else" style processing. Highlander was a movie in
@@ -955,7 +1013,11 @@ to give you a taste of how C<mute_attr> is used:
 
 
 
-=head2 Tree-Building Methods: Unrolling an array via a single sample element (<ul> container)
+=head2 Tree-Building Methods
+
+
+
+=head3 Unrolling an array via a single sample element (<ul> container)
 
 This is best described by example. Given this HTML:
 
@@ -986,7 +1048,7 @@ To produce this:
   </body>
  </html>
 
-=head2 Tree-Building Methods: Unrolling an array via n sample elements (<dl> container)
+=head3 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
@@ -1143,7 +1205,9 @@ So now that we have documented the API, let's see the call we need:
  );
 
 
-=head2 Tree-Building Methods: Select Unrolling
+
+
+=head3 Select Unrolling
 
 The C<unroll_select> method has this API: