既存のドライバの中に要件を満たすものがない場合は、 独自のデータソースドライバを書くことになります。 これはとても簡単に行うことができ、非常に柔軟性が高くなります。
風変わりなソースからデータを取得する場合に 独自のドライバを書く必要があるのは当然ですが、 それ以外にも、特にデータベースなど (それに限りませんが) へのアクセスを最適化するといった目的でも独自のドライバを書くことがあります。
このドキュメントでは、データソースのインターフェイスとその実装方法を説明します。
データソースドライバ は、 Structures_DataGrid_DataSource クラスを継承したものです。 これは データソースインターフェイス を実装しています。
データソース は、 データソースドライバ と同じ意味で使用します。
データソースインターフェイス には、 ドライバがオーバーロードするメソッド群が含まれます。また、 ドライバが使用できる protected なプロパティや推奨する実装が含まれます。
データソースコンテナ は定数あるいは任意の型 (string, array, object など) の変数で、データ自身あるいはデータの取得方法が含まれます。
すべての データソースドライバ は、 指定した データソースコンテナ に固有のもので、 そのコンテナを処理する方法を知っています。
array $_options
- データをバインドした際のオプションが
連想配列で含まれます。このプロパティの内容を読み込むことはできますが、
直接書き換えてはいけません。
constructor (
void
)
object bind (
mixed container
, array options
)
container
をドライバに読み込みます。その際に options
を適用します。このメソッドは必須ではありません。
失敗した場合には PEAR_Error オブジェクトを返す必要があります。
object count (
void
)
object sort (
mixed sortSpec
, array sortDir
)
sortSpec
およびオプションの
sortDir
にしたがってデータを並べ替えます。
このメソッドは必須で、fetch() の前に常にコールされます。
失敗した場合には PEAR_Error オブジェクトを返す必要があります。
mixed fetch (
integer offset
, integer len
)
offset
で指定した場所のレコードから始まり、
len
で指定した件数を含みます。このメソッドは必須です。
失敗した場合には PEAR_Error オブジェクトを返す必要があります。
void _addDefaultOptions (
array options
)
void setOptions (
array options
)
まずはシンプルなドライバからはじめてみましょう。そのほうが、読んで理解しやすいでしょう。 こんな SQL クエリのために独自のドライバを書くのは実用的ではありませんが、 はじめの一歩としてはお勧めです。
シンプルな SQL アダプタ
<?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);
}
}
?>
実際に使用する前に dump() メソッドでドライバをテストしてみることをお勧めします。
dump() によるテスト
<?php
$datasource = new MyDataSource();
$count = $datasource->count();
echo "農場には $count 匹の猫がいます\n\n";
$datasource->sort('weight');
echo "一番軽いほうから 5 匹を表示します。\n";
// dump() は $offset および $len を fetch() と同じように受け付けます
$datasource->dump(0,5);
?>
このメソッドは、次のようにきれいに整形されたテキストのテーブルを出力します。
農場には 23 匹の猫がいます
一番軽いほうから 5 匹を表示します。
+---------+---------+-----------+--------+
| 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 |
+---------+---------+-----------+--------+
さあ、これであなた専用のドライバができあがり、テストも完了しました。 そろそろ Structures_DataGrid で使用してみましょう。
そのためには、 bindDataSource() メソッドを使用します。
独自のデータソースのバインド
<?php
$datagrid =& new Structures_DataGrid();
$datasource = new MyDataSource();
$datagrid->bindDataSource($datasource);
$datagrid->render();
?>
これは、並べ替えのできる HTML テーブルを出力します。
もちろん、それ以外の Structures_DataGrid の機能も使用可能です。 例えばページ処理をしたり、XML や MS-Excel などの別のフォーマットで出力したりなどができます。