Home » HTML » HTML_Table » Manual

Introduction

Introduction – Creating an HTML-Table

What is HTML_Table?

HTML_Table offers an interface for create a HTML table. You can work with the table like a spreadsheet. Instead of working with HTML code and linear adding of cells, you can address and fill cells independend of there position. There is no different, whether you start with fill a cell at the beginning, in the middle or at the end of the table, a row or a column.

The autoGrow and autoFill value

The autoGrow flag

Normaly, you would define a table with a constant number of rows and columns. But sometimes, you does not know, how many rows or columns you need: ie. transforming user input or the result of a database query to an HTML table.

In this case, you should enable the autoGrow feature. In this mode, HTML_Table adds new rows or columns automatically, if you use a cell address located in a not existing row or column.

The autoFill value

If you create a table of data, sometimes you have not to fill all cells with different values. Perhaps you do not know the value for a cell, or you want to insert a default value - ie. retrieving data about users. Not every user has a mobile, a email address etc., in this case, an "n/a" should be inserted into that specific cell.

So, simply define "n/a" as autoFill value and fill only the cells where data exist. You need not to fill every cell; unfilled cells contain automatically an "n/a".

Creating a table

The demonstation data

Our HTML table to create should contain the following data:

<?php
$data = array(
 '0' => array('Bakken', 'Stig', '', 'stig@example.com'),
 '1' => array('Merz', 'Alexander', 'alex.example.com', 'alex@example.com'),
 '2' => array('Daniel', 'Adam', '', '')
);
?>

Start

Let us now start by creating a new instance of HTML_Table. The table should be 600 pixel wide. We do not know the quantity of the data to insert into the table - so we enable the autoGrow feature. Unfilled cells should contain an "n/a".

<?php
require_once 'HTML/Table.php';

$attrs = array('width' => '600');
$table = new HTML_Table($attrs);
$table->setAutoGrow(true);
$table->setAutoFill('n/a');
?>

Setting table attributes is also possible by using the setAttributes() method. Therefore, the example from above can also be written as:

<?php
require_once 'HTML/Table.php';

$attrs = array('width' => '600');
$table = new HTML_Table();
$table->setAttributes($attrs);
// [...]
?>

Add data rows

Now process every data entry. Here we use also the alternate feature of HTML_Table. Every second row will be colored red.

<?php
for ($nr = 0; $nr < count($data); $nr++) {
  $table->setHeaderContents($nr+1, 0, (string)$nr);
  for ($i = 0; $i < 4; $i++) {
    if ('' != $data[$nr][$i]) {
      $table->setCellContents($nr+1, $i+1, $data[$nr][$i]);
    }
  }
}
$altRow = array('bgcolor' => 'red');
$table->altRowAttributes(1, null, $altRow);
?>

Add header cells

Now we want to define the cells in the first row and column as header cells. It should looks like a spreadsheet application, so we want to use the color "silver" as the background colour for each header cell. The first row contains a column headline, the first column the number of the data set row.

<?php
$table->setHeaderContents(0, 0, '');
$table->setHeaderContents(0, 1, 'Surname');
$table->setHeaderContents(0, 2, 'Name');
$table->setHeaderContents(0, 3, 'Website');
$table->setHeaderContents(0, 4, 'EMail');
$hrAttrs = array('bgcolor' => 'silver');
$table->setRowAttributes(0, $hrAttrs, true);
$table->setColAttributes(0, $hrAttrs);
?>

Print the table

It is done! Our table is finished, now we can output the table as HTML code.

<?php
echo $table->toHtml();
?>

The output will look like this:

Using thead, tfoot and tbody

If you want to divide your tables into thead, tfoot and tbody groups, you need to get table objects using getHeader(), getFooter(), and getBody(), which you can then use like the normal table object.

<?php
$table = new HTML_Table();
$head =& $table->getHeader();
$foot =& $table->getFooter();
$body =& $table->getBody();
$head->setCellContents(...);
$body->setCellContents(...);
echo $table->toHtml();
?>

In this example, there is no content set for the tfoot group. Therefore, only thead and tbody will be rendered.

The rendering order is thead, then tfoot and as the last group tbody. This is not a bug but intended behaviour because that's the way it is defined in the (X)HTML Standard.

Since release 1.8.0 getBody() and several other methods like setCellAttributes() accept an optional numeric parameter $body that allows you to generate multiple tbody groups in your table. A new group can be generated by using addBody() or, if the autoGrow feature is enabled, by using a new number in one of the mentioned method calls.

FAQ

FAQ – Answers to most Frequently Asked Questions

Description

This document is based on questions asked on PEAR general mailing list and other mailing lists and forums.

HTML_Table FAQ

1. How can I add attributes to the thead, tfoot or tbody tags?
2. How can I set attributes for the table tag?
3. How can I easily add JavaScript sorting facilities to my tables?

How can I add attributes to the thead, tfoot or tbody tags?

Here is an example on how to set the attribute string id="header" for the thead tag. For the other two tags the procedure is similar.

<?php
$table = new HTML_Table();
// [...]
$thead =& $table->getHeader();
$thead->setAttributes(array('id' => 'header'));
// [...]
$table->display();
?>

This would give the following result:

<table>
  <thead id="header">
    [...]
  </thead>
  [...]
</table>

How can I set attributes for the table tag?

Besides the possibility to pass attributes to the HTML_Table constructor, there are several more methods that can be used.

HTML_Table extends HTML_Common which offers methods like setAttributes() or updateAttributes(). A complete list of methods provided by HTML_Common can be found in its API documentation.

How can I easily add JavaScript sorting facilities to my tables?

Stuart Langridge has developed the SortTable JavaScript class that allows adding of sorting facilities to tables very easily. Another class for this purpose is Standardista Table Sorting.

Constructor HTML_Table::HTML_Table()

Constructor HTML_Table::HTML_Table() – Constructor

Synopsis

void HTML_Table::HTML_Table ( array $attributes = null , integer $tabOffset=0 , boolean $useTGroups = false )

Description

Class constructor

Parameter

• array $attributes - Associative array of table tag attributes
• integer $tabOffset - Tab offset of the table
• boolean $useTGroups - Whether to use the thead, tfoot and tbody groups or not

Note

This function can not be called statically.

See

HTML_Table::getBody()

HTML_Table::getFooter()

HTML_Table::getHeader()

HTML_Table::addBody()

HTML_Table::addBody() – Add body

Synopsis

int HTML_Table::addBody ( array $attributes = null )

Description

Adds a new body to the table and returns the body identifier

Parameter

• array $attributes - Associative array of tbody tag attributes

Return value

int - the body identifier

Note

This function can not be called statically.

See

HTML_Table::getBody()

HTML_Table::addCol()

HTML_Table::addCol() – Add column

Synopsis

int HTML_Table::addCol ( array $contents = null , mixed $attributes = null , string $type='TD' , int $body=0 )

Description

Adds a table column and returns the column identifier

Parameter

• array $contents - Must be an indexed array of valid cell contents.
• mixed $attributes - Associative array or string of table row attributes
• string $type - Cell type either 'th' or 'td'
• int $body - The number of the tbody group that should be used

Return value

int - the identifier for the column

Note

This function can not be called statically.

See

HTML_Table::addRow()

HTML_Table::addRow()

HTML_Table::addRow() – Add row

Synopsis

int HTML_Table::addRow ( array $contents = null , mixed $attributes = null , string $type='TD' , boolean $inTR = false , int $body=0 )

Description

Adds a table row and returns the row identifier

Parameter

• array $contents - Must be an indexed array of valid cell contents
• mixed $attributes - Associative array or string of table row attributes. This can also be an array of attributes, in which case the attributes will be repeated in a loop.
• string $type - Cell type either 'th' or 'td'
• boolean $inTR - FALSE, if attributes are to be applied in TD tags; TRUE, if attributes are to be applied in TR tag
• int $body - The number of the tbody group that should be used

Return value

int - the row identifier

Note

This function can not be called statically.

See

HTML_Table::addCol()

HTML_Table::altRowAttributes()

HTML_Table::altRowAttributes() – Alternate row attributes

Synopsis

void HTML_Table::altRowAttributes ( int $start , mixed $attributes1 , mixed $attributes2 , boolean $inTR = false , int $body = null )

Description

Alternates the row attributes starting at $start

Parameter

• int $start - Row index of row in which alternating begins
• mixed $attributes1 - Associative array or string of table row attributes
• mixed $attributes2 - Associative array or string of table row attributes
• boolean $inTR - FALSE, if attributes are to be applied in td tags; TRUE, if attributes are to be applied in tr tag.
• int $body - The number of the tbody group that should be used. NULL indicates that all groups should be used.

Note

This function can not be called statically.

See

HTML_Table::setAllAttributes(), HTML_Table::updateAllAttributes(), HTML_Table::setColAttributes(), HTML_Table::updateColAttributes(), HTML_Table::setCellAttributes(), HTML_Table::updateCellAttributes(), HTML_Table::updateRowAttributes(), HTML_Table::setRowAttributes()

HTML_Table::apiVersion()

HTML_Table::apiVersion() – Return API version (DEPRECATED)

Synopsis

double HTML_Table::apiVersion ( )

Description

DEPRECATED: Returns the API version of HTML_Table

Return value

double - the version number

Note

This function can not be called statically.

This function is deprecated. That means that future versions of this package may not support it anymore.

HTML_Table::display()

HTML_Table::display() – Output HTML code

Synopsis

string HTML_Table::display ( )

Description

Outputs the table structure as HTML

Note

This function can not be called statically.

See

HTML_Table::toHtml()

HTML_Table::getAutoFill()

HTML_Table::getAutoFill() – Return autoFill value

Synopsis

mixed HTML_Table::getAutoFill ( int $body=0 )

Description

Returns the autoFill value

Parameter

• int $body - The number of the tbody group that should be used

Return value

mixed - the value, which will be inserted into empty cells

Note

This function can not be called statically.

See

HTML_Table::setAutoFill()

HTML_Table::getAutoGrow()

HTML_Table::getAutoGrow() – Return autoGrow flag

Synopsis

boolean HTML_Table::getAutoGrow ( int $body=0 )

Description

Returns the value of the autoGrow flag. If a value into an cell, which not exists, HTML_Table will automatically add a necessary row or column, if the flag is TRUE.

Parameter

• int $body - The number of the tbody group that should be used

Return value

boolean - the flag state

Note

This function can not be called statically.

See

HTML_Table::setAutoGrow()

HTML_Table::getBody()

HTML_Table::getBody() – Return the table object for the tbody group

Synopsis

mixed HTML_Table::getBody ( int $body=0 )

Description

Returns the table object for a tbody group

Parameter

• int $body - The number of the tbody group that should be used

Return value

object - the table object for a tbody group

Note

This function can not be called statically.

See

HTML_Table::HTML_Table()

HTML_Table::getCellAttributes()

HTML_Table::getCellAttributes() – Return cell attributes

Synopsis

array HTML_Table::getCellAttributes ( int $row , int $col , int $body=0 )

Description

Returns the attributes for a given cell

Parameter

• int $row - Row index
• int $col - Column index
• int $body - The number of the tbody group that should be used

Return value

array - the attributes of the specific cell

Note

This function can not be called statically.

See

HTML_Table::getRowAttributes()

HTML_Table::getCellContents()

HTML_Table::getCellContents() – Return cell content

Synopsis

mixed HTML_Table::getCellContents ( int $row , int $col , int $body=0 )

Description

Returns the content of an existing cell

Parameter

• int $row - Row index
• int $col - Column index
• int $body - The number of the tbody group that should be used

Return value

mixed - the content of the specified cell

Note

This function can not be called statically.

HTML_Table::getColCount()

HTML_Table::getColCount() – Return numbers of column

Synopsis

int HTML_Table::getColCount ( int $row=null , int $body=0 )

Description

Returns the number of columns in the table

Parameter

• int $row - The row number to serve for cols count
• int $body - The number of the tbody group that should be used

Return value

int - number of columns

Note

This function can not be called statically.

See

HTML_Table::getRowCount()

HTML_Table::getFooter()

HTML_Table::getFooter() – Return the table object for the tfoot group

Synopsis

mixed HTML_Table::getFooter ( )

Description

Returns the table object for the tfoot group

If the usage of the thead, tfoot and tbody groups was not activated via the third parameter of the constructor, the grouping will be activated automatically when calling this function.

Return value

object - the table object for the tfoot group

Note

This function can not be called statically.

See

HTML_Table::HTML_Table()

HTML_Table::getHeader()

HTML_Table::getHeader() – Return the table object for the thead group

Synopsis

mixed HTML_Table::getHeader ( )

Description

Returns the table object for the thead group

If the usage of the thead, tfoot and tbody groups was not activated via the third parameter of the constructor, the grouping will be activated automatically when calling this function.

Return value

object - the table object for the thead group

Note

This function can not be called statically.

See

HTML_Table::HTML_Table()

HTML_Table::getRowAttributes()

HTML_Table::getRowAttributes() – Return row attributes

Synopsis

array HTML_Table::getRowAttributes ( int $row , int $body=0 )

Description

Returns the attributes for a given row as contained in the tr tag

Parameter

• int $row - Row index
• int $body - The number of the tbody group that should be used

Return value

array - the attributes of the row

Note

This function can not be called statically.

HTML_Table::getRowCount()

HTML_Table::getRowCount() – Return number of rows

Synopsis

int HTML_Table::getRowCount ( int $body=0 )

Description

Returns the number of rows in the table

Parameter

• int $body - The number of the tbody group that should be used

Return value

int - number of rows

Note

This function can not be called statically.

See

HTML_Table::getColCount()

HTML_Table::setAllAttributes()

HTML_Table::setAllAttributes() – Set attributes for all cells

Synopsis

void HTML_Table::setAllAttributes ( mixed $attributes = null , int $body = null )

Description

Sets the attributes for all cells

Parameter

• mixed $attributes - Associative array or string of table cell attributes
• int $body - The number of the tbody group that should be used. NULL indicates that all groups should be used.

Note

This function can not be called statically.

See

HTML_Table::updateAllAttributes(), HTML_Table::setColAttributes(), HTML_Table::setCellAttributes(), HTML_Table::setRowAttributes()

HTML_Table::setAutoGrow()

HTML_Table::setAutoGrow() – Set autoGrow flag

Synopsis

void HTML_Table::setAutoGrow ( bool $grow , int $body = null )

Description

If this flag is set to TRUE, HTML_Table will automatically add new rows or columns when you insert a value into a non-existing cell.

Parameter

• bool $grow - TRUE to automatically grow
• int $body - The number of the tbody group that should be used. NULL indicates that all groups should be used.

Note

This function can not be called statically.

See

HTML_Table::getAutoGrow()

HTML_Table::setAutoFill()

HTML_Table::setAutoFill() – Set autoFill value

Synopsis

void HTML_Table::setAutoFill ( mixed $fill , int $body = null )

Description

The autoFill value will be insert into every cell not filled.

Parameter

• mixed $fill - standard value for empty cells
• int $body - The number of the tbody group that should be used. NULL indicates that all groups should be used.

Note

This function can not be called statically.

See

HTML_Table::getAutoFill()

HTML_Table::setCaption()

HTML_Table::setCaption() – Set table caption

Synopsis

void HTML_Table::setCaption ( string $caption , mixed $attributes = null )

Description

Sets the caption of a table. This does not refer to the <th>-tag. The <caption>-tag defines a headline for the whole table.

Parameter

• string $caption - the caption string
• mixed $attributes - Associative array or string of caption attributes

Note

This function can not be called statically.

HTML_Table::setCellAttributes()

HTML_Table::setCellAttributes() – Set cell attributes

Synopsis

void HTML_Table::setCellAttributes ( int $row , int $col , mixed $attributes , int $body=0 )

Description

Sets the cell attributes for an existing cell. If the given indices do not exist and autoGrow is TRUE then the given row and/or column is automatically added. If autoGrow is FALSE, an error is returned.

Parameter

• int $row - Row index
• int $col - Column index
• mixed $attributes - Associative array or string of table cell attributes
• int $body - The number of the tbody group that should be used

Throws

Note

This function can not be called statically.

See

HTML_Table::setAutoGrow()

HTML_Table::setCellContents()

HTML_Table::setCellContents() – Set cell content

Synopsis

void HTML_Table::setCellContents ( int $row , int $col , mixed $contents , string $type='TD' , int $body=0 )

Description

Sets the cell contents for an existing cell. If the given indices do not exist and autoGrow is TRUE then the given row and/or column is automatically added. If autoGrow is FALSE, then an error is returned.

Parameter

• int $row - Row index
• int $col - Column index
• mixed $contents - May contain HTML or any object with a toHTML() method
• string $type - Cell type either 'th' or 'td'
• int $body - The number of the tbody group that should be used

Throws

Note

This function can not be called statically.

See

HTML_Table::setAutoGrow()

HTML_Table::setColAttributes()

HTML_Table::setColAttributes() – Set column attributes

Synopsis

void HTML_Table::setColAttributes ( int $col , mixed $attributes = null , int $body = null )

Description

Sets the column attributes for an existing column

Parameter

• int $col - Column index
• mixed $attributes - Associative array or string of table column attributes
• int $body - The number of the tbody group that should be used. NULL indicates that all groups should be used.

Note

This function can not be called statically.

See

HTML_Table::setRowAttributes()

HTML_Table::setColCount()

HTML_Table::setColCount() – Set number of columns

Synopsis

void HTML_Table::setColCount ( int $cols , int $body=0 )

Description

Sets the number of columns in the table

Parameter

• int $cols - number of columns to create
• int $body - The number of the tbody group that should be used

Note

This function can not be called statically.

See

HTML_Table::setRowCount()

HTML_Table::setColGroup()

HTML_Table::setColGroup() – Set a colgroup

Synopsis

void HTML_Table::setColGroup ( mixed $colgroup = null , mixed $attributes = null )

Description

Allows to add a colgroup (with attributes)

Parameter

• mixed $colgroup - Empty string, string with attributes or an associative array of attributes for the columns
• mixed $attributes - Associative array or string of colgroup attributes

Example

Usage without a col tag

<?php
require_once 'HTML/Table.php';

$table =& new HTML_Table();

$colgroup = '';
$attributes = 'span="3" class="group1"';
$table->setColGroup($colgroup, $attributes);
?>

Usage with col tags

<?php
require_once 'HTML/Table.php';

$table =& new HTML_Table();

$colgroup = array('style="font-size: 120%;"', 'class="col2"', 'align="right"');
$attributes = 'span="3" class="group1"';
$table->setColGroup($colgroup, $attributes);
?>

Usage with multiple colgroups

<?php
require_once 'HTML/Table.php';

$colgroup = array('style="font-size:120%;"', 'class="col2"', 'align="right"');
$attributes = 'span="3" class="group1"';
$table->setColGroup($colgroup, $attributes);

$colgroup = array(array('class' => 'col4'), array('class' => 'col5'));
$attributes = 'span="2" class="group2"';
$table->setColGroup($colgroup, $attributes);
?>

Note

This function can not be called statically.

HTML_Table::setColType()

HTML_Table::setColType() – Set column type

Synopsis

void HTML_Table::setColType ( int $col , string $type , int $body = null )

Description

Sets the type of a column to 'th' or 'td'

Parameter

• int $col - Column index
• string $type - th or td
• int $body - The number of the tbody group that should be used. NULL indicates that all groups should be used.

Note

This function can not be called statically.

HTML_Table::setHeaderContents()

HTML_Table::setHeaderContents() – Set content of header cell

Synopsis

void HTML_Table::setHeaderContents ( int $row , int $col , mixed $contents , int $body=0 )

Description

Defines the specified cell as a header cell and sets the content

Parameter

• int $row - row index
• int $col - column index
• mixed $contents - cell content
• int $body - The number of the tbody group that should be used

Note

This function can not be called statically.

See

HTML_Table::setCellContent()

HTML_Table::setRowCount()

HTML_Table::setRowCount() – Set row number

Synopsis

void HTML_Table::setRowCount ( int $rows , int $body=0 )

Description

Sets the number of rows in the table

Parameter

• int $rows - number of rows to create
• int $body - The number of the tbody group that should be used

Note

This function can not be called statically.

See

HTML_Table::setColCount()

HTML_Table::setRowType()

HTML_Table::setRowType() – Set row type

Synopsis

void HTML_Table::setRowType ( int $row , string $type , int $body=0 )

Description

Sets the type of a row to 'th' or 'td'

Parameter

• int $row - Row index
• string $type - 'th' or 'td'
• int $body - The number of the tbody group that should be used

Note

This function can not be called statically.

See

HTML_Table::setColType()

HTML_Table::setRowAttributes()

HTML_Table::setRowAttributes() – Set row attributes

Synopsis

void HTML_Table::setRowAttributes ( int $row , mixed $attributes , boolean $inTR = false , int $body=0 )

Description

Sets the attributes for an existing row

Parameter

• int $row - Row index
• mixed $attributes - Associative array or string of table row attributes. This can also be an array of attributes, in which case the attributes will be repeated in a loop.
• boolean $inTR - FALSE, if attributes are to be applied in td tags; TRUE, if attributes are to be applied in tr tag
• int $body - The number of the tbody group that should be used

Throws

Note

This function can not be called statically.

See

HTML_Table::setColAttributes()

HTML_Table::toHtml()

HTML_Table::toHtml() – Return HTML code

Synopsis

string HTML_Table::toHtml ( )

Description

Returns the table structure as HTML

Return value

string - the generated HTML code

Note

This function can not be called statically.

See

HTML_Table::display()

HTML_Table::updateAllAttributes()

HTML_Table::updateAllAttributes() – Update attributes of all cells

Synopsis

void HTML_Table::updateAllAttributes ( mixed $attributes = null , int $body = null )

Description

Updates the attributes for all cells.

Parameter

• mixed $attributes - Associative array or string of table row attributes
• int $body - The number of the tbody group that should be used. NULL indicates that all groups should be used.

Note

This function can not be called statically.

HTML_Table::updateCellAttributes()

HTML_Table::updateCellAttributes() – Update cell attributes

Synopsis

void HTML_Table::updateCellAttributes ( int $row , int $col , mixed $attributes , int $body=0 )

Description

Updates the cell attributes passed but leaves other existing attributes intact

Parameter

• int $row - Row index
• int $col - Column index
• mixed $attributes - Associative array or string of table row attributes
• int $body - The number of the tbody group that should be used

Note

This function can not be called statically.

HTML_Table::updateColAttributes()

HTML_Table::updateColAttributes() – Update column attributes

Synopsis

void HTML_Table::updateColAttributes ( int $col , mixed $attributes = null , int $body = null )

Description

Updates the column attributes for an existing column

Parameter

• int $col - Column index
• mixed $attributes - Associative array or string of table row attributes
• int $body - The number of the tbody group that should be used. NULL indicates that all groups should be used.

Note

This function can not be called statically.

HTML_Table::updateRowAttributes()

HTML_Table::updateRowAttributes() – Update row attributes

Synopsis

void HTML_Table::updateRowAttributes ( int $row , mixed $attributes = null , boolean $inTR = false , int $body=0 )

Description

Updates the row attributes for an existing row

Parameter

• int $row - Row index
• mixed $attributes - Associative array or string of table row attributes
• boolean $inTR - FALSE if attributes are to be applied in td tags; TRUE, if attributes are to be applied in tr tag.
• int $body - The number of the tbody group that should be used

Throws

Note

This function can not be called statically.