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

I'm using the HTML_Table Renderer. How can I use multiple grids on the same page?

The setRequestPrefix() method is the solution for this problem. Each DataGrid for the page needs such a prefix that is internally used before the GET parameters for sorting and paging. An example of the usage:

<?php
require_once 'Structures/DataGrid.php';

$datagrid1 = new Structures_DataGrid();
$datagrid2 = new Structures_DataGrid();

$datagrid1->setRequestPrefix('trade_');
$datagrid2->setRequestPrefix('stock_');

$datagrid1->bind('SELECT * FROM trade', array('dsn' => DSN));
$datagrid2->bind('SELECT * FROM stock', array('dsn' => DSN));

$datagrid1->render();
$datagrid2->render();
?>

You need to call setRequestPrefix() before calling bind().

Which DataSource drivers are recommended?

Currently there are five DataSource drivers that are recommended in the sense of efficiency:

• DB_DataObject

• DB_Table

• DBQuery

• MDB2

• PDO

These four drivers will only fetch the needed records from the database. For example, if you have a row limit of 15 records per page, they will only fetch (up to) 15 records.

All other DataSource drivers can, of course, also be used. But there is no logic implemented (better said: implementable) to avoid fetching (or keeping in memory) unneeded records.

I'd like to add row numbers to my DataGrid. How can I do this?

You need a formatter for the new column that should hold the row number. The first parameter that is passed to such a formatter function contains a currRow value with the row number per page. For calculating the row number relative to the whole table, you need to take also the getCurrentRecordNumberStart() method into account.

The following code snippet shows you how to define the formatter function and how to add the column (with # as the column label and right aligned values):

<?php
function formatRowNumber($params, $recordNumberStart)
{
    return $params['currRow'] + $recordNumberStart;
}

$datagrid->addColumn(
    new Structures_DataGrid_Column(
        '#',
        null,
        null,
        array('style' => 'text-align: right;'),
        null,
        'formatRowNumber',
        $datagrid->getCurrentRecordNumberStart()
    ));
?>

I'm using the Excel Renderer and would like to have the € sign in the resulting Excel file, but I always get only a box or some funny characters. How can I get the right € sign?

Instead of using an encoding like ISO-8859-15, you need to use Windows-1252.

Streaming is a nice feature. Why isn't streaming the default behaviour?

Streaming support in Structures_DataGrid is intended to be used with large datasets. But it can also be used with very small datasets without loss of performance.

As always, there is an exception to this rule: When you're using one of the DataSource drivers that fetch data from a database and you have queries that need a lot of time for computation of the results, you should not use streaming, as running such a complex query multiple times will need even more time, of course.

I have used $renderer->toHtml(); with older versions of Structures_DataGrid, but this does not work anymore. How can I fix my code?

If you just want to output the HTML code, use the following line of code:

<?php
$datagrid->render()
?>

If you want to get the generated HTML code, e.g. for using it within a template, use the following line of code:

<?php
$html = $datagrid->getOutput();
?>

All the rows are displayed on one page. Why isn't it paging the data?

Don't forget to pass the number of rows per page to the constructor:

<?php
$datagrid =& new Structures_DataGrid(10); // 10 rows per page
?>

Sorting doesn't work with MDB2 DataSource driver if I have column names in uppercase letters. Why?

This is caused by MDB2's portability settings that are enabled by default. The MDB2_PORTABILITY_FIX_CASE setting is set to CASE_LOWER, resulting in lowercased letters for all column names. Disable this or all portability settings of MDB2 to avoid sorting problem with Structures_DataGrid.