Introduction

Writing your own DataSource driver is the way to go when none of the existing driver suit your needs. It is actually pretty easy, and allows for great flexibility.

Of course, if you're trying to fetch data from an exotic source, writing your own driver is required. But, sometimes it's also the best way to achieve the best optimization, especially (but not only) with databases.

This document will present you the DataSource interface, and how to implement it.

Definitions

A DataSource driver is a descendent of the Structures_DataGrid_DataSource class, which implements the DataSource interface.

DataSource is a synomym for DataSource driver.

The DataSource interface consists in a set of methods that drivers must or may overload and protected properties that drivers can use, as well as recommended practices.

A DataSource container is a constant or a variable of any type (string, array, object, etc...) that either contains data or describes how to retrieve data.

Every DataSource driver is specific to, and knows how to handle, a given DataSource container type.

The DataSource interface

A simple driver

Let's start with a very simple driver. It is rather readable and you shouldn't have much trouble understanding it. It is not extremely useful to write a custom driver for a such simple SQL query, but it should get you started.

<?php
require 'Structures/DataGrid/DataSource.php';
require_once 'DB.php';
 class MyDataSource extends Structures_DataGrid_DataSource {
 
    var $db;
    var $orderBy = '';
 
    function MyDataSource() {
        $dsn = 'mysql://someuser:apasswd@localhost/thedb';
        $this->db =& DB::connect($dsn);
    }

    function count() {
        $query = "SELECT COUNT(*) FROM animals WHERE species='cat'";
        return $this->db->getOne($query);
    }

    function sort($sortSpec, $sortDir = 'ASC') {
        $this->orderBy = "ORDER BY $sortSpec $sortDir"; 
    }

    function fetch($offset = 0, $len = null) {
        
        $limit = is_null($len) ? "LIMIT $offset,18446744073709551615" 
                               : "LIMIT $offset,$len";
    
        $query  = "SELECT * FROM animals WHERE species='cat' ";
        $query .= $this->_orderBy . " $limit";

        return $this->db->getAll($query);
    }
}

?>

Testing your driver

Before going live, it is very recommended to test your driver with the dump() method.

<?php
$datasource = new MyDataSource();

$count = $datasource->count();
echo "There are $count cats in the farm\n\n";

$datasource->sort('weight');

echo "Here are the 5 lightest ones: \n";

// dump() accepts the same $offset and $len argument as fetch()
$datasource->dump(0,5);
?>

That should output a nicely formated ascii table like:

There are 23 cats in the farm.

Here are the 5 lightest ones:
+---------+---------+-----------+--------+
| name    | species | birthDate | weight |
+---------+---------+-----------+--------+
| sarge   | cat     | 20021220  | 1.8    |
| etch    | cat     | 20000509  | 2.5    |
| potato  | cat     | 19980128  | 3.8    |
| sid     | cat     | 20011101  | 4.1    |
| woody   | cat     | 19970712  | 6.0    |
+---------+---------+-----------+--------+

Using your new driver

Okay, so you have written a driver that's tailored to your needs, and tested it. It is now time to connect it to Structures_DataGrid.

For this purpose we're going to use the bindDataSource() method.

<?php

$datagrid =& new Structures_DataGrid(); 

$datasource = new MyDataSource();

$datagrid->bindDataSource($datasource);

$datagrid->render();
?>

That should output a sortable HTML table.

Of course, the usual features of Structures_DataGrid are now available to you: paging, other output formats as XML, MS-Excel, etc...