HTML::Table(3pm)

1Table(3)              User Contributed Perl Documentation             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 ta‐
61       ble if passed more cell values than will fit in the current table grid.
62
63       Methods are provided for nearly all valid table, row, and cell tags
64       specified for HTML 3.0.
65
66       A Japanese translation of the documentation is available at:
67
68               http://member.nifty.ne.jp/hippo2000/perltips/html/table.htm
69

METHODS

71         [] indicate optional parameters. default value will
72            be used if no value is specified
73
74         row_num indicates that a row number is required.
75               Rows are numbered from 1.  To refer to the last row use the value -1.
76
77         col_num indicates that a col number is required.
78               Cols are numbered from 1.  To refer to the last col use the value -1.
79
80       Creation
81
82       new HTML::Table([num_rows, num_cols])
83           Creates a new HTML table object.  If rows and columns are speci‐
84           fied, the table will be initialized to that size.  Row and Column
85           numbers start at 1,1.  0,0 is considered an empty table.
86
87       new HTML::Table([-rows=>num_rows, -cols=>num_cols, -border=>bor‐
88       der_width, -align=>table_alignment, -style=>table_style, -class=>ta‐
89       ble_class, -evenrowclass=>'even', -oddrowclass=>'odd',
90       -bgcolor=>back_colour, -width=>table_width, -spacing=>cell_spacing,
91       -padding=>cell_padding])
92           Creates a new HTML table object.  If rows and columns are speci‐
93           fied, the table will be initialized to that size.  Row and Column
94           numbers start at 1,1.  0,0 is considered an empty table.
95
96           If evenrowclass or oddrowclass is specified, these classes will be
97           applied to even and odd rows, respectively, unless those rows have
98           a specific class applied to it.
99
100       Table Level Methods
101
102       setBorder([pixels])
103           Sets the table Border Width
104
105       setWidth([pixels⎪percentofscreen])
106           Sets the table width
107
108                   $table->setWidth(500);
109             or
110                   $table->setWidth('100%');
111
112       setCellSpacing([pixels])
113       setCellPadding([pixels])
114       setCaption("CaptionText" [, top⎪bottom])
115       setBGColor([colorname⎪colortriplet])
116       autoGrow([1⎪true⎪on⎪anything⎪0⎪false⎪off⎪no⎪disable])
117           Switches on (default) or off automatic growing of the table if row
118           or column values passed to setCell exceed current table size.
119
120       setAlign ( [ left , center , right ] )
121       setRules ( [ rows , cols , all, both , groups  ] )
122       setStyle ( 'css style' )
123           Sets the table style attribute.
124
125       setClass ( 'css class' )
126           Sets the table class attribute.
127
128       setEvenRowClass ( 'css class' )
129           Sets the class attribute of even rows in the table.
130
131       setOddRowClass ( 'css class' )
132           Sets the class attribute of odd rows in the table.
133
134       setAttr ( 'user attribute' )
135           Sets a user defined attribute for the table.  Useful for when
136           HTML::Table hasn't implemented a particular attribute yet
137
138       sort ( [sort_col_num, sort_type, sort_order, num_rows_to_skip] )
139                   or
140             sort( -sort_col => sort_col_num,
141                   -sort_type => sort_type,
142                   -sort_order => sort_order,
143                   -skip_rows => num_rows_to_skip,
144                   -strip_html => strip_html,
145                   -strip_non_numeric => strip_non_numeric,
146                   -presort_func => \&filter_func )
147
148               sort_type in { ALPHA ⎪ NUMERIC },
149               sort_order in { ASC ⎪ DESC },
150               strip_html in { 0 ⎪ 1 }, defaults to 1,
151               strip_non_numeric in { 0 ⎪ 1 }, defaults to 1
152
153             Sort all rows on a given column (optionally skipping table header rows
154             by specifiying num_rows_to_skip).
155
156             By default sorting ignores HTML Tags and &nbsp, setting the strip_html parameter to 0
157             disables this behaviour.
158
159             By default numeric Sorting ignores non numeric chararacters, setting the strip_non_numeric
160             parameter to 0 disables this behaviour.
161
162             You can provide your own pre-sort function, useful for pre-processing the cell contents
163             before sorting for example dates.
164
165       getTableRows
166           Returns the number of rows in the table.
167
168       getTableCols
169           Returns the number of columns in the table.
170
171       getStyle
172           Returns the table's style attribute.
173
174       Cell Level Methods
175
176       setCell(row_num, col_num, "content")
177           Sets the content of a table cell.  This could be any string, even
178           another table object via the getTable method.  If the row and/or
179           column numbers are outside the existing table boundaries extra rows
180           and/or columns are created automatically.
181
182       setCellAlign(row_num, col_num, [center⎪right⎪left])
183           Sets the horizontal alignment for the cell.
184
185       setCellVAlign(row_num, col_num, [center⎪top⎪bottom⎪middle⎪baseline])
186           Sets the vertical alignment for the cell.
187
188       setCellWidth(row_num, col_num, [pixels⎪percentoftable])
189           Sets the width of the cell.
190
191       setCellHeight(row_num, col_num, [pixels])
192           Sets the height of the cell.
193
194       setCellHead(row_num, col_num)
195           Sets cell to be of type head (Ie <th></th>)
196
197       setCellNoWrap(row_num, col_num, [0⎪1])
198           Sets the NoWrap attribute of the cell.
199
200       setCellBGColor(row_num, col_num, [colorname⎪colortriplet])
201           Sets the background colour for the cell
202
203       setCellRowSpan(row_num, col_num, num_cells)
204           Causes the cell to overlap a number of cells below it.  If the
205           overlap number is greater than number of cells below the cell, a
206           false value will be returned.
207
208       setCellColSpan(row_num, col_num, num_cells)
209           Causes the cell to overlap a number of cells to the right.  If the
210           overlap number is greater than number of cells to the right of the
211           cell, a false value will be returned.
212
213       setCellSpan(row_num, col_num, num_rows, num_cols)
214           Joins the block of cells with the starting cell specified.  The
215           joined area will be num_cols wide and num_rows deep.
216
217       setCellFormat(row_num, col_num, start_string, end_string)
218           Start_string should be a string of valid HTML, which is output
219           before the cell contents, end_string is valid HTML that is output
220           after the cell contents.  This enables formatting to be applied to
221           the cell contents.
222
223                   $table->setCellFormat(1, 2, '<b>', '</b>');
224
225       setCellStyle (row_num, col_num, 'css style')
226           Sets the cell style attribute.
227
228       setCellClass (row_num, col_num, 'css class')
229           Sets the cell class attribute.
230
231       setCellAttr (row_num, col_num, 'user attribute')
232           Sets a user defined attribute for the cell.  Useful for when
233           HTML::Table hasn't implemented a particular attribute yet
234
235       setLastCell*
236           All of the setCell methods have a corresponding setLastCell method
237           which does not accept the row_num and col_num parameters, but auto‐
238           matically applies to the last row and last col of the table.
239
240       getCell(row_num, col_num)
241           Returns the contents of the specified cell as a string.
242
243       getCellStyle(row_num, col_num)
244           Returns cell's style attribute.
245
246       Column Level Methods
247
248       addCol("cell 1 content" [, "cell 2 content",  ...])
249           Adds a column to the right end of the table.  Assumes if you pass
250           more values than there are rows that you want to increase the num‐
251           ber of rows.
252
253       setColAlign(col_num, [center⎪right⎪left])
254           Applies setCellAlign over the entire column.
255
256       setColVAlign(col_num, [center⎪top⎪bottom⎪middle⎪baseline])
257           Applies setCellVAlign over the entire column.
258
259       setColWidth(col_num, [pixels⎪percentoftable])
260           Applies setCellWidth over the entire column.
261
262       setColHeight(col_num, [pixels])
263           Applies setCellHeight over the entire column.
264
265       setColHead(col_num)
266           Applies setCellHead over the entire column.
267
268       setColNoWrap(col_num, [0⎪1])
269           Applies setCellNoWrap over the entire column.
270
271       setColBGColor(row_num, [colorname⎪colortriplet])
272           Applies setCellBGColor over the entire column.
273
274       setColFormat(col_num, start_string, end_sting)
275           Applies setCellFormat over the entire column.
276
277       setColStyle (col_num, 'css style')
278           Applies setCellStyle over the entire column.
279
280       setColClass (col_num, 'css class')
281           Applies setCellClass over the entire column.
282
283       setColAttr (col_num, 'user attribute')
284           Applies setCellAttr over the entire column.
285
286       setLastCol*
287           All of the setCol methods have a corresponding setLastCol method
288           which does not accept the col_num parameter, but automatically
289           applies to the last col of the table.
290
291       getColStyle(col_num)
292           Returns column's style attribute.  Only really useful after setting
293           a column's style via setColStyle().
294
295       Row Level Methods
296
297       addRow("cell 1 content" [, "cell 2 content",  ...])
298           Adds a row to the bottom of the table.  Assumes if you pass more
299           values than there are columns that you want to increase the number
300           of columns.
301
302       setRowAlign(row_num, [center⎪right⎪left])
303           Applies setCellAlign over the entire row.
304
305       setRowVAlign(row_num, [center⎪top⎪bottom⎪middle⎪baseline])
306           Applies setCellVAlign over the entire row.
307
308       setRowWidth(row_num, [pixels⎪percentoftable])
309           Applies setCellWidth over the entire row.
310
311       setRowHeight(row_num, [pixels])
312           Applies setCellHeight over the entire row.
313
314       setRowHead(row_num)
315           Applies setCellHead over the entire row.
316
317       setRowNoWrap(col_num, [0⎪1])
318           Applies setCellNoWrap over the entire row.
319
320       setRowBGColor(row_num, [colorname⎪colortriplet])
321           Applies setCellBGColor over the entire row.
322
323       setRowFormat(row_num, start_string, end_string)
324           Applies setCellFormat over the entire row.
325
326       setRowStyle (row_num, 'css style')
327           Applies setCellStyle over the entire row.
328
329       setRowClass (row_num, 'css class')
330           Applies setCellClass over the entire row.
331
332       setRowAttr (row_num, 'user attribute')
333           Applies setCellAttr over the entire row.
334
335       setLastRow*
336           All of the setRow methods have a corresponding setLastRow method
337           which does not accept the row_num parameter, but automatically
338           applies to the last row of the table.
339
340       getRowStyle(row_num)
341           Returns row's style attribute.
342
343       Output Methods
344
345       getTable
346           Returns a string containing the HTML representation of the table.
347
348           The same effect can also be achieved by using the object reference
349           in a string scalar context.
350
351           For example...
352
353                   This code snippet:
354
355                           $table = new HTML::Table(2, 2);
356                           print '<p>Start</p>';
357                           print $table->getTable;
358                           print '<p>End</p>';
359
360                   would produce the same output as:
361
362                           $table = new HTML::Table(2, 2);
363                           print "<p>Start</p>$table<p>End</p>";
364
365       print
366           Prints HTML representation of the table to STDOUT
367

CLASS VARIABLES

HISTORY

370       This module was originally created in 1997 by Stacy Lacy and whose last
371       version was uploaded to CPAN in 1998.  The module was adopted in July
372       2000 by Anthony Peacock in order to distribute a revised version.  This
373       adoption took place without the explicit consent of Stacy Lacy as it
374       proved impossible to contact them at the time.  Explicit consent for
375       the adoption has since been received.
376

AUTHOR

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

CONTRIBUTIONS

381       Douglas Riordan <doug.riordan@gmail.com> For get methods for Style
382       attributes.
383
384       Jay Flaherty, fty@mediapulse.com For ROW, COL & CELL HEAD methods. Mod‐
385       ified the new method to allow hash of values.
386
387       John Stumbles, john@uk.stumbles.org For autogrow behaviour of setCell,
388       and allowing alignment specifications to be case insensitive
389
390       Arno Teunisse, Arno.Teunisse@Simac.nl For the methods adding rules,
391       styles and table alignment attributes.
392
393       Ville Skyttä, ville.skytta@iki.fi For general fixes
394
395       Paul Vernaza, vernaza@stwing.upenn.edu For the setLast... methods
396
397       David Link, dvlink@yahoo.com For the sort method
398
399       Tommi Maekitalo, t.maekitalo@epgmbh.de For adding the 'head' parameter
400       to the new method and for adding the initialisation from an array ref
401       to the new method.
402
403       Chris Weyl, cweyl@alumni.drew.edu For adding the even/odd row class
404       support.
405

COPYRIGHT

407       Copyright (c) 2000-2007 Anthony Peacock, CHIME.  Copyright (c) 1997
408       Stacy Lacy
409
410       This library is free software; you can redistribute it and/or modify it
411       under the same terms as Perl itself.
412