NAME

HTML::Table - produces HTML tables

SYNOPSIS

  use HTML::Table;

  $table1 = new HTML::Table($rows, $cols);
    or
  $table1 = new HTML::Table(-rows=>26,
                            -cols=>2,
                            -align=>'center',
                            -rules=>'rows',
                            -border=>0,
                            -bgcolor=>'blue',
                            -width=>'50%',
                            -spacing=>0,
                            -padding=>0,
                            -style=>'color: blue',
                            -class=>'myclass',
                            -evenrowclass=>'even',
                            -oddrowclass=>'odd',
                            -head=> ['head1', 'head2'],
                            -data=> [ ['1:1', '1:2'], ['2:1', '2:2'] ] );
   or
  $table1 = new HTML::Table( [ ['1:1', '1:2'], ['2:1', '2:2'] ] );

  $table1->setCell($cellrow, $cellcol, 'This is Cell 1');
  $table1->setCellBGColor('blue');
  $table1->setCellColSpan(1, 1, 2);
  $table1->setRowHead(1);
  $table1->setColHead(1);

  $table1->print;

  $table2 = new HTML::Table;
  $table2->addRow(@cell_values);
  $table2->addCol(@cell_values2);

  $table1->setCell(1,1, "$table2->getTable");
  $table1->print;

REQUIRES

Perl5.002

EXPORTS

Nothing

DESCRIPTION

HTML::Table is used to generate HTML tables for CGI scripts. By using the methods provided fairly complex tables can be created, manipulated, then printed from Perl scripts. The module also greatly simplifies creating tables within tables from Perl. It is possible to create an entire table using the methods provided and never use an HTML tag.

HTML::Table also allows for creating dynamically sized tables via its addRow and addCol methods. These methods automatically resize the table if passed more cell values than will fit in the current table grid.

Methods are provided for nearly all valid table, row, and cell tags specified for HTML 3.0.

A Japanese translation of the documentation is available at:

        http://member.nifty.ne.jp/hippo2000/perltips/html/table.htm

METHODS

  [] indicate optional parameters. default value will
     be used if no value is specified
     
  row_num indicates that a row number is required.  
        Rows are numbered from 1.  To refer to the last row use the value -1.

  col_num indicates that a col number is required.  
        Cols are numbered from 1.  To refer to the last col use the value -1.

Sections

From version 2.07 onwards HTML::Table supports table sections (THEAD, TFOOT & TBODY).

Each section can have its own attributes (id, class, etc) set, and will contain 1 or more rows. Section numbering starts at 0, only tbody is allowed to have more than one section.

Methods for manipultaing sections and their data are available and have the general form:

  setSectionCell ( section, section_num, row_num, col_num, data );
  
  For example, the following adds a row to the first body section:
  
  addSectionRow ( 'tbody', 0, "Cell 1", "Cell 2", "Cell 3" );

For backwards compatibility, methods with Section in their name will default to manipulating the first body section.

  For example, the following sets the class for the first row in the 
  first body section:
  
  setRowClass ( 1, 'row_class' );
  
  Which is semantically equivalent to:
  
  setSectionRowClass ( 'tbody', 0, 1, 'row_class' );

Creation

new HTML::Table([num_rows, num_cols]): Creates a new HTML table object. If rows and columns are specified, the table will be initialized to that size. Row and Column numbers start at 1,1. 0,0 is considered an empty table.
new HTML::Table([-rows=>num_rows, -cols=>num_cols, -border=>border_width, -align=>table_alignment, -style=>table_style, -class=>table_class, -evenrowclass=>'even', -oddrowclass=>'odd', -bgcolor=>back_colour, -width=>table_width, -spacing=>cell_spacing, -padding=>cell_padding]): Creates a new HTML table object. If rows and columns are specified, the table will be initialized to that size. Row and Column numbers start at 1,1. 0,0 is considered an empty table.
If evenrowclass or oddrowclass is specified, these classes will be applied to even and odd rows, respectively, unless those rows have a specific class applied to it.

Table Level Methods

setBorder([pixels])

Sets the table Border Width

setWidth([pixels|percentofscreen])

Sets the table width

        $table->setWidth(500);
  or
        $table->setWidth('100%');

setCellSpacing([pixels])

setCellPadding([pixels])

setCaption("CaptionText" [, top|bottom])

setBGColor([colorname|colortriplet])

autoGrow([1|true|on|anything|0|false|off|no|disable])

Switches on (default) or off automatic growing of the table if row or column values passed to setCell exceed current table size.

setAlign ( [ left , center , right ] )

setRules ( [ rows , cols , all, both , groups ] )

setStyle ( 'css style' )

Sets the table style attribute.

setClass ( 'css class' )

Sets the table class attribute.

setEvenRowClass ( 'css class' )

Sets the class attribute of even rows in the table.

setOddRowClass ( 'css class' )

Sets the class attribute of odd rows in the table.

setAttr ( 'user attribute' )

Sets a user defined attribute for the table. Useful for when HTML::Table hasn't implemented a particular attribute yet

sort ( [sort_col_num, sort_type, sort_order, num_rows_to_skip] )

        or 
  sort( -sort_col => sort_col_num, 
        -sort_type => sort_type,
        -sort_order => sort_order,
        -skip_rows => num_rows_to_skip,
        -strip_html => strip_html,
        -strip_non_numeric => strip_non_numeric,
        -presort_func => \&filter_func )

    sort_type in { ALPHA | NUMERIC }, 
    sort_order in { ASC | DESC },
    strip_html in { 0 | 1 }, defaults to 1,
    strip_non_numeric in { 0 | 1 }, defaults to 1

  Sort all rows on a given column (optionally skipping table header rows
  by specifiying num_rows_to_skip).

  By default sorting ignores HTML Tags and &nbsp, setting the strip_html parameter to 0 
  disables this behaviour.

  By default numeric Sorting ignores non numeric chararacters, setting the strip_non_numeric
  parameter to 0 disables this behaviour.

  You can provide your own pre-sort function, useful for pre-processing the cell contents 
  before sorting for example dates.

getTableRows

Returns the number of rows in the table.

getTableCols

Returns the number of columns in the table.

getStyle

Returns the table's style attribute.

Section Level Methods

setSectionId ( [tbody|thead|tfoot], section_num, 'id' ): Sets the id attribute for the section.
setSectionClass ( [tbody|thead|tfoot], section_num, 'class' ): Sets the class attribute for the section.
setSectionStyle ( [tbody|thead|tfoot], section_num, 'style' ): Sets the style attribute for the section.
setSectionAlign ( [tbody|thead|tfoot], section_num, [center|right|left] ): Sets the horizontal alignment for the section.
setSectionValign ( [tbody|thead|tfoot], section_num, [center|top|bottom|middle|baseline] ): Sets the vertical alignment for the section.
setSectionAttr ( [tbody|thead|tfoot], section_num, 'user attribute' ): Sets a user defined attribute for the cell. Useful for when HTML::Table hasn't implemented a particular attribute yet

Cell Level Methods

setCell(row_num, col_num, "content")

Sets the content of a table cell. This could be any string, even another table object via the getTable method. If the row and/or column numbers are outside the existing table boundaries extra rows and/or columns are created automatically.

setSectionCell([tbody|thead|tfoot], section_num, row_num, col_num, "content")

Same as setCell, but able to specify which section to act on.

setCellAlign(row_num, col_num, [center|right|left])

Sets the horizontal alignment for the cell.

setSectionCellAlign([tbody|thead|tfoot], section_num, row_num, col_num, [center|right|left])

Same as setCellAlign, but able to specify which section to act on.

setCellVAlign(row_num, col_num, [center|top|bottom|middle|baseline])

Sets the vertical alignment for the cell.

Same as setCellVAlign, but able to specify which section to act on.

setCellWidth(row_num, col_num, [pixels|percentoftable])

Sets the width of the cell.

setSectionCellWidth([tbody|thead|tfoot], section_num, row_num, col_num, [pixels|percentoftable])

Same as setCellWidth, but able to specify which section to act on.

setCellHeight(row_num, col_num, [pixels])

Sets the height of the cell.

setSectionCellHeight([tbody|thead|tfoot], section_num, row_num, col_num, [pixels])

Same as setCellHeight, but able to specify which section to act on.

setCellHead(row_num, col_num, [0|1])

Sets cell to be of type head (Ie <th></th>)

setSectionCellHead([tbody|thead|tfoot], section_num, row_num, col_num, [0|1])

Same as setCellHead, but able to specify which section to act on.

setCellNoWrap(row_num, col_num, [0|1])

Sets the NoWrap attribute of the cell.

setSectionCellNoWrap([tbody|thead|tfoot], section_num, row_num, col_num, [0|1])

Same as setCellNoWrap, but able to specify which section to act on.

setCellBGColor(row_num, col_num, [colorname|colortriplet])

Sets the background colour for the cell.

setSectionCellBGColor([tbody|thead|tfoot], section_num, row_num, col_num, [colorname|colortriplet])

Same as setCellBGColor, but able to specify which section to act on.

setCellRowSpan(row_num, col_num, num_cells)

Causes the cell to overlap a number of cells below it. If the overlap number is greater than number of cells below the cell, a false value will be returned.

setSectionCellRowSpan([tbody|thead|tfoot], section_num, row_num, col_num, num_cells)

Same as setCellRowSpan, but able to specify which section to act on.

setCellColSpan(row_num, col_num, num_cells)

Causes the cell to overlap a number of cells to the right. If the overlap number is greater than number of cells to the right of the cell, a false value will be returned.

setSectionCellColSpan([tbody|thead|tfoot], section_num, row_num, col_num, num_cells)

Same as setCellColSpan, but able to specify which section to act on.

setCellSpan(row_num, col_num, num_rows, num_cols)

Joins the block of cells with the starting cell specified. The joined area will be num_cols wide and num_rows deep.

setSectionCellSpan([tbody|thead|tfoot], section_num, row_num, col_num, num_rows, num_cols)

Same as setCellSpan, but able to specify which section to act on.

setCellFormat(row_num, col_num, start_string, end_string)

Start_string should be a string of valid HTML, which is output before the cell contents, end_string is valid HTML that is output after the cell contents. This enables formatting to be applied to the cell contents.

        $table->setCellFormat(1, 2, '<b>', '</b>');

setSectionCellFormat([tbody|thead|tfoot], section_num, row_num, col_num, start_string, end_string)

Same as setCellFormat, but able to specify which section to act on.

setCellStyle (row_num, col_num, 'css style')

Sets the cell style attribute.

setSectionCellStyle([tbody|thead|tfoot], section_num, row_num, col_num, 'css style')

Same as setCellStyle, but able to specify which section to act on.

setCellClass (row_num, col_num, 'css class')

Sets the cell class attribute.

setSectionCellClass([tbody|thead|tfoot], section_num, row_num, col_num, 'css class')

Same as setCellClass, but able to specify which section to act on.

setCellAttr (row_num, col_num, 'user attribute')

Sets a user defined attribute for the cell. Useful for when HTML::Table hasn't implemented a particular attribute yet

setSectionCellAttr([tbody|thead|tfoot], section_num, row_num, col_num, 'css class')

Same as setCellAttr, but able to specify which section to act on.

setLastCell*

All of the setCell methods have a corresponding setLastCell method which does not accept the row_num and col_num parameters, but automatically applies to the last row and last col of the table.

NB. Only works on the setCell* methods, not on the setSectionCell* methods.

getCell(row_num, col_num)

Returns the contents of the specified cell as a string.

getSectionCell([tbody|thead|tfoot], section_num, row_num, col_num)

Same as getCell, but able to specify which section to act on.

getCellStyle(row_num, col_num)

Returns cell's style attribute.

getSectionCellStyle([tbody|thead|tfoot], section_num, row_num, col_num)

Same as getCellStyle, but able to specify which section to act on.

Column Level Methods

addCol("cell 1 content" [, "cell 2 content", ...]): Adds a column to the right end of the table. Assumes if you pass more values than there are rows that you want to increase the number of rows.
addSectionCol([tbody|thead|tfoot], section_num, "cell 1 content" [, "cell 2 content", ...]): Same as addCol, but able to specify which section to act on.
setColAlign(col_num, [center|right|left]): Applies setCellAlign over the entire column.
setSectionColAlign([tbody|thead|tfoot], section_num, col_num, [center|right|left]): Same as setColAlign, but able to specify which section to act on.
setColVAlign(col_num, [center|top|bottom|middle|baseline]): Applies setCellVAlign over the entire column.
setSectionColVAlign([tbody|thead|tfoot], section_num, col_num, [center|top|bottom|middle|baseline]): Same as setColVAlign, but able to specify which section to act on.
setColWidth(col_num, [pixels|percentoftable]): Applies setCellWidth over the entire column.
setSectionColWidth([tbody|thead|tfoot], section_num, col_num, [pixels|percentoftable]): Same as setColWidth, but able to specify which section to act on.
setColHeight(col_num, [pixels]): Applies setCellHeight over the entire column.
setSectionColHeight([tbody|thead|tfoot], section_num, col_num, [pixels]): Same as setColHeight, but able to specify which section to act on.
setColHead(col_num, [0|1]): Applies setCellHead over the entire column.
setSectionColHead([tbody|thead|tfoot], section_num, col_num, [0|1]): Same as setColHead, but able to specify which section to act on.
setColNoWrap(col_num, [0|1]): Applies setCellNoWrap over the entire column.
setSectionColNoWrap([tbody|thead|tfoot], section_num, col_num, [0|1]): Same as setColNoWrap, but able to specify which section to act on.
setColBGColor(row_num, [colorname|colortriplet]): Applies setCellBGColor over the entire column.
setSectionColBGColor([tbody|thead|tfoot], section_num, col_num, [colorname|colortriplet]): Same as setColBGColor, but able to specify which section to act on.
setColFormat(col_num, start_string, end_sting): Applies setCellFormat over the entire column.
setSectionColFormat([tbody|thead|tfoot], section_num, col_num, start_string, end_sting): Same as setColFormat, but able to specify which section to act on.
setColStyle (col_num, 'css style'): Applies setCellStyle over the entire column.
setSectionColStyle([tbody|thead|tfoot], section_num, col_num, 'css style'): Same as setColStyle, but able to specify which section to act on.
setColClass (col_num, 'css class'): Applies setCellClass over the entire column.
setSectionColClass([tbody|thead|tfoot], section_num, col_num, 'css class'): Same as setColClass, but able to specify which section to act on.
setColAttr (col_num, 'user attribute'): Applies setCellAttr over the entire column.
setSectionColAttr([tbody|thead|tfoot], section_num, col_num, 'user attribute'): Same as setColAttr, but able to specify which section to act on.
setLastCol*: All of the setCol methods have a corresponding setLastCol method which does not accept the col_num parameter, but automatically applies to the last col of the table.
NB. Only works on the setCol* methods, not on the setSectionCol* methods.
getColStyle(col_num): Returns column's style attribute. Only really useful after setting a column's style via setColStyle().
getSectionColStyle([tbody|thead|tfoot], section_num, col_num): Same as getColStyle, but able to specify which section to act on.

Row Level Methods

addRow("cell 1 content" [, "cell 2 content", ...]): Adds a row to the bottom of the first body section of the table.
Adds a row to the bottom of the table. Assumes if you pass more values than there are columns that you want to increase the number of columns.
addSectionRow([tbody|thead|tfoot], section_num, "cell 1 content" [, "cell 2 content", ...]): Same as addRow, but able to specify which section to act on.
delRow(row_num): Deletes a row from the first body section of the table. If -1 is passed as row_num, the last row in the section will be deleted.
delSectionRow([tbody|thead|tfoot], section_num, row_num): Same as delRow, but able to specify which section to act on.
setRowAlign(row_num, [center|right|left]): Sets the Align attribute of the row.
setSectionRowAlign([tbody|thead|tfoot], section_num, row_num, [center|right|left]): Same as setRowAlign, but able to specify which section to act on.
setRowVAlign(row_num, [center|top|bottom|middle|baseline]): Sets the VAlign attribute of the row.
setSectionRowVAlign([tbody|thead|tfoot], section_num, row_num, [center|top|bottom|middle|baseline]): Same as setRowVAlign, but able to specify which section to act on.
setRowNoWrap(col_num, [0|1]): Sets the NoWrap attribute of the row.
setSectionRowNoWrap([tbody|thead|tfoot], section_num, row_num, [0|1]): Same as setRowNoWrap, but able to specify which section to act on.
setRowBGColor(row_num, [colorname|colortriplet]): Sets the BGColor attribute of the row.
setSectionRowBGColor([tbody|thead|tfoot], section_num, row_num, [colorname|colortriplet]): Same as setRowBGColor, but able to specify which section to act on.
setRowStyle (row_num, 'css style'): Sets the Style attribute of the row.
setSectionRowStyle([tbody|thead|tfoot], section_num, row_num, 'css style'): Same as setRowStyle, but able to specify which section to act on.
setRowClass (row_num, 'css class'): Sets the Class attribute of the row.
setSectionRowClass([tbody|thead|tfoot], section_num, row_num, 'css class'): Same as setRowClass, but able to specify which section to act on.
setRowAttr (row_num, 'user attribute'): Sets the Attr attribute of the row.
setSectionRowAttr([tbody|thead|tfoot], section_num, row_num, 'user attribute'): Same as setRowAttr, but able to specify which section to act on.
setRCellsWidth(row_num, [pixels|percentoftable])
setRowWidth(row_num, [pixels|percentoftable]) ** Deprecated **: Applies setCellWidth over the entire row.
setSectionRCellsWidth([tbody|thead|tfoot], section_num, row_num, [pixels|percentoftable])
setSectionRowWidth([tbody|thead|tfoot], section_num, row_num, [pixels|percentoftable]) ** Deprecated **: Same as setRowWidth, but able to specify which section to act on.
setRCellsHeight(row_num, [pixels])
setRowHeight(row_num, [pixels]) ** Deprecated **: Applies setCellHeight over the entire row.
setSectionRCellsHeight([tbody|thead|tfoot], section_num, row_num, [pixels])
setSectionRowHeight([tbody|thead|tfoot], section_num, row_num, [pixels]) ** Deprecated **: Same as setRowHeight, but able to specify which section to act on.
setRCellsHead(row_num, [0|1])
setRowHead(row_num, [0|1]) ** Deprecated **: Applies setCellHead over the entire row.
setSectionRCellsHead([tbody|thead|tfoot], section_num, row_num, [0|1])
setSectionRowHead([tbody|thead|tfoot], section_num, row_num, [0|1]) ** Deprecated **: Same as setRowHead, but able to specify which section to act on.
setRCellsFormat(row_num, start_string, end_string)
setRowFormat(row_num, start_string, end_string) ** Deprecated **: Applies setCellFormat over the entire row.
setSectionRCellsFormat([tbody|thead|tfoot], section_num, row_num, start_string, end_string)
setSectionRowFormat([tbody|thead|tfoot], section_num, row_num, start_string, end_string) ** Deprecated **: Same as setRowFormat, but able to specify which section to act on.
setLastRow*: All of the setRow methods have a corresponding setLastRow method which does not accept the row_num parameter, but automatically applies to the last row of the table.
NB. Only works on the setRow* methods, not on the setSectionRow* methods.
getRowStyle(row_num): Returns row's style attribute.
getSectionRowStyle([tbody|thead|tfoot], section_num, row_num): Same as getRowStyle, but able to specify which section to act on.

Output Methods

getTable

Returns a string containing the HTML representation of the table.

The same effect can also be achieved by using the object reference in a string scalar context.

For example...

        This code snippet:

                $table = new HTML::Table(2, 2);
                print '<p>Start</p>';
                print $table->getTable;
                print '<p>End</p>';

        would produce the same output as:

                $table = new HTML::Table(2, 2);
                print "<p>Start</p>$table<p>End</p>";

print

Prints HTML representation of the table to STDOUT

CLASS VARIABLES

HISTORY

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

AUTHOR

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

CONTRIBUTIONS

Douglas Riordan <doug.riordan@gmail.com> For get methods for Style attributes.

Jay Flaherty, fty@mediapulse.com For ROW, COL & CELL HEAD methods. Modified the new method to allow hash of values.

John Stumbles, john@uk.stumbles.org For autogrow behaviour of setCell, and allowing alignment specifications to be case insensitive

Arno Teunisse, Arno.Teunisse@Simac.nl For the methods adding rules, styles and table alignment attributes.

Ville Skyttä, ville.skytta@iki.fi For general fixes

Paul Vernaza, vernaza@stwing.upenn.edu For the setLast... methods

David Link, dvlink@yahoo.com For the sort method

Tommi Maekitalo, t.maekitalo@epgmbh.de For adding the 'head' parameter to the new method and for adding the initialisation from an array ref to the new method.

Chris Weyl, cweyl@alumni.drew.edu For adding the even/odd row class support.

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 788:: Non-ASCII character seen before =encoding in 'Skyttä,'. Assuming CP1252