+=head3 Simplifying calls to HTML::FillInForm
+
+Since HTML::FillInForm gets and returns strings, using HTML::Element instances
+becomes tedious:
+
+ 1. Seamstress has an HTML tree that it wants the form filled in on
+ 2. Seamstress converts this tree to a string
+ 3. FillInForm parses the string into an HTML tree and then fills in the form
+ 4. FillInForm converts the HTML tree to a string
+ 5. Seamstress re-parses the HTML for additional processing
+
+I've filed a bug about this:
+L<https://rt.cpan.org/Ticket/Display.html?id=44105>
+
+This function, fillinform,
+allows you to pass a tree to fillinform (along with your data structure) and
+get back a tree:
+
+ my $new_tree = $html_tree->fillinform($data_structure);
+
+
+=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<content_handler>. Two other methods, C<hashmap> and C<datamap> 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:
+
+ <h1>user data</h1>
+ <span id="name">?</span>
+ <span id="email">?</span>
+ <span id="gender">?</span>
+
+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<content_handler> 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
+
+ <span id="name">?</span>
+
+would come out as
+
+ <span id="name"></span>
+
+(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
+
+ <span id="name">?</span>
+
+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:
+
+
+ <table>
+ <tr sclass="tr" class="alt" align="left" valign="top">
+ <td smap="people_id">1</td>
+ <td smap="phone">(877) 255-3239</td>
+ <td smap="password">*********</td>
+ </tr>
+ </table>
+
+In the table above, there are several attributes named C<< smap >>. 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->hashmap(smap => \%data, ['password']);
+
+
+Note: 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.
+
+Also note: the function C<< hashmap >> has a simple easy-to-type API. Interally, it calls C<< hash_map >>
+(which has a more verbose keyword calling API). Thus, the above call to C<hashmap()> results in this call:
+
+ $tree->hash_map(hash => \%data, to_attr => 'sid', excluding => ['password']);
+
+=head4 $elem->defmap($attr_name, \%hashref, $debug)
+
+C<defmap> was described above.
+
+
+=head4 $elem->content_handler(%hashref)
+
+C<content_handler> is described below.
+
+