1HTML::Table(3) User Contributed Perl Documentation HTML::Table(3)
2
3
4
6 HTML::Table - produces HTML tables
7
9 use HTML::Table;
10
11 $table1 = new HTML::Table($rows, $cols);
12 or
13 $table1 = new HTML::Table(-rows=>26,
14 -cols=>2,
15 -align=>'center',
16 -rules=>'rows',
17 -border=>0,
18 -bgcolor=>'blue',
19 -width=>'50%',
20 -spacing=>0,
21 -padding=>0,
22 -style=>'color: blue',
23 -class=>'myclass',
24 -evenrowclass=>'even',
25 -oddrowclass=>'odd',
26 -head=> ['head1', 'head2'],
27 -data=> [ ['1:1', '1:2'], ['2:1', '2:2'] ] );
28 or
29 $table1 = new HTML::Table( [ ['1:1', '1:2'], ['2:1', '2:2'] ] );
30
31 $table1->setCell($cellrow, $cellcol, 'This is Cell 1');
32 $table1->setCellBGColor('blue');
33 $table1->setCellColSpan(1, 1, 2);
34 $table1->setRowHead(1);
35 $table1->setColHead(1);
36
37 $table1->print;
38
39 $table2 = new HTML::Table;
40 $table2->addRow(@cell_values);
41 $table2->addCol(@cell_values2);
42
43 $table1->setCell(1,1, "$table2->getTable");
44 $table1->print;
45
47 Perl5.002
48
50 Nothing
51
53 HTML::Table is used to generate HTML tables for CGI scripts. By using
54 the methods provided fairly complex tables can be created, manipulated,
55 then printed from Perl scripts. The module also greatly simplifies
56 creating tables within tables from Perl. It is possible to create an
57 entire table using the methods provided and never use an HTML tag.
58
59 HTML::Table also allows for creating dynamically sized tables via its
60 addRow and addCol methods. These methods automatically resize the
61 table if passed more cell values than will fit in the current table
62 grid.
63
64 Methods are provided for nearly all valid table, row, and cell tags
65 specified for HTML 3.0.
66
67 A Japanese translation of the documentation is available at:
68
69 http://member.nifty.ne.jp/hippo2000/perltips/html/table.htm
70
72 [] indicate optional parameters. default value will
73 be used if no value is specified
74
75 row_num indicates that a row number is required.
76 Rows are numbered from 1. To refer to the last row use the value -1.
77
78 col_num indicates that a col number is required.
79 Cols are numbered from 1. To refer to the last col use the value -1.
80
81 Sections
82 From version 2.07 onwards HTML::Table supports table sections
83 (THEAD, TFOOT & TBODY).
84
85 Each section can have its own attributes (id, class, etc) set, and
86 will contain 1 or more rows. Section numbering starts at 0, only
87 tbody is allowed to have more than one section.
88
89 Methods for manipultaing sections and their data are available and
90 have the general form:
91
92 setSectionCell ( section, section_num, row_num, col_num, data );
93
94 For example, the following adds a row to the first body section:
95
96 addSectionRow ( 'tbody', 0, "Cell 1", "Cell 2", "Cell 3" );
97
98 For backwards compatibility, methods with Section in their name
99 will default to manipulating the first body section.
100
101 For example, the following sets the class for the first row in the
102 first body section:
103
104 setRowClass ( 1, 'row_class' );
105
106 Which is semantically equivalent to:
107
108 setSectionRowClass ( 'tbody', 0, 1, 'row_class' );
109
110 Creation
111 new HTML::Table([num_rows, num_cols])
112 Creates a new HTML table object. If rows and columns are
113 specified, the table will be initialized to that size. Row and
114 Column numbers start at 1,1. 0,0 is considered an empty table.
115
116 new HTML::Table([-rows=>num_rows, -cols=>num_cols,
117 -border=>border_width, -align=>table_alignment, -style=>table_style,
118 -class=>table_class, -evenrowclass=>'even', -oddrowclass=>'odd',
119 -bgcolor=>back_colour, -width=>table_width, -spacing=>cell_spacing,
120 -padding=>cell_padding])
121 Creates a new HTML table object. If rows and columns are
122 specified, the table will be initialized to that size. Row and
123 Column numbers start at 1,1. 0,0 is considered an empty table.
124
125 If evenrowclass or oddrowclass is specified, these classes will be
126 applied to even and odd rows, respectively, unless those rows have
127 a specific class applied to it.
128
129 Table Level Methods
130 setBorder([pixels])
131 Sets the table Border Width
132
133 setWidth([pixels|percentofscreen])
134 Sets the table width
135
136 $table->setWidth(500);
137 or
138 $table->setWidth('100%');
139
140 setCellSpacing([pixels])
141 setCellPadding([pixels])
142 setCaption("CaptionText" [, top|bottom])
143 setBGColor([colorname|colortriplet])
144 autoGrow([1|true|on|anything|0|false|off|no|disable])
145 Switches on (default) or off automatic growing of the table if row
146 or column values passed to setCell exceed current table size.
147
148 setAlign ( [ left , center , right ] )
149 setRules ( [ rows , cols , all, both , groups ] )
150 setStyle ( 'css style' )
151 Sets the table style attribute.
152
153 setClass ( 'css class' )
154 Sets the table class attribute.
155
156 setEvenRowClass ( 'css class' )
157 Sets the class attribute of even rows in the table.
158
159 setOddRowClass ( 'css class' )
160 Sets the class attribute of odd rows in the table.
161
162 setAttr ( 'user attribute' )
163 Sets a user defined attribute for the table. Useful for when
164 HTML::Table hasn't implemented a particular attribute yet
165
166 sort ( [sort_col_num, sort_type, sort_order, num_rows_to_skip] )
167 or
168 sort( -sort_col => sort_col_num,
169 -sort_type => sort_type,
170 -sort_order => sort_order,
171 -skip_rows => num_rows_to_skip,
172 -strip_html => strip_html,
173 -strip_non_numeric => strip_non_numeric,
174 -presort_func => \&filter_func )
175
176 sort_type in { ALPHA | NUMERIC },
177 sort_order in { ASC | DESC },
178 strip_html in { 0 | 1 }, defaults to 1,
179 strip_non_numeric in { 0 | 1 }, defaults to 1
180
181 Sort all rows on a given column (optionally skipping table header rows
182 by specifiying num_rows_to_skip).
183
184 By default sorting ignores HTML Tags and  , setting the strip_html parameter to 0
185 disables this behaviour.
186
187 By default numeric Sorting ignores non numeric chararacters, setting the strip_non_numeric
188 parameter to 0 disables this behaviour.
189
190 You can provide your own pre-sort function, useful for pre-processing the cell contents
191 before sorting for example dates.
192
193 getTableRows
194 Returns the number of rows in the table.
195
196 getTableCols
197 Returns the number of columns in the table.
198
199 getStyle
200 Returns the table's style attribute.
201
202 Section Level Methods
203 setSectionId ( [tbody|thead|tfoot], section_num, 'id' )
204 Sets the id attribute for the section.
205
206 setSectionClass ( [tbody|thead|tfoot], section_num, 'class' )
207 Sets the class attribute for the section.
208
209 setSectionStyle ( [tbody|thead|tfoot], section_num, 'style' )
210 Sets the style attribute for the section.
211
212 setSectionAlign ( [tbody|thead|tfoot], section_num, [center|right|left]
213 )
214 Sets the horizontal alignment for the section.
215
216 setSectionValign ( [tbody|thead|tfoot], section_num,
217 [center|top|bottom|middle|baseline] )
218 Sets the vertical alignment for the section.
219
220 setSectionAttr ( [tbody|thead|tfoot], section_num, 'user attribute' )
221 Sets a user defined attribute for the cell. Useful for when
222 HTML::Table hasn't implemented a particular attribute yet
223
224 Cell Level Methods
225 setCell(row_num, col_num, "content")
226 Sets the content of a table cell. This could be any string, even
227 another table object via the getTable method. If the row and/or
228 column numbers are outside the existing table boundaries extra rows
229 and/or columns are created automatically.
230
231 setSectionCell([tbody|thead|tfoot], section_num, row_num, col_num,
232 "content")
233 Same as setCell, but able to specify which section to act on.
234
235 setCellAlign(row_num, col_num, [center|right|left])
236 Sets the horizontal alignment for the cell.
237
238 setSectionCellAlign([tbody|thead|tfoot], section_num, row_num, col_num,
239 [center|right|left])
240 Same as setCellAlign, but able to specify which section to act on.
241
242 setCellVAlign(row_num, col_num, [center|top|bottom|middle|baseline])
243 Sets the vertical alignment for the cell.
244
245 setSectionCellVAlign([tbody|thead|tfoot], section_num, row_num,
246 col_num, [center|top|bottom|middle|baseline])
247 Same as setCellVAlign, but able to specify which section to act on.
248
249 setCellWidth(row_num, col_num, [pixels|percentoftable])
250 Sets the width of the cell.
251
252 setSectionCellWidth([tbody|thead|tfoot], section_num, row_num, col_num,
253 [pixels|percentoftable])
254 Same as setCellWidth, but able to specify which section to act on.
255
256 setCellHeight(row_num, col_num, [pixels])
257 Sets the height of the cell.
258
259 setSectionCellHeight([tbody|thead|tfoot], section_num, row_num,
260 col_num, [pixels])
261 Same as setCellHeight, but able to specify which section to act on.
262
263 setCellHead(row_num, col_num, [0|1])
264 Sets cell to be of type head (Ie <th></th>)
265
266 setSectionCellHead([tbody|thead|tfoot], section_num, row_num, col_num,
267 [0|1])
268 Same as setCellHead, but able to specify which section to act on.
269
270 setCellNoWrap(row_num, col_num, [0|1])
271 Sets the NoWrap attribute of the cell.
272
273 setSectionCellNoWrap([tbody|thead|tfoot], section_num, row_num,
274 col_num, [0|1])
275 Same as setCellNoWrap, but able to specify which section to act on.
276
277 setCellBGColor(row_num, col_num, [colorname|colortriplet])
278 Sets the background colour for the cell.
279
280 setSectionCellBGColor([tbody|thead|tfoot], section_num, row_num,
281 col_num, [colorname|colortriplet])
282 Same as setCellBGColor, but able to specify which section to act
283 on.
284
285 setCellRowSpan(row_num, col_num, num_cells)
286 Causes the cell to overlap a number of cells below it. If the
287 overlap number is greater than number of cells below the cell, a
288 false value will be returned.
289
290 setSectionCellRowSpan([tbody|thead|tfoot], section_num, row_num,
291 col_num, num_cells)
292 Same as setCellRowSpan, but able to specify which section to act
293 on.
294
295 setCellColSpan(row_num, col_num, num_cells)
296 Causes the cell to overlap a number of cells to the right. If the
297 overlap number is greater than number of cells to the right of the
298 cell, a false value will be returned.
299
300 setSectionCellColSpan([tbody|thead|tfoot], section_num, row_num,
301 col_num, num_cells)
302 Same as setCellColSpan, but able to specify which section to act
303 on.
304
305 setCellSpan(row_num, col_num, num_rows, num_cols)
306 Joins the block of cells with the starting cell specified. The
307 joined area will be num_cols wide and num_rows deep.
308
309 setSectionCellSpan([tbody|thead|tfoot], section_num, row_num, col_num,
310 num_rows, num_cols)
311 Same as setCellSpan, but able to specify which section to act on.
312
313 setCellFormat(row_num, col_num, start_string, end_string)
314 Start_string should be a string of valid HTML, which is output
315 before the cell contents, end_string is valid HTML that is output
316 after the cell contents. This enables formatting to be applied to
317 the cell contents.
318
319 $table->setCellFormat(1, 2, '<b>', '</b>');
320
321 setSectionCellFormat([tbody|thead|tfoot], section_num, row_num,
322 col_num, start_string, end_string)
323 Same as setCellFormat, but able to specify which section to act on.
324
325 setCellStyle (row_num, col_num, 'css style')
326 Sets the cell style attribute.
327
328 setSectionCellStyle([tbody|thead|tfoot], section_num, row_num, col_num,
329 'css style')
330 Same as setCellStyle, but able to specify which section to act on.
331
332 setCellClass (row_num, col_num, 'css class')
333 Sets the cell class attribute.
334
335 setSectionCellClass([tbody|thead|tfoot], section_num, row_num, col_num,
336 'css class')
337 Same as setCellClass, but able to specify which section to act on.
338
339 setCellAttr (row_num, col_num, 'user attribute')
340 Sets a user defined attribute for the cell. Useful for when
341 HTML::Table hasn't implemented a particular attribute yet
342
343 setSectionCellAttr([tbody|thead|tfoot], section_num, row_num, col_num,
344 'css class')
345 Same as setCellAttr, but able to specify which section to act on.
346
347 setLastCell*
348 All of the setCell methods have a corresponding setLastCell method
349 which does not accept the row_num and col_num parameters, but
350 automatically applies to the last row and last col of the table.
351
352 NB. Only works on the setCell* methods, not on the setSectionCell*
353 methods.
354
355 getCell(row_num, col_num)
356 Returns the contents of the specified cell as a string.
357
358 getSectionCell([tbody|thead|tfoot], section_num, row_num, col_num)
359 Same as getCell, but able to specify which section to act on.
360
361 getCellStyle(row_num, col_num)
362 Returns cell's style attribute.
363
364 getSectionCellStyle([tbody|thead|tfoot], section_num, row_num, col_num)
365 Same as getCellStyle, but able to specify which section to act on.
366
367 Column Level Methods
368 addCol("cell 1 content" [, "cell 2 content", ...])
369 Adds a column to the right end of the table. Assumes if you pass
370 more values than there are rows that you want to increase the
371 number of rows.
372
373 addSectionCol([tbody|thead|tfoot], section_num, "cell 1 content" [,
374 "cell 2 content", ...])
375 Same as addCol, but able to specify which section to act on.
376
377 setColAlign(col_num, [center|right|left])
378 Applies setCellAlign over the entire column.
379
380 setSectionColAlign([tbody|thead|tfoot], section_num, col_num,
381 [center|right|left])
382 Same as setColAlign, but able to specify which section to act on.
383
384 setColVAlign(col_num, [center|top|bottom|middle|baseline])
385 Applies setCellVAlign over the entire column.
386
387 setSectionColVAlign([tbody|thead|tfoot], section_num, col_num,
388 [center|top|bottom|middle|baseline])
389 Same as setColVAlign, but able to specify which section to act on.
390
391 setColWidth(col_num, [pixels|percentoftable])
392 Applies setCellWidth over the entire column.
393
394 setSectionColWidth([tbody|thead|tfoot], section_num, col_num,
395 [pixels|percentoftable])
396 Same as setColWidth, but able to specify which section to act on.
397
398 setColHeight(col_num, [pixels])
399 Applies setCellHeight over the entire column.
400
401 setSectionColHeight([tbody|thead|tfoot], section_num, col_num,
402 [pixels])
403 Same as setColHeight, but able to specify which section to act on.
404
405 setColHead(col_num, [0|1])
406 Applies setCellHead over the entire column.
407
408 setSectionColHead([tbody|thead|tfoot], section_num, col_num, [0|1])
409 Same as setColHead, but able to specify which section to act on.
410
411 setColNoWrap(col_num, [0|1])
412 Applies setCellNoWrap over the entire column.
413
414 setSectionColNoWrap([tbody|thead|tfoot], section_num, col_num, [0|1])
415 Same as setColNoWrap, but able to specify which section to act on.
416
417 setColBGColor(row_num, [colorname|colortriplet])
418 Applies setCellBGColor over the entire column.
419
420 setSectionColBGColor([tbody|thead|tfoot], section_num, col_num,
421 [colorname|colortriplet])
422 Same as setColBGColor, but able to specify which section to act on.
423
424 setColFormat(col_num, start_string, end_sting)
425 Applies setCellFormat over the entire column.
426
427 setSectionColFormat([tbody|thead|tfoot], section_num, col_num,
428 start_string, end_sting)
429 Same as setColFormat, but able to specify which section to act on.
430
431 setColStyle (col_num, 'css style')
432 Applies setCellStyle over the entire column.
433
434 setSectionColStyle([tbody|thead|tfoot], section_num, col_num, 'css
435 style')
436 Same as setColStyle, but able to specify which section to act on.
437
438 setColClass (col_num, 'css class')
439 Applies setCellClass over the entire column.
440
441 setSectionColClass([tbody|thead|tfoot], section_num, col_num, 'css
442 class')
443 Same as setColClass, but able to specify which section to act on.
444
445 setColAttr (col_num, 'user attribute')
446 Applies setCellAttr over the entire column.
447
448 setSectionColAttr([tbody|thead|tfoot], section_num, col_num, 'user
449 attribute')
450 Same as setColAttr, but able to specify which section to act on.
451
452 setLastCol*
453 All of the setCol methods have a corresponding setLastCol method
454 which does not accept the col_num parameter, but automatically
455 applies to the last col of the table.
456
457 NB. Only works on the setCol* methods, not on the setSectionCol*
458 methods.
459
460 getColStyle(col_num)
461 Returns column's style attribute. Only really useful after setting
462 a column's style via setColStyle().
463
464 getSectionColStyle([tbody|thead|tfoot], section_num, col_num)
465 Same as getColStyle, but able to specify which section to act on.
466
467 Row Level Methods
468 addRow("cell 1 content" [, "cell 2 content", ...])
469 Adds a row to the bottom of the first body section of the table.
470
471 Adds a row to the bottom of the table. Assumes if you pass more
472 values than there are columns that you want to increase the number
473 of columns.
474
475 addSectionRow([tbody|thead|tfoot], section_num, "cell 1 content" [,
476 "cell 2 content", ...])
477 Same as addRow, but able to specify which section to act on.
478
479 delRow(row_num)
480 Deletes a row from the first body section of the table. If -1 is
481 passed as row_num, the last row in the section will be deleted.
482
483 delSectionRow([tbody|thead|tfoot], section_num, row_num)
484 Same as delRow, but able to specify which section to act on.
485
486 setRowAlign(row_num, [center|right|left])
487 Sets the Align attribute of the row.
488
489 setSectionRowAlign([tbody|thead|tfoot], section_num, row_num,
490 [center|right|left])
491 Same as setRowAlign, but able to specify which section to act on.
492
493 setRowVAlign(row_num, [center|top|bottom|middle|baseline])
494 Sets the VAlign attribute of the row.
495
496 setSectionRowVAlign([tbody|thead|tfoot], section_num, row_num,
497 [center|top|bottom|middle|baseline])
498 Same as setRowVAlign, but able to specify which section to act on.
499
500 setRowNoWrap(col_num, [0|1])
501 Sets the NoWrap attribute of the row.
502
503 setSectionRowNoWrap([tbody|thead|tfoot], section_num, row_num, [0|1])
504 Same as setRowNoWrap, but able to specify which section to act on.
505
506 setRowBGColor(row_num, [colorname|colortriplet])
507 Sets the BGColor attribute of the row.
508
509 setSectionRowBGColor([tbody|thead|tfoot], section_num, row_num,
510 [colorname|colortriplet])
511 Same as setRowBGColor, but able to specify which section to act on.
512
513 setRowStyle (row_num, 'css style')
514 Sets the Style attribute of the row.
515
516 setSectionRowStyle([tbody|thead|tfoot], section_num, row_num, 'css
517 style')
518 Same as setRowStyle, but able to specify which section to act on.
519
520 setRowClass (row_num, 'css class')
521 Sets the Class attribute of the row.
522
523 setSectionRowClass([tbody|thead|tfoot], section_num, row_num, 'css
524 class')
525 Same as setRowClass, but able to specify which section to act on.
526
527 setRowAttr (row_num, 'user attribute')
528 Sets the Attr attribute of the row.
529
530 setSectionRowAttr([tbody|thead|tfoot], section_num, row_num, 'user
531 attribute')
532 Same as setRowAttr, but able to specify which section to act on.
533
534 setRCellsWidth(row_num, [pixels|percentoftable])
535 setRowWidth(row_num, [pixels|percentoftable]) ** Deprecated **
536 Applies setCellWidth over the entire row.
537
538 setSectionRCellsWidth([tbody|thead|tfoot], section_num, row_num,
539 [pixels|percentoftable])
540 setSectionRowWidth([tbody|thead|tfoot], section_num, row_num,
541 [pixels|percentoftable]) ** Deprecated **
542 Same as setRowWidth, but able to specify which section to act on.
543
544 setRCellsHeight(row_num, [pixels])
545 setRowHeight(row_num, [pixels]) ** Deprecated **
546 Applies setCellHeight over the entire row.
547
548 setSectionRCellsHeight([tbody|thead|tfoot], section_num, row_num,
549 [pixels])
550 setSectionRowHeight([tbody|thead|tfoot], section_num, row_num,
551 [pixels]) ** Deprecated **
552 Same as setRowHeight, but able to specify which section to act on.
553
554 setRCellsHead(row_num, [0|1])
555 setRowHead(row_num, [0|1]) ** Deprecated **
556 Applies setCellHead over the entire row.
557
558 setSectionRCellsHead([tbody|thead|tfoot], section_num, row_num, [0|1])
559 setSectionRowHead([tbody|thead|tfoot], section_num, row_num, [0|1]) **
560 Deprecated **
561 Same as setRowHead, but able to specify which section to act on.
562
563 setRCellsFormat(row_num, start_string, end_string)
564 setRowFormat(row_num, start_string, end_string) ** Deprecated **
565 Applies setCellFormat over the entire row.
566
567 setSectionRCellsFormat([tbody|thead|tfoot], section_num, row_num,
568 start_string, end_string)
569 setSectionRowFormat([tbody|thead|tfoot], section_num, row_num,
570 start_string, end_string) ** Deprecated **
571 Same as setRowFormat, but able to specify which section to act on.
572
573 setLastRow*
574 All of the setRow methods have a corresponding setLastRow method
575 which does not accept the row_num parameter, but automatically
576 applies to the last row of the table.
577
578 NB. Only works on the setRow* methods, not on the setSectionRow*
579 methods.
580
581 getRowStyle(row_num)
582 Returns row's style attribute.
583
584 getSectionRowStyle([tbody|thead|tfoot], section_num, row_num)
585 Same as getRowStyle, but able to specify which section to act on.
586
587 Output Methods
588 getTable
589 Returns a string containing the HTML representation of the table.
590
591 The same effect can also be achieved by using the object reference
592 in a string scalar context.
593
594 For example...
595
596 This code snippet:
597
598 $table = new HTML::Table(2, 2);
599 print '<p>Start</p>';
600 print $table->getTable;
601 print '<p>End</p>';
602
603 would produce the same output as:
604
605 $table = new HTML::Table(2, 2);
606 print "<p>Start</p>$table<p>End</p>";
607
608 print
609 Prints HTML representation of the table to STDOUT
610
613 This module was originally created in 1997 by Stacy Lacy and whose last
614 version was uploaded to CPAN in 1998. The module was adopted in July
615 2000 by Anthony Peacock in order to distribute a revised version. This
616 adoption took place without the explicit consent of Stacy Lacy as it
617 proved impossible to contact them at the time. Explicit consent for
618 the adoption has since been received.
619
621 Anthony Peacock, a.peacock@chime.ucl.ac.uk Stacy Lacy (Original author)
622
624 Douglas Riordan <doug.riordan@gmail.com> For get methods for Style
625 attributes.
626
627 Jay Flaherty, fty@mediapulse.com For ROW, COL & CELL HEAD methods.
628 Modified the new method to allow hash of values.
629
630 John Stumbles, john@uk.stumbles.org For autogrow behaviour of setCell,
631 and allowing alignment specifications to be case insensitive
632
633 Arno Teunisse, Arno.Teunisse@Simac.nl For the methods adding rules,
634 styles and table alignment attributes.
635
636 Ville Skyttä, ville.skytta@iki.fi For general fixes
637
638 Paul Vernaza, vernaza@stwing.upenn.edu For the setLast... methods
639
640 David Link, dvlink@yahoo.com For the sort method
641
642 Tommi Maekitalo, t.maekitalo@epgmbh.de For adding the 'head' parameter
643 to the new method and for adding the initialisation from an array ref
644 to the new method.
645
646 Chris Weyl, cweyl@alumni.drew.edu For adding the even/odd row class
647 support.
648
650 Copyright (c) 2000-2007 Anthony Peacock, CHIME. Copyright (c) 1997
651 Stacy Lacy
652
653 This library is free software; you can redistribute it and/or modify it
654 under the same terms as Perl itself.
655
657 perl(1), CGI(3)
658
660 Hey! The above document had some coding errors, which are explained
661 below:
662
663 Around line 788:
664 Non-ASCII character seen before =encoding in 'Skyttä,'. Assuming
665 UTF-8
666
667
668
669perl v5.36.0 2023-01-20 HTML::Table(3)