HTML::Table(3pm)

1HTML::Table(3)        User Contributed Perl Documentation       HTML::Table(3)
2
3
4

NAME

6       HTML::Table - produces HTML tables
7

SYNOPSIS

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

REQUIRES

47       Perl5.002
48

EXPORTS

50       Nothing
51

DESCRIPTION

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

METHODS

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 &nbsp, 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

CLASS VARIABLES

HISTORY

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

AUTHOR

621       Anthony Peacock, a.peacock@chime.ucl.ac.uk Stacy Lacy (Original author)
622

CONTRIBUTIONS

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 SkyttA~X, 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

COPYRIGHT

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