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 tags
td_data => sub {
my ($tr_node, $tr_data) = @_;
$tr_node->content_handler($_ => $tr_data->{$_})
for qw(name age weight)
}
);
print $seamstress->as_HTML;
=head4 Looping over Multiple Sample Rows
* HTML
name | age | weight |
NATURE BOY RIC FLAIR |
35 |
220 |
NATURE BOY RIC FLAIR |
35 |
220 |
* Only one change to last API call.
This:
gi_tr => 'iterate',
becomes this:
gi_tr => ['iterate1', 'iterate2']
=head3 $tree->table2() : New API Call to Unroll a Table
After 2 or 3 years with C, I began to develop production
websites with it and decided it needed a cleaner interface,
particularly in the area of handling the fact that C 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.
=head4 Dry/technical parameter documentation
C<< $tree->table2(%param) >> takes the following arguments:
=over
=item * C<< table_ld => $look_down >> : optional
How to find the C element in C<$tree>. If C<$look_down> is an
arrayref, then use C. If it is a CODE ref, then call it,
passing it C<$tree>.
Defaults to C<< ['_tag' => 'table'] >> if not passed in.
=item * C<< table_data => $tabular_data >> : required
The data to fill the table with. I be passed in.
=item * C<< 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 C and C.
=item * C<< tr_ld => $look_down >> : optional
Same as C but for finding the table row elements. Please
note that the C is done on the table node that was found
I of the whole HTML tree. This makes sense. The Cs that
you want exist below the table that was just found.
Defaults to C<< ['_tag' => 'tr'] >> if not passed in.
=item * C<< tr_data => $code_ref >> : optional
How to take the C and return a row. Defaults to:
sub { my ($self, $data) = @_;
shift(@{$data}) ;
}
=item * C<< 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 C attribute
unique:
sub {
my ($self, $tr, $tr_data, $tr_base_id, $row_count) = @_;
$tr->attr(id => sprintf "%s_%d", $tr_base_id, $row_count);
}
=item * C<< td_proc => $code_ref >> : required
This coderef will take the row of data and operate on the C cells
that are children of the C | . See C for several usage
examples.
Here's a sample one:
sub {
my ($tr, $data) = @_;
my @td = $tr->look_down('_tag' => 'td');
for my $i (0..$#td) {
$td[$i]->splice_content(0, 1, $data->[$i]);
}
}
=cut
=head4 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 Cable 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 C and
C respectively. A little more on C. If this
happens to be a CODE ref, then execution of the code ref is presumed
to return the C representing the table in the HTML
tree.
Next, we get the row or rows which serve as sample C elements by
doing a C from the C. 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 C row by mutating the element in
C, discussed below. The default C is C<< ['_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
C(s) which are C element(s). The reason a
subroutine might be preferred is in the case that the HTML designers
gave you 8 sample C 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 C and C calls.
Now, as we move through the table rows with table data, we need to do
two different things on each table row:
=over 4
=item * get one row of data from the C via C
The default procedure assumes the C 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.
=item * take the C element and mutate it via C
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);
}
=back
Now that we have our row of data, we call C so that it can
take the data and the C cells in this C | and process them. This
function I be supplied.
=head3 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:
name | age | weight |
NATURE BOY RIC FLAIR |
35 |
220 |
=head2 Tree-Killing Methods
=head3 $tree->prune
This removes any nodes from the tree which consist of nothing or
nothing but whitespace. See also delete_ignorable_whitespace in
L.
=head2 Loltree Functions
A loltree is an arrayref consisting of arrayrefs which is used by C<<
new_from__lol >> in L to produce HTML trees. The CPAN
distro L creates such XML trees by parsing XML
files, analagous to L. The purpose of the functions in
this section is to allow you manipulate a loltree programmatically.
These could not be methods because if you bless a loltree, then
HTML::Tree will barf.
=head3 HTML::Element::newchild($lol, $parent_label, @newchild)
Given this initial loltree:
my $initial_lol = [ note => [ shopping => [ item => 'sample' ] ] ];
This code:
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:
[
'note',
[
'shopping',
[
'item',
'bread'
],
[
'item',
'butter'
],
[
'item',
'beans'
]
]
];
Thanks to kcott and the other Perlmonks in this thread:
http://www.perlmonks.org/?node_id=912416
=head1 SEE ALSO
=head2 L
A perl package for creating and manipulating HTML trees.
=head2 L
An L - based module which allows for manipulation of HTML
trees using cartesian coordinations.
=head2 L
An L - based module inspired by XMLC
(L), allowing for dynamic HTML generation via
tree rewriting.
=head2 Push-style templating systems
A comprehensive cross-language
L.
=head1 TODO
=over
=item * highlander2
currently the API expects the subtrees to survive or be pruned to be
identified by id:
$if_then->highlander2([
under10 => sub { $_[0] < 10} ,
under18 => sub { $_[0] < 18} ,
welcome => [
sub { 1 },
sub {
my $branch = shift;
$branch->look_down(id => 'age')->replace_content($age);
}
]
], $age);
but, it should be more flexible. the C, and C 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:
$if_then->highlander2([
[class => 'under10'] => sub { $_[0] < 10} ,
[class => 'under18'] => sub { $_[0] < 18} ,
[class => 'welcome'] => [
sub { 1 },
sub {
my $branch = shift;
$branch->look_down(id => 'age')->replace_content($age);
}
]
], $age);
=head1 AUTHOR and ACKS
Terrence Brannon, Etbone@cpan.orgE
I appreciate the feedback from M. David Moussa Leo Keita regarding
some issues with the test suite, namely (1) CRLF leading to test
breakage in F and (2) using the wrong module in
F thus not having the right functionality available.
Many thanks to BARBIE for his RT bug report.
Many thanks to perlmonk kcott for his work on array rewriting:
L. It was crucial in the
development of newchild.
=head2 Source Repo
The source is at L
=head1 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.
=cut
|