+++ /dev/null
-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.
-
- Element Decoration Methods
- HTML::Element::Library::super_literal($text)
- In 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 "super_literal" your text and back comes your
- text wrapped in a "~literal" element.
-
- One of these days, I'll around to writing a nice "EXPORT" section.
-
- 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: Single ("li") Iteration
- This is best described by example. Given this HTML:
-
- <strong>Here are the things I need from the store:</strong>
- <ul>
- <li id="store_items">Sample item</li>
- </ul>
-
- We can unroll it like so:
-
- my $li = $tree->look_down(id => '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 id="store_items:1">bread</li>
- <li id="store_items:2">butter</li>
- <li id="store_items:3">vodka</li>
- </ul>
- </body>
- </html>
-
- 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;
-
- $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;
-
- 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']
-
- $tree->table2() : New API Call to Unroll a Table
- After 2 or 3 years with "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 "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.
-
- Dry/technical parameter documentation
- "$tree->table2(%param)" takes the following arguments:
-
- * "table_ld => $look_down" : optional
- How to find the "table" element in $tree. If $look_down is an
- arrayref, then use "look_down". If it is a CODE ref, then call it,
- passing it $tree.
-
- Defaults to "['_tag' => 'table']" if not passed in.
-
- * "table_data => $tabular_data" : required
- The data to fill the table with. *Must* be passed in.
-
- * "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 "tr_proc" and "td_proc".
-
- * "tr_ld => $look_down" : optional
- Same as "table_ld" but for finding the table row elements. Please
- note that the "tr_ld" is done on the table node that was found below
- *instead* of the whole HTML tree. This makes sense. The "tr"s that
- you want exist below the table that was just found.
-
- * "tr_data => $code_ref" : optional
- How to take the "table_data" and return a row. Defaults to:
-
- sub { my ($self, $data) = @_;
- shift(@{$data}) ;
- }
-
- * "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 "id" attribute
- unique:
-
- sub {
- my ($self, $tr, $tr_data, $row_count, $root_id) = @_;
- $tr->attr(id => sprintf "%s_%d", $root_id, $row_count);
- }
-
- * "td_proc => $code_ref" : required
- This coderef will take the row of data and operate on the "td" cells
- that are children of the "tr". See "t/table2.t" for several usage
- examples.
-
- 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 "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 "table_ld"
- and "table_data" respectively. A little more on "table_ld". If this
- happens to be a CODE ref, then execution of the code ref is presumed
- to return the "HTML::Element" representing the table in the HTML
- tree.
-
- Next, we get the row or rows which serve as sample "tr" elements by
- doing a "look_down" from the "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 "tr" row by mutating the element in
- "tr_proc", discussed below. The default "tr_ld" is "['_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 "HTML::Element"(s) which are "tr" element(s). The reason a
- subroutine might be preferred is in the case that the HTML designers
- gave you 8 sample "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 "tr_proc" and "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:
-
- * get one row of data from the "table_data" via "tr_data"
- The default procedure assumes the "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.
-
- * take the "tr" element and mutate it via "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);
- }
-
- Now that we have our row of data, we call "td_proc" so that it can
- take the data and the "td" cells in this "tr" and process them. This
- function *must* be supplied.
-
- 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>), allowing for dynamic HTML
- generation via tree rewriting.
-
-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.
-
projects / html-element-library.git / commitdiff