NAME

       HTML::ElementTable - Perl extension for manipulating a table composed of HTML::Element
       style components.

SYNOPSIS

         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;

DESCRIPTION

       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.

PUBLIC METHODS

       Table coordinates start at 0,0 in the upper left cell.

       CONSTRUCTORS

       new()
       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)
           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 HTML::ElementGlob(3) 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 HTML::ElementSuper(3) 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 '&nbsp;', or invisible
           content, which will trigger the rendering of the BGCOLOR for that cell.

NOTES ON GLOBS

       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 HTML::ElementGlob(3) for more details on how globs work.

REQUIRES

       HTML::ElementSuper, HTML::ElementGlob

AUTHOR

       Matthew P. Sisk, <sisk@mojotoad.com>

ACKNOWLEDGEMENTS

       Thanks to William R. Ward for some conceptual nudging.

COPYRIGHT

       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.

SEE ALSO

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