1HTML::ElementTable(3) User Contributed Perl DocumentationHTML::ElementTable(3)
2
3
4
6 HTML::ElementTable - Perl extension for manipulating a table composed
7 of HTML::Element style components.
8
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
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
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 ' ', or invisible
153 content, which will trigger the rendering of the BGCOLOR for that
154 cell.
155
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
176 HTML::ElementSuper, HTML::ElementGlob
177
179 Matthew P. Sisk, <sisk@mojotoad.com>
180
182 Thanks to William R. Ward for some conceptual nudging.
183
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
190 A useful page of HTML::ElementTable examples can be found at
191 http://www.mojotoad.com/sisk/projects/HTML-Element-Extended/examples.html.
192
193 HTML::ElementSuper(3), HTML::ElementGlob(3), HTML::Element(3),
194 HTML::TableExtract(3), perl(1).
195
196
197
198perl v5.34.0 2021-07-22 HTML::ElementTable(3)