HTML::ElementTable(3pm)

1HTML::ElementTable(3) User Contributed Perl DocumentationHTML::ElementTable(3)
2
3
4

NAME

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

SYNOPSIS

10         use HTML::ElementTable;
11         # Create a table 0..10 x 0..12
12         $t = new HTML::ElementTable maxrow => 10, maxcol => 12;
13
14         # Populate cells with coordinates
15         $t->table->push_position;
16
17         # Manipulate <TABLE> tag
18         $t->attr('cellspacing',0);
19         $t->attr('border',1);
20         $t->attr('bgcolor','#DDBB00');
21
22         # Manipulate entire table - optimize on <TR> or pass to all <TD>
23         $t->table->attr('align','left');
24         $t->table->attr('valign','top');
25
26         # Manipulate rows (optimizes on <TR> if possible)
27         $t->row(0,2,4,6)->attr('bgcolor','#9999FF');
28
29         # Manipulate columns (all go to <TD> tags within column)
30         $t->col(0,4,8,12)->attr('bgcolor','#BBFFBB');
31
32         # Manipulate boxes (all go to <TD> elements
33         # unless it contains full rows, then <TR>)
34         $t->box(7,1 => 10,3)->attr('bgcolor','magenta');
35         $t->box(7,7 => 10,5)->attr('bgcolor','magenta');
36         $t->box(8,9 => 9,11)->attr('bgcolor','magenta');
37         $t->box(7,10 => 10,10)->attr('bgcolor','magenta');
38
39         # individual <TD> or <TH> attributes
40         $t->cell(8,6)->attr('bgcolor','#FFAAAA');
41         $t->cell(9,6)->attr('bgcolor','#FFAAAA');
42         $t->cell(7,9, 10,9, 7,11, 10,11)->attr('bgcolor','#FFAAAA');
43
44         # Take a look
45         print $t->as_HTML;
46

DESCRIPTION

48       HTML::ElementTable provides a highly enhanced HTML::ElementSuper
49       structure with methods designed to easily manipulate table elements by
50       using coordinates. Elements can be manipulated in bulk by individual
51       cells, arbitrary groupings of cells, boxes, columns, rows, or the
52       entire table.
53

PUBLIC METHODS

55       Table coordinates start at 0,0 in the upper left cell.
56
57       CONSTRUCTORS
58
59       new()
60       new(maxrow => row, maxcol => col)
61           Return a new HTML::ElementTable object. If the number of rows and
62           columns were provided, all elements required for the rows and
63           columns will be initialized as well. See extent().
64
65       new_from_tree($tree)
66           Takes an existing top-level HTML::Element representing a table and
67           converts the entire table structure into a cohesive
68           HTML::ElementTable construct. (this is potentially useful if you
69           want to use the power of this module for editing HTML tables in
70           situ within an HTML::Element tree).
71
72       TABLE CONFIGURATION
73
74       extent()
75       extent(maxrow, maxcolumn)
76           Set or return the extent of the current table. The maxrow and
77           maxcolumn parameters indicate the maximum row and column
78           coordinates you desire in the table. These are the coordinates of
79           the lower right cell in the table, starting from (0,0) at the upper
80           left.  Providing a smaller extent than the current one will shrink
81           the table with no ill effect, provided you do not mind losing the
82           information in the clipped cells.
83
84       maxrow()
85           Set or return the coordinate of the last row.
86
87       maxcol()
88           Set or return the coordinate of the last column.
89
90       ELEMENT ACCESS
91
92       Unless accessing a single element, most table element access is
93       accomplished through globs, which are collections of elements that
94       behave as if they were a single element object.
95
96       Whenever possible, globbed operations are optimized into the most
97       appropriate element. For example, if you set an attribute for a row
98       glob, the attribute will be set either on the <TR> element or the
99       collected <TD> elements, whichever is appropriate.
100
101       See HTML::ElementGlob(3) for more information on element globs.
102
103       cell(row,col,[row2,col2],[...])
104           Access an individual cell or collection of cells by their
105           coordinates.
106
107       row(row,[row2,...])
108           Access the contents of a row or collection of rows by row
109           coordinate.
110
111       col(col,[col2,...])
112           Access the contents of a column or collection of columns by column
113           coordinate.
114
115       box(row_a1,col_a1,row_a2,col_a2,[row_b1,col_b1,row_b2,col_b2],[...])
116           Access the contents of a span of cells, specified as a box
117           consisting of two sets of coordinates. Multiple boxes can be
118           specified.
119
120       table()
121           Access all cells in the table. This is different from manipulating
122           the table object itself, which is reserved for such things as
123           CELLSPACING and other attributes specific to the <TABLE> tag.
124           However, since table() returns a glob of cells, if the attribute is
125           more appropriate for the top level <TABLE> tag, it will be placed
126           there rather than in each <TR> tag or every <TD> tag.
127
128       ELEMENT/GLOB METHODS
129
130       The interfaces to a single table element or a glob of elements are
131       identical. All methods available from the HTML::ElementSuper class are
132       also available to a table element or glob of elements. See
133       HTML::ElementSuper(3) for details on these methods.
134
135       Briefly, here are some of the more useful methods provided by
136       HTML::ElementSuper:
137
138       attr()
139       push_content()
140       replace_content()
141       wrap_content()
142       clone([element])
143       mask([mode])
144
145       TABLE SPECIFIC EXTENSIONS
146
147       blank_fill([mode])
148           Set or return the current fill mode for blank cells. The default is
149           0 for HTML::Element::Table elements. When most browsers render
150           tables, if they are empty you will get a box the color of your
151           browser background color rather than the BGCOLOR of that cell. When
152           enabled, empty cells are provided with an '&nbsp;', or invisible
153           content, which will trigger the rendering of the BGCOLOR for that
154           cell.
155

NOTES ON GLOBS

157       Globbing was a convenient way to treat arbitrary collections of table
158       cells as if they were a single HTML element. Methods are generally
159       passed blindly and sequentially to the elements they contain.
160
161       Most of the time, this is fairly intuitive, such as when you are
162       setting the attributes of the cells.
163
164       Other times, it might be problematic, such as with push_content(). Do
165       you push the same object to all of the cells? HTML::Element based
166       classes only support one parent, so this breaks if you try to push the
167       same element into multiple parental hopefuls. In the specific case of
168       push_content() on globs, the elements that eventually get pushed are
169       clones of the originally provided content. It works, but it is not
170       necessarily what you expect. An incestuous HTML element tree is
171       probably not what you want anyway.
172
173       See HTML::ElementGlob(3) for more details on how globs work.
174

REQUIRES

176       HTML::ElementSuper, HTML::ElementGlob
177

AUTHOR

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

ACKNOWLEDGEMENTS

182       Thanks to William R. Ward for some conceptual nudging.
183

COPYRIGHT

185       Copyright (c) 1998-2010 Matthew P. Sisk. All rights reserved. All
186       wrongs revenged. This program is free software; you can redistribute it
187       and/or modify it under the same terms as Perl itself.
188