HTML::ElementTable - Perl extension for manipulating a table composed of HTML::Element style components.
use HTML::ElementTable;
# Create a table 0..10 x 0..12
$t = new HTML::ElementTable maxrow => 10, maxcol => 12;
# Populate cells with coordinates
$t->table->push_position;
# Manipulate <TABLE> tag
$t->attr('cellspacing',0);
$t->attr('border',1);
$t->attr('bgcolor','#DDBB00');
# Manipulate entire table - optimize on <TR> or pass to all <TD>
$t->table->attr('align','left');
$t->table->attr('valign','top');
# Manipulate rows (optimizes on <TR> if possible)
$t->row(0,2,4,6)->attr('bgcolor','#9999FF');
# Manipulate columns (all go to <TD> tags within column)
$t->col(0,4,8,12)->attr('bgcolor','#BBFFBB');
# Manipulate boxes (all go to <TD> elements
# unless it contains full rows, then <TR>)
$t->box(7,1 => 10,3)->attr('bgcolor','magenta');
$t->box(7,7 => 10,5)->attr('bgcolor','magenta');
$t->box(8,9 => 9,11)->attr('bgcolor','magenta');
$t->box(7,10 => 10,10)->attr('bgcolor','magenta');
# individual <TD> or <TH> attributes
$t->cell(8,6)->attr('bgcolor','#FFAAAA');
$t->cell(9,6)->attr('bgcolor','#FFAAAA');
$t->cell(7,9, 10,9, 7,11, 10,11)->attr('bgcolor','#FFAAAA');
# Take a look
print $t->as_HTML;
HTML::ElementTable provides a highly enhanced HTML::ElementSuper
structure with methods designed to easily manipulate table elements by
using coordinates. Elements can be manipulated in bulk by individual
cells, arbitrary groupings of cells, boxes, columns, rows, or the
entire table.
Table coordinates start at 0,0 in the upper left cell.
CONSTRUCTORS
- new()
-
- new(maxrow => row, maxcol => col)new(maxrow => row, maxcol => col)
-
Return a new HTML::ElementTable object. If the number of rows and
columns were provided, all elements required for the rows and columns
will be initialized as well. See extent().
- new_from_tree($tree)
-
Takes an existing top-level HTML::Element representing a table and
converts the entire table structure into a cohesive HTML::ElementTable
construct. (this is potentially useful if you want to use the power of
this module for editing HTML tables in situ within an
HTML::Element tree).
TABLE CONFIGURATION
- extent()
-
- extent(maxrow, maxcolumn)extent(maxrow, maxcolumn)
-
Set or return the extent of the current table. The maxrow and
maxcolumn parameters indicate the maximum row and column
coordinates you desire in the table. These are the coordinates of the
lower right cell in the table, starting from (0,0) at the upper left.
Providing a smaller extent than the current one will shrink the table
with no ill effect, provided you do not mind losing the information in
the clipped cells.
- maxrow()
-
Set or return the coordinate of the last row.
- maxcol()
-
Set or return the coordinate of the last column.
ELEMENT ACCESS
Unless accessing a single element, most table element access is
accomplished through globs, which are collections of elements that
behave as if they were a single element object.
Whenever possible, globbed operations are optimized into the most
appropriate element. For example, if you set an attribute for a row
glob, the attribute will be set either on the <TR> element or the
collected <TD> elements, whichever is appropriate.
See the HTML::ElementGlob(3) manpage for more information on element globs.
- cell(row,col,[row2,col2],[...])
-
Access an individual cell or collection of cells by their coordinates.
- row(row,[row2,...])
-
Access the contents of a row or collection of rows by row coordinate.
- col(col,[col2,...])
-
Access the contents of a column or collection of columns by column
coordinate.
- box(row_a1,col_a1,row_a2,col_a2,[row_b1,col_b1,row_b2,col_b2],[...])
-
Access the contents of a span of cells, specified as a box consisting of
two sets of coordinates. Multiple boxes can be specified.
- table()
-
Access all cells in the table. This is different from manipulating the
table object itself, which is reserved for such things as CELLSPACING
and other attributes specific to the <TABLE> tag. However, since
table()
returns a glob of cells, if the attribute is more appropriate for the
top level <TABLE> tag, it will be placed there rather than in each <TR>
tag or every <TD> tag.
ELEMENT/GLOB METHODS
The interfaces to a single table element or a glob of elements are
identical. All methods available from the HTML::ElementSuper class are
also available to a table element or glob of elements. See
the HTML::ElementSuper(3) manpage for details on these methods.
Briefly, here are some of the more useful methods provided by
HTML::ElementSuper:
- attr()
-
- push_content()
-
- replace_content()
-
- wrap_content()
-
- clone([element])
-
- mask([mode])
-
TABLE SPECIFIC EXTENSIONS
- blank_fill([mode])
-
Set or return the current fill mode for blank cells. The default is 0
for HTML::Element::Table elements. When most browsers render tables, if
they are empty you will get a box the color of your browser background
color rather than the BGCOLOR of that cell. When enabled, empty cells
are provided with an ' ', or invisible content, which will trigger
the rendering of the BGCOLOR for that cell.
Globbing was a convenient way to treat arbitrary collections of table
cells as if they were a single HTML element. Methods are generally
passed blindly and sequentially to the elements they contain.
Most of the time, this is fairly intuitive, such as when you are setting
the attributes of the cells.
Other times, it might be problematic, such as with push_content(). Do
you push the same object to all of the cells? HTML::Element based
classes only support one parent, so this breaks if you try to push the
same element into multiple parental hopefuls. In the specific case of
push_content() on globs, the elements that eventually get pushed are
clones of the originally provided content. It works, but it is not
necessarily what you expect. An incestuous HTML element tree is probably
not what you want anyway.
See the HTML::ElementGlob(3) manpage for more details on how globs work.
HTML::ElementSuper, HTML::ElementGlob
Matthew P. Sisk, <sisk@mojotoad.com>
Thanks to William R. Ward for some conceptual nudging.
Copyright (c) 1998-2010 Matthew P. Sisk. All rights reserved. All wrongs
revenged. This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
A useful page of HTML::ElementTable examples can be found at
http://www.mojotoad.com/sisk/projects/HTML-Element-Extended/examples.html.
HTML::ElementSuper(3), HTML::ElementGlob(3), HTML::Element(3), HTML::TableExtract(3), perl(1).
|