From 9a087986e1896870b46e15cebc8a5fa7e2233247 Mon Sep 17 00:00:00 2001 From: Terrence Brannon Date: Wed, 25 Feb 2009 10:13:49 -0500 Subject: [PATCH] docs --- lib/HTML/Element/Library.pm | 99 +++++++++++++++++++++++++++++++++++-- t/defmap.t | 2 +- 2 files changed, 96 insertions(+), 5 deletions(-) diff --git a/lib/HTML/Element/Library.pm b/lib/HTML/Element/Library.pm index 7573cbd..6b9e27a 100644 --- a/lib/HTML/Element/Library.pm +++ b/lib/HTML/Element/Library.pm @@ -38,11 +38,13 @@ sub HTML::Element::siblings { } sub HTML::Element::defmap { - my($tree,$attr,$hashref)=@_; + my($tree,$attr,$hashref,$debug)=@_; while (my ($k, $v) = (each %$hashref)) { + warn "defmap looks for ($attr => $k)" if $debug; my $found = $tree->look_down($attr => $k); if ($found) { + warn "($attr => $k) was found.. replacing with '$v'" if $debug; $found->replace_content( $v ); } } @@ -200,7 +202,6 @@ sub HTML::Element::iter { my @item = map { my $new_item = clone $p; $new_item->replace_content($_); - # $new_item->attr('id', $id_incr->( $p->attr('id') )); $new_item; } @data; @@ -796,7 +797,77 @@ One of these days, I'll around to writing a nice C section. =head2 Tree Rewriting Methods -=head3 $elem->hashmap($attr_name, \%hashref, \@excluded, $debug) +=head3 Mapping a hashref to HTML elements + +It is very common to get a hashref of data from some external source - flat file, database, XML, etc. +Therefore, it is important to have a convenient way of mapping this data to HTML. + +As it turns out, there are 3 ways to do this in HTML::Element::Library. +The most strict and structured way to do this is with +C. Two other methods, C and C require less manual mapping and may prove +even more easy to use in certain cases. + +As is usual with Perl, a practical example is always best. So let's take some sample HTML: + +

user data

+ ? + ? + ? + +Now, let's say our data structure is this: + + $ref = { email => 'jim@beam.com', gender => 'lots' } ; + +And let's start with the most strict way to get what you want: + + $tree->content_handler(email => $ref->{email} , gender => $ref->{gender}) ; + + +In this case, you manually state the mapping between id tags and hashref keys and +then C retrieves the hashref data and pops it in the specified place. + +Now let's look at the two (actually 2 and a half) other hash-mapping methods. + + $tree->hashmap(id => $ref); + +Now, what this function does is super-destructive. It finds every element in the tree +with an attribute named id (since 'id' is a parameter, it could find every element with +some other attribute also) and replaces the content of those elements with the hashref +value. + +So, in the case above, the + + ? + +would come out as + + + +(it would be blank) - because there is nothing in the hash with that value, so it substituted + + $ref->{name} + +which was blank and emptied the contents. + +Now, let's assume we want to protect name from being auto-assigned. Here is what you do: + + $tree->hashmap(id => $ref, ['name']); + +That last array ref is an exclusion list. + +But wouldnt it be nice if you could do a hashmap, but only assigned things which are defined +in the hashref? C<< defmap() >> to the rescue: + + $tree->defmap(id => $ref); + +does just that, so + + ? + +would be left alone. + + +=head4 $elem->hashmap($attr_name, \%hashref, \@excluded, $debug) This method is designed to take a hashref and populate a series of elements. For example: @@ -826,6 +897,15 @@ Also note: the function C<< hashmap >> has a simple easy-to-type API. Interally, $tree->hash_map(hash => \%data, to_attr => 'sid', excluding => ['password']); +=head4 $elem->defmap($attr_name, \%hashref, $debug) + +C was described above. + + +=head4 $elem->content_handler(%hashref) + +C is described below. + =head3 $elem->replace_content(@new_elem) @@ -860,7 +940,7 @@ Instead of typing: $elem->set_child_content(sid => 'fixme', 'new text') -PLEASE NOTE: you can pass a hash whose keys are Cs and whose values are the content you want there and it will perform the replacement on each hash member: +ALSO NOTE: you can pass a hash whose keys are Cs 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', @@ -1099,6 +1179,17 @@ To produce this: +Now, you might be wondering why the API call is: + + $tree->iter($li => @items) + +instead of: + + $li->iter(@items) + +and there is no good answer. The latter would be more concise and it is what I +should have done. + =head3 Unrolling an array via n sample elements (
container) C was fine for awhile, but some things diff --git a/t/defmap.t b/t/defmap.t index 9f61672..05c930d 100644 --- a/t/defmap.t +++ b/t/defmap.t @@ -19,7 +19,7 @@ sub tage { my %data = (pause => 'arsenal rules'); - $tree->defmap(smap => \%data); + $tree->defmap(smap => \%data, 1); my $generated_html = ptree($tree, "$root.gen"); -- 2.39.2