PHPBuilder.com, the best resource for PHP tutorials, templates, PHP manuals, content management systems, scripts, classes and more.

Sr. Web Developer
mediabistro.com
US-NY-New York

Using PEAR's HTML_Table Class

A Simpler Approach to Tables

Within the current incarnation of (X)HTML tables are the building blocks to well organized and attractive designs. They allow the developer an incredible amount of control over the visual representation of information and graphics. However they come with a catch, they are an absolute headache to write into your PHP code. The simple process of querying a database and showing the results in a table becomes a disorganized and ungainly process looking something like this:



<?php
//get our query
$connection = mysql_connect("localhost", "me", "password");
$sql = "SELECT * FROM users";
$result = mysql_query($sql, $connection);

//echo our table
echo "<table width=\"100%\" border=\"1\">";
echo "<tr>
        <th>Name</th>
        <th>E-mail</th>
        <th>Phone Number</th>
<tr>";

while($row = mysql_fetch_array($result) {
        echo "<tr>
                <td bgcolor=\"#COCOCO\">" . $row['name'] . "</td>
                <td bgcolor=\"#COCOCO\">" . $row['email'] . "</td>
                <td bgcolor=\"#COCOCO\">" . $row['phone'] . "</td>
        </tr>";
}
echo "</table>";
?>

Clearly this is not an eloquent solution. We either need to use multiple echo statements or as we use the above string one together to make one long statement.

Thankfully there is a solution: the PEAR HTML_Table class.

What is PEAR HTML_Table?

(PHP Extension and Application Repository) (PEAR) is a large body of PHP classes developed to make your life as a PHP programmer easier, by providing a library of prewritten code while also establishing a series of coding standards.

The HTML_Table class makes building tables much simpler, helps you maintain cleaner more readable code and brings the advantages of object oriented code to your work. If you are unfamiliar with working with objects in PHP, I recommend that you read either the relevant section of the PHP documentation or this article will make very little sense. You will also need to make sure that you download and install a copy of the code as well as it's dependencies, all of which can be found here. Instructions for installing PEAR and it's various classes is beyond the scope of this document but the PEAR documentation is very good and should be able to answer your questions.

So How do I Use This Thing?

To show you the advantages of the HTML_Table class let's recreate the table we used before, this time using the HTML_Table class.



<?php
//get our query
$connection = mysql_connect("localhost", "me", "password");
$sql = "SELECT * FROM users";
$result = mysql_query($sql, $connection);

//include the class
require_once("/HTML/Table.php");

//set table attributes
$attributes = array("width"=>"100%",
                        "border"=>"1");

//create the table class
$table = new HTML_Table($attributes);

//build our first row
$contents = array("Name", "E-Mail", "Phone Number");
$attributes = array("bgcolor"="#336699");
$table->addRow($contents, $attributes, "TH");

//loop through and add our data
$attributes = array("bgcolor"="#COCOCO")

while($row = mysql_fetch_array($result)) {
        $contents = array($row['name'], $row['email'], $row['phone']);
        $table->addRow($contents, $attributes);
}

$table->display();
?>

As we can clearly see this approach is much cleaner and more efficient. So lets take a walk through the code and see how it works.

The first part of the code, which retrieves our database results, remains the same. Next we have a require_once statement to include the Table Class into our current document.

Next we define the attributes of our table. This can be done by either creating a string of attributes, or creating an associative array of the attributes and values.



<?php
$attributes = "width=\"100%\" border=\"1\""; //string of attributes
$attributes = array("width"=>"100%", "border"=>"1"); //array of attributes
?>

Now that we have defined the way that we want the table to look we create an instance of the class with our attributes as an argument.

In the next several lines we create the first line of our table. First we define the contents in an array with each element representing a different cell of the table. Next we define the attributes of that row. Then we use the addRow function to add the row to the table. Note that we use the third argument to set the cell type to be a header. The addRow function has the following attributes:



<?php
addRow($contents = null, $attributes = null, $type = 'TD', $inTR = false)
?>

Now that we have a header row, we loop through our database results and add a row to the table for each row of the results.

Lastly we add use the display() function to output our table.

Changing the Look of Things

Now that we have learned to build tables with the class, let us take a look at how to spice them up a bit. To do this we have a wide selection of tools which allow us to change the way that the table looks on 3 levels:

Table Level
Row or Column Level
Cell Level

1. At the table level we manipulate properties with either the setAllAttibutes or the updateAllAttributes functions. The only difference between these two functions is that updateAllAttributes will add attributes to your table, leaving current attributes in place while setAllAttributes will replace whatever has been previously set. The usage of these two functions is as follows:



<?php
setAllAttributes($properties);
updateAllAttributes($properties);
?>

Where $properties is either a string or an associative array as discussed previously.

2. To manipulate the attributes of rows and columns we use the following functions:



<?php
setRowAttributes($row, $attributes);
updateRowAttributes($row, $attributes, $inTR);

setColAttributes($col, $attributes);
updateColAttributes($col, $attributes);
?>

The use of these functions is fairly straight forward but there is one important thing to remember. First the $row and $col attributes are the numbers of the row or column that you wish to change. Numbering of rows and columns starts at 0, so in order to make the first row of the table have a background color of blue, you would use the following code segment:



<?php
$attributes = array(bgcolor=>#0000FF);
$table->updateRowAttributes(0, $attributes);
?>

3. In order to set attributes of individual cells we would use one of these two functions:



<?php
setCellAttributes($row, $col, $attributes);
updateCellAttributes($row, $col, $attributes);
?>

Both functions are very straight forward, simply specify the cell location by row and column number then specify the attributes. Again, row and column numbers start at 0.

A Few Last Tricks

And before we close here are few last tricks that come along with this very useful class.

Alternating Rows

One of the most common tasks when creating tables containing database output is alternating colors to make it easier to read. The HTML_Table class makes this easy to do, using the altRowAttributes function. Using our example from before the function works like this:



<?php
//..database retrieval... 

while($row = mysql_fetch_array($result)) {
        $contents = array($row['name'], $row['email'], $row['phone']);
        $table->addRow($contents, $attributes);
}
//alternate between 2 colors
$attributes1 = bgcolor = #336699;
$attributes2 = bgcolor = #COCOCO;
$table->altRowAttributes(1, $attributes1, $attributes2);

$table->display();
?>

This will result in the rows switching colors with every row, starting with the second (as our first row is a header).

Outputting to HTML

Another useful feature is the toHtml() function which works much the same as the display function but instead returns the html rather than outputting directly. This is useful if you are building the table in a function or need to display the table in a place other than where you built it.

In parting, I hope that I have shown you the benefits of the HTML_Table class. There are several other functions which I felt were beyond the scope of this introduction but I very much encourage you to browse the code yourself and find them. I think you will find the documentation to be very well done.