The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
HTML-Element-Library-0.05
River stage one • 1 direct dependent • 1 total dependent
++
/ HTML::Element::Library

NAME

HTML::Element::Library - HTML::Element convenience functions

SYNOPSIS

  use HTML::Element::Library;
  use HTML::TreeBuilder;

DESCRIPTION

This method provides API calls for common actions on trees when using HTML::Tree.

METHODS

The test suite contains examples of each of these methods in a file t/$method.t

Positional Querying Methods

$elem->siblings

Return a list of all nodes under the same parent.

$elem->sibdex

Return the index of $elem into the array of siblings of which it is a part. HTML::ElementSuper calls this method addr but I don't think that is a descriptive name. And such naming is deceptively close to the address function of HTML::Element. HOWEVER, in the interest of backwards compatibility, both methods are available.

$elem->addr

Same as sibdex

$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.

Tree Rewriting Methods

$elem->replace_content($new_elem)

Replaces all of $elem's content with $new_elem.

$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.

$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.

$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')

$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 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 span tag with id 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 under10 remains. For age less than 18, the node with id under18 remains. Otherwise our "else" condition fires and the child with id welcome remains.

Tree-Building Methods: Select Unrolling

The 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 } )

Tree-Building Methods: Table Generation

Matthew Sisk has a much more intuitive (imperative) way to generate tables via his module 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 HTML::Tree API calls. Then the table method available here is discussed.

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;

Sample Usage:

       my $data = Simple::Class->load_data;
       ++$_->{age} for @$data

Inline Code to Unroll a Table

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>

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;

Seamstress 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;

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']

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>

SEE ALSO

  • HTML::Tree

    A perl package for creating and manipulating HTML trees

  • HTML::ElementTable

    An HTML::Tree - based module which allows for manipulation of HTML trees using cartesian coordinations.

  • HTML::Seamstress

    An HTML::Tree - based module inspired by XMLC:

     http://xmlc.enhydra.org

    which allows for non-embedded tree-based HTML templating.

AUTHOR

Terrence Brannon, <tbone@cpan.org>

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.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 731:

You forgot a '=back' before '=head1'