.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "HTML::ElementTable 3pm" .TH HTML::ElementTable 3pm "2022-12-02" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" HTML::ElementTable \- Perl extension for manipulating a table composed of HTML::Element style components. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& 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 tag \& $t\->attr(\*(Aqcellspacing\*(Aq,0); \& $t\->attr(\*(Aqborder\*(Aq,1); \& $t\->attr(\*(Aqbgcolor\*(Aq,\*(Aq#DDBB00\*(Aq); \& \& # Manipulate entire table \- optimize on or pass to all if possible) \& $t\->row(0,2,4,6)\->attr(\*(Aqbgcolor\*(Aq,\*(Aq#9999FF\*(Aq); \& \& # Manipulate columns (all go to ) \& $t\->box(7,1 => 10,3)\->attr(\*(Aqbgcolor\*(Aq,\*(Aqmagenta\*(Aq); \& $t\->box(7,7 => 10,5)\->attr(\*(Aqbgcolor\*(Aq,\*(Aqmagenta\*(Aq); \& $t\->box(8,9 => 9,11)\->attr(\*(Aqbgcolor\*(Aq,\*(Aqmagenta\*(Aq); \& $t\->box(7,10 => 10,10)\->attr(\*(Aqbgcolor\*(Aq,\*(Aqmagenta\*(Aq); \& \& # individual
\& $t\->table\->attr(\*(Aqalign\*(Aq,\*(Aqleft\*(Aq); \& $t\->table\->attr(\*(Aqvalign\*(Aq,\*(Aqtop\*(Aq); \& \& # Manipulate rows (optimizes on
tags within column) \& $t\->col(0,4,8,12)\->attr(\*(Aqbgcolor\*(Aq,\*(Aq#BBFFBB\*(Aq); \& \& # Manipulate boxes (all go to elements \& # unless it contains full rows, then
or attributes \& $t\->cell(8,6)\->attr(\*(Aqbgcolor\*(Aq,\*(Aq#FFAAAA\*(Aq); \& $t\->cell(9,6)\->attr(\*(Aqbgcolor\*(Aq,\*(Aq#FFAAAA\*(Aq); \& $t\->cell(7,9, 10,9, 7,11, 10,11)\->attr(\*(Aqbgcolor\*(Aq,\*(Aq#FFAAAA\*(Aq); \& \& # Take a look \& print $t\->as_HTML; .Ve .SH "DESCRIPTION" .IX Header "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. .SH "PUBLIC METHODS" .IX Header "PUBLIC METHODS" Table coordinates start at 0,0 in the upper left cell. .PP \&\s-1CONSTRUCTORS\s0 .IP "\fBnew()\fR" 4 .IX Item "new()" .PD 0 .IP "new(maxrow => row, maxcol => col)" 4 .IX Item "new(maxrow => row, maxcol => col)" .PD 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 \fBextent()\fR. .IP "new_from_tree($tree)" 4 .IX Item "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 \s-1HTML\s0 tables \fIin situ\fR within an HTML::Element tree). .PP \&\s-1TABLE CONFIGURATION\s0 .IP "\fBextent()\fR" 4 .IX Item "extent()" .PD 0 .IP "extent(maxrow, maxcolumn)" 4 .IX Item "extent(maxrow, maxcolumn)" .PD Set or return the extent of the current table. The \fImaxrow\fR and \&\fImaxcolumn\fR 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. .IP "\fBmaxrow()\fR" 4 .IX Item "maxrow()" Set or return the coordinate of the last row. .IP "\fBmaxcol()\fR" 4 .IX Item "maxcol()" Set or return the coordinate of the last column. .PP \&\s-1ELEMENT ACCESS\s0 .PP Unless accessing a single element, most table element access is accomplished through \fIglobs\fR, which are collections of elements that behave as if they were a single element object. .PP 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 <\s-1TR\s0> element or the collected <\s-1TD\s0> elements, whichever is appropriate. .PP See \fBHTML::ElementGlob\fR\|(3) for more information on element globs. .IP "cell(row,col,[row2,col2],[...])" 4 .IX Item "cell(row,col,[row2,col2],[...])" Access an individual cell or collection of cells by their coordinates. .IP "row(row,[row2,...])" 4 .IX Item "row(row,[row2,...])" Access the contents of a row or collection of rows by row coordinate. .IP "col(col,[col2,...])" 4 .IX Item "col(col,[col2,...])" Access the contents of a column or collection of columns by column coordinate. .IP "box(row_a1,col_a1,row_a2,col_a2,[row_b1,col_b1,row_b2,col_b2],[...])" 4 .IX Item "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. .IP "\fBtable()\fR" 4 .IX Item "table()" Access all cells in the table. This is different from manipulating the table object itself, which is reserved for such things as \s-1CELLSPACING\s0 and other attributes specific to the <\s-1TABLE\s0> tag. However, since \fBtable()\fR returns a glob of cells, if the attribute is more appropriate for the top level <\s-1TABLE\s0> tag, it will be placed there rather than in each <\s-1TR\s0> tag or every <\s-1TD\s0> tag. .PP \&\s-1ELEMENT/GLOB METHODS\s0 .PP 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 \&\fBHTML::ElementSuper\fR\|(3) for details on these methods. .PP Briefly, here are some of the more useful methods provided by HTML::ElementSuper: .IP "\fBattr()\fR" 4 .IX Item "attr()" .PD 0 .IP "\fBpush_content()\fR" 4 .IX Item "push_content()" .IP "\fBreplace_content()\fR" 4 .IX Item "replace_content()" .IP "\fBwrap_content()\fR" 4 .IX Item "wrap_content()" .IP "clone([element])" 4 .IX Item "clone([element])" .IP "mask([mode])" 4 .IX Item "mask([mode])" .PD .PP \&\s-1TABLE SPECIFIC EXTENSIONS\s0 .IP "blank_fill([mode])" 4 .IX Item "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 \s-1BGCOLOR\s0 of that cell. When enabled, empty cells are provided with an ' ', or invisible content, which will trigger the rendering of the \s-1BGCOLOR\s0 for that cell. .SH "NOTES ON GLOBS" .IX Header "NOTES ON GLOBS" Globbing was a convenient way to treat arbitrary collections of table cells as if they were a single \s-1HTML\s0 element. Methods are generally passed blindly and sequentially to the elements they contain. .PP Most of the time, this is fairly intuitive, such as when you are setting the attributes of the cells. .PP Other times, it might be problematic, such as with \fBpush_content()\fR. 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 \&\fBpush_content()\fR 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 \s-1HTML\s0 element tree is probably not what you want anyway. .PP See \fBHTML::ElementGlob\fR\|(3) for more details on how globs work. .SH "REQUIRES" .IX Header "REQUIRES" HTML::ElementSuper, HTML::ElementGlob .SH "AUTHOR" .IX Header "AUTHOR" Matthew P. Sisk, <\fIsisk@mojotoad.com\fR> .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Thanks to William R. Ward for some conceptual nudging. .SH "COPYRIGHT" .IX Header "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. .SH "SEE ALSO" .IX Header "SEE ALSO" A useful page of HTML::ElementTable examples can be found at http://www.mojotoad.com/sisk/projects/HTML\-Element\-Extended/examples.html. .PP \&\fBHTML::ElementSuper\fR\|(3), \fBHTML::ElementGlob\fR\|(3), \fBHTML::Element\fR\|(3), \fBHTML::TableExtract\fR\|(3), \fBperl\fR\|(1).