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',
                            -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.

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, -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.

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.

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.

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.

setCellAlign(row_num, col_num, [CENTER|RIGHT|LEFT])

Sets the horizontal alignment for the cell.

setCellVAlign(row_num, col_num, [CENTER|TOP|BOTTOM|MIDDLE|BASELINE])

Sets the vertical alignment for the cell.

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

Sets the width of the cell.

setCellHeight(row_num, col_num, [pixels])

Sets the height of the cell.

setCellHead(row_num, col_num)

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

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

Sets the NoWrap attribute of the cell.

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

Sets the background colour for the cell

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.

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.

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.

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>');

setCellStyle (row_num, col_num, 'css style')

Sets the cell style attribute.

setCellClass (row_num, col_num, 'css class')

Sets the cell class attribute.

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

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.

getCell(row_num, col_num)

Returns the contents of the specified cell as a string.

getCellStyle(row_num, col_num)

Returns cell's style attribute.

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.

setColAlign(col_num, [CENTER|RIGHT|LEFT])

Applies setCellAlign over the entire column.

setColVAlign(col_num, [CENTER|TOP|BOTTOM|MIDDLE|BASELINE])

Applies setCellVAlign over the entire column.

setColWidth(col_num, [pixels|percentoftable])

Applies setCellWidth over the entire column.

setColHeight(col_num, [pixels])

Applies setCellHeight over the entire column.

setColHead(col_num)

Applies setCellHead over the entire column.

setColNoWrap(col_num, [0|1])

Applies setCellNoWrap over the entire column.

setColBGColor(row_num, [colorname|colortriplet])

Applies setCellBGColor over the entire column.

setColFormat(col_num, start_string, end_sting)

Applies setCellFormat over the entire column.

setColStyle (col_num, 'css style')

Applies setCellStyle over the entire column.

setColClass (col_num, 'css class')

Applies setCellClass over the entire column.

setColAttr (col_num, 'user attribute')

Applies setCellAttr over the entire column.

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.

getColStyle(col_num)

Returns column's style attribute. Only really useful after setting a column's style via setColStyle().

Row Level Methods

addRow("cell 1 content" [, "cell 2 content", ...])

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.

setRowAlign(row_num, [CENTER|RIGHT|LEFT])

Applies setCellAlign over the entire row.

setRowVAlign(row_num, [CENTER|TOP|BOTTOM|MIDDLE|BASELINE])

Applies setCellVAlign over the entire row.

setRowWidth(row_num, [pixels|percentoftable])

Applies setCellWidth over the entire row.

setRowHeight(row_num, [pixels])

Applies setCellHeight over the entire row.

setRowHead(row_num)

Applies setCellHead over the entire row.

setRowNoWrap(col_num, [0|1])

Applies setCellNoWrap over the entire row.

setRowBGColor(row_num, [colorname|colortriplet])

Applies setCellBGColor over the entire row.

setRowFormat(row_num, start_string, end_string)

Applies setCellFormat over the entire row.

setRowStyle (row_num, 'css style')

Applies setCellStyle over the entire row.

setRowClass (row_num, 'css class')

Applies setCellClass over the entire row.

setRowAttr (row_num, 'user attribute')

Applies setCellAttr over the entire row.

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.

getRowStyle(row_num)

Returns row's style attribute.

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.

COPYRIGHT

Copyright (c) 2000-2005 Anthony Peacock, CHIME. Copyright (c) 1997 Stacy Lacy

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

SEE ALSO

perl(1), CGI(3)

cpanm HTML::Table

perl -MCPAN -e shell
install HTML::Table