usually can be found as the first child of the parent
\&
\& gi_tr => \*(Aqiterate\*(Aq,
\&
\& # 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 tags
\&
\& td_data => sub {
\& my ($tr_node, $tr_data) = @_;
\& $tr_node\->content_handler($_ => $tr_data\->{$_})
\& for qw(name age weight)
\& }
\& );
\&
\& print $seamstress\->as_HTML;
.Ve
.PP
Looping over Multiple Sample Rows
.IX Subsection "Looping over Multiple Sample Rows"
.PP
* \s-1HTML\s0
.PP
.Vb 10
\&
\&
\& | name | age | weight |
\&
\& | NATURE BOY RIC FLAIR |
\& 35 |
\& 220 |
\&
\&
\& | NATURE BOY RIC FLAIR |
\& 35 |
\& 220 |
\&
\&
\&
.Ve
.PP
* Only one change to last \s-1API\s0 call.
.PP
This:
.PP
.Vb 1
\& gi_tr => \*(Aqiterate\*(Aq,
.Ve
.PP
becomes this:
.PP
.Vb 1
\& gi_tr => [\*(Aqiterate1\*(Aq, \*(Aqiterate2\*(Aq]
.Ve
.PP
\fI\f(CI$tree\fI\->\fItable2()\fI : New \s-1API\s0 Call to Unroll a Table\fR
.IX Subsection "$tree->table2() : New API Call to Unroll a Table"
.PP
After 2 or 3 years with \f(CW\*(C`table()\*(C'\fR, I began to develop production
websites with it and decided it needed a cleaner interface,
particularly in the area of handling the fact that \f(CW\*(C`id\*(C'\fR tags will be
the same after cloning a table row.
.PP
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.
.PP
Dry/technical parameter documentation
.IX Subsection "Dry/technical parameter documentation"
.PP
\&\f(CW\*(C`$tree\->table2(%param)\*(C'\fR takes the following arguments:
.IP "\(bu" 4
\&\f(CW\*(C`table_ld => $look_down\*(C'\fR : optional
.Sp
How to find the \f(CW\*(C`table\*(C'\fR element in \f(CW$tree\fR. If \f(CW$look_down\fR is an
arrayref, then use \f(CW\*(C`look_down\*(C'\fR. If it is a \s-1CODE\s0 ref, then call it,
passing it \f(CW$tree\fR.
.Sp
Defaults to \f(CW\*(C`[\*(Aq_tag\*(Aq => \*(Aqtable\*(Aq]\*(C'\fR if not passed in.
.IP "\(bu" 4
\&\f(CW\*(C`table_data => $tabular_data\*(C'\fR : required
.Sp
The data to fill the table with. \fIMust\fR be passed in.
.IP "\(bu" 4
\&\f(CW\*(C`table_proc => $code_ref\*(C'\fR : not implemented
.Sp
A subroutine to do something to the table once it is found. Not
currently implemented. Not obviously necessary. Just created because
there is a \f(CW\*(C`tr_proc\*(C'\fR and \f(CW\*(C`td_proc\*(C'\fR.
.IP "\(bu" 4
\&\f(CW\*(C`tr_ld => $look_down\*(C'\fR : optional
.Sp
Same as \f(CW\*(C`table_ld\*(C'\fR but for finding the table row elements. Please
note that the \f(CW\*(C`tr_ld\*(C'\fR is done on the table node that was found
\&\fIinstead\fR of the whole \s-1HTML\s0 tree. This makes sense. The \f(CW\*(C`tr\*(C'\fRs that
you want exist below the table that was just found.
.Sp
Defaults to \f(CW\*(C`[\*(Aq_tag\*(Aq => \*(Aqtr\*(Aq]\*(C'\fR if not passed in.
.IP "\(bu" 4
\&\f(CW\*(C`tr_data => $code_ref\*(C'\fR : optional
.Sp
How to take the \f(CW\*(C`table_data\*(C'\fR and return a row. Defaults to:
.Sp
.Vb 3
\& sub { my ($self, $data) = @_;
\& shift(@{$data}) ;
\& }
.Ve
.IP "\(bu" 4
\&\f(CW\*(C`tr_proc => $code_ref\*(C'\fR : optional
.Sp
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 \f(CW\*(C`id\*(C'\fR attribute
unique:
.Sp
.Vb 4
\& sub {
\& my ($self, $tr, $tr_data, $tr_base_id, $row_count) = @_;
\& $tr\->attr(id => sprintf "%s_%d", $tr_base_id, $row_count);
\& }
.Ve
.IP "\(bu" 4
\&\f(CW\*(C`td_proc => $code_ref\*(C'\fR : required
.Sp
This coderef will take the row of data and operate on the \f(CW\*(C`td\*(C'\fR cells
that are children of the \f(CW\*(C`tr\*(C'\fR. See \f(CW\*(C`t/table2.t\*(C'\fR for several usage
examples.
.Sp
Here's a sample one:
.Sp
.Vb 7
\& sub {
\& my ($tr, $data) = @_;
\& my @td = $tr\->look_down(\*(Aq_tag\*(Aq => \*(Aqtd\*(Aq);
\& for my $i (0..$#td) {
\& $td[$i]\->splice_content(0, 1, $data\->[$i]);
\& }
\& }
.Ve
.PP
Conversational parameter documentation
.IX Subsection "Conversational parameter documentation"
.PP
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
.PP
.Vb 1
\& [\*(Aq_tag\*(Aq => \*(Aqtable\*(Aq]
.Ve
.PP
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 \f(CW\*(C`next\*(C'\fRable iterator, a \s-1DBI\s0
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 \f(CW\*(C`table_ld\*(C'\fR and
\&\f(CW\*(C`table_data\*(C'\fR respectively. A little more on \f(CW\*(C`table_ld\*(C'\fR. If this
happens to be a \s-1CODE\s0 ref, then execution of the code ref is presumed
to return the \f(CW\*(C`HTML::Element\*(C'\fR representing the table in the \s-1HTML\s0
tree.
.PP
Next, we get the row or rows which serve as sample \f(CW\*(C`tr\*(C'\fR elements by
doing a \f(CW\*(C`look_down\*(C'\fR from the \f(CW\*(C`table_elem\*(C'\fR. While normally one sample
row is enough to unroll a table, consider when you have alternating
table rows. This \s-1API\s0 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 \f(CW\*(C`tr\*(C'\fR row by mutating the element in
\&\f(CW\*(C`tr_proc\*(C'\fR, discussed below. The default \f(CW\*(C`tr_ld\*(C'\fR is \f(CW\*(C`[\*(Aq_tag\*(Aq =>
\&\*(Aqtr\*(Aq]\*(C'\fR but you can overwrite it. Note well, if you overwrite it with
a subroutine, then it is expected that the subroutine will return the
\&\f(CW\*(C`HTML::Element\*(C'\fR(s) which are \f(CW\*(C`tr\*(C'\fR element(s). The reason a
subroutine might be preferred is in the case that the \s-1HTML\s0 designers
gave you 8 sample \f(CW\*(C`tr\*(C'\fR 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 \s-1API\s0 call can clone
it and supply it to the \f(CW\*(C`tr_proc\*(C'\fR and \f(CW\*(C`td_proc\*(C'\fR calls.
.PP
Now, as we move through the table rows with table data, we need to do
two different things on each table row:
.IP "\(bu" 4
get one row of data from the \f(CW\*(C`table_data\*(C'\fR via \f(CW\*(C`tr_data\*(C'\fR
.Sp
The default procedure assumes the \f(CW\*(C`table_data\*(C'\fR is an array reference
and shifts a row off of it:
.Sp
.Vb 4
\& sub {
\& my ($self, $data) = @_;
\& shift @{$data};
\& }
.Ve
.Sp
Your function \s-1MUST\s0 return undef when there is no more rows to lay out.
.IP "\(bu" 4
take the \f(CW\*(C`tr\*(C'\fR element and mutate it via \f(CW\*(C`tr_proc\*(C'\fR
.Sp
The default procedure simply makes the id of the table row unique:
.Sp
.Vb 4
\& sub {
\& my ($self, $tr, $tr_data, $row_count, $root_id) = @_;
\& $tr\->attr(id => sprintf "%s_%d", $root_id, $row_count);
\& }
.Ve
.PP
Now that we have our row of data, we call \f(CW\*(C`td_proc\*(C'\fR so that it can
take the data and the \f(CW\*(C`td\*(C'\fR cells in this \f(CW\*(C`tr\*(C'\fR and process them. This
function \fImust\fR be supplied.
.PP
\fIWhither a Table with No Rows\fR
.IX Subsection "Whither a Table with No Rows"
.PP
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:
.PP
.Vb 10
\&
\&
\&
\&
\&
\&
\& | name | age | weight |
\&
\& | NATURE BOY RIC FLAIR |
\& 35 |
\& 220 |
\&
\&
\&
\&
.Ve
.SS "Tree-Killing Methods"
.IX Subsection "Tree-Killing Methods"
\fI\f(CI$tree\fI\->prune\fR
.IX Subsection "$tree->prune"
.PP
This removes any nodes from the tree which consist of nothing or
nothing but whitespace. See also delete_ignorable_whitespace in
HTML::Element.
.SS "Loltree Functions"
.IX Subsection "Loltree Functions"
A loltree is an arrayref consisting of arrayrefs which is used by \f(CW\*(C`new_from_\|_lol\*(C'\fR in HTML::Element to produce \s-1HTML\s0 trees. The \s-1CPAN\s0
distro XML::Element::Tolol creates such \s-1XML\s0 trees by parsing \s-1XML\s0
files, analogous to XML::Toolkit. The purpose of the functions in
this section is to allow you manipulate a loltree programmatically.
.PP
These could not be methods because if you bless a loltree, then
HTML::Tree will barf.
.PP
\fIHTML::Element::newchild($lol, \f(CI$parent_label\fI, \f(CI@newchild\fI)\fR
.IX Subsection "HTML::Element::newchild($lol, $parent_label, @newchild)"
.PP
Given this initial loltree:
.PP
.Vb 1
\& my $initial_lol = [ note => [ shopping => [ item => \*(Aqsample\*(Aq ] ] ];
.Ve
.PP
This code:
.PP
.Vb 4
\& sub shopping_items {
\& my @shopping_items = map { [ item => _ ] } qw(bread butter beans);
\& @shopping_items;
\& }
\&
\& my $new_lol = HTML::Element::newnode($initial_lol, item => shopping_items());
\&
\& will replace the single sample with a list of shopping items:
\&
\& [
\& \*(Aqnote\*(Aq,
\& [
\& \*(Aqshopping\*(Aq,
\& [
\& \*(Aqitem\*(Aq,
\& \*(Aqbread\*(Aq
\& ],
\& [
\& \*(Aqitem\*(Aq,
\& \*(Aqbutter\*(Aq
\& ],
\& [
\& \*(Aqitem\*(Aq,
\& \*(Aqbeans\*(Aq
\& ]
\&
\& ]
\& ];
.Ve
.PP
Thanks to kcott and the other Perlmonks in this thread:
http://www.perlmonks.org/?node_id=912416
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.SS "HTML::Tree"
.IX Subsection "HTML::Tree"
A perl package for creating and manipulating \s-1HTML\s0 trees.
.SS "HTML::ElementTable"
.IX Subsection "HTML::ElementTable"
An HTML::Tree \- based module which allows for manipulation of \s-1HTML\s0
trees using cartesian coordinations.
.SS "HTML::Seamstress"
.IX Subsection "HTML::Seamstress"
An HTML::Tree \- based module inspired by \s-1XMLC
\&\s0(), allowing for dynamic \s-1HTML\s0 generation via
tree rewriting.
.SS "Push-style templating systems"
.IX Subsection "Push-style templating systems"
A comprehensive cross-language
list of push-style templating systems .
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 4
highlander2
.Sp
currently the \s-1API\s0 expects the subtrees to survive or be pruned to be
identified by id:
.Sp
.Vb 11
\& $if_then\->highlander2([
\& under10 => sub { $_[0] < 10} ,
\& under18 => sub { $_[0] < 18} ,
\& welcome => [
\& sub { 1 },
\& sub {
\& my $branch = shift;
\& $branch\->look_down(id => \*(Aqage\*(Aq)\->replace_content($age);
\& }
\& ]
\& ], $age);
.Ve
.Sp
but, it should be more flexible. the \f(CW\*(C`under10\*(C'\fR, and \f(CW\*(C`under18\*(C'\fR are
expected to be ids in the tree... but it is not hard to have a check
to see if this field is an array reference and if it, then to do a
look down instead:
.Sp
.Vb 11
\& $if_then\->highlander2([
\& [class => \*(Aqunder10\*(Aq] => sub { $_[0] < 10} ,
\& [class => \*(Aqunder18\*(Aq] => sub { $_[0] < 18} ,
\& [class => \*(Aqwelcome\*(Aq] => [
\& sub { 1 },
\& sub {
\& my $branch = shift;
\& $branch\->look_down(id => \*(Aqage\*(Aq)\->replace_content($age);
\& }
\& ]
\& ], $age);
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Original author Terrence Brannon, .
.PP
Adopted by Marius Gavrilescu \f(CW\*(C`\*(C'\fR.
.PP
I appreciate the feedback from M. David Moussa Leo Keita regarding
some issues with the test suite, namely (1) \s-1CRLF\s0 leading to test
breakage in \fIt/crunch.t\fR and (2) using the wrong module in
\&\fIt/prune.t\fR thus not having the right functionality available.
.PP
Many thanks to \s-1BARBIE\s0 for his \s-1RT\s0 bug report.
.PP
Many thanks to perlmonk kcott for his work on array rewriting:
. It was crucial in the
development of newchild.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Coypright (C) 2014\-2016 by Marius Gavrilescu
.PP
Copyright (C) 2004\-2012 by Terrence Brannon
.PP
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.
|
\& 
\& 
.Ve
.PP
and then when the tree of \s-1HTML\s0 is being processed, you make this call:
.PP
.Vb 5
\& my %closures = (
\& lnc => sub { my ($tree, $mute_node, $attr_value)= @_; "http://lnc.usc.edu$attr_value" },
\& playboy => sub { my ($tree, $mute_node, $attr_value)= @_; "http://playboy.com$attr_value" }
\& foobar => sub { my ($tree, $mute_node, $attr_value)= @_; "http://foobar.info$attr_value" }
\& )
\&
\& $tree\->overwrite_attr(fixup => \e%closures) ;
.Ve
.PP
and the tags come out modified like so:
.PP
.Vb 3
\& 
\& 
\& 
.Ve
.PP
\fI\f(CI$tree\fI\->mute_elem($mutation_attr => \f(CI$mutating_closures\fI, [ \f(CI$post_hook\fI ] )\fR
.IX Subsection "$tree->mute_elem($mutation_attr => $mutating_closures, [ $post_hook ] )"
.PP
This is a generalization of \f(CW\*(C`overwrite_attr\*(C'\fR. \f(CW\*(C`overwrite_attr\*(C'\fR
assumes the return value of the closure is supposed overwrite an
attribute value and does it for you. \f(CW\*(C`mute_elem\*(C'\fR is a more general
function which does nothing but hand the closure the element and let
it mutate it as it jolly well pleases :)
.PP
In fact, here is the implementation of \f(CW\*(C`overwrite_attr\*(C'\fR to give you a
taste of how \f(CW\*(C`mute_attr\*(C'\fR is used:
.PP
.Vb 2
\& sub overwrite_action {
\& my ($mute_node, %X) = @_;
\&
\& $mute_node\->attr($X{local_attr}{name} => $X{local_attr}{value}{new});
\& }
\&
\&
\& sub HTML::Element::overwrite_attr {
\& my $tree = shift;
\&
\& $tree\->mute_elem(@_, \e&overwrite_action);
\& }
.Ve
.SS "Tree-Building Methods"
.IX Subsection "Tree-Building Methods"
\fIUnrolling an array via a single sample element (