Zend Framework 1.7.9 Manual

もっともシンプルな使用法は、dojo.data に各アイテムの identifier フィールドの名前とアイテムの内容 (データ) を渡すことです。 コンストラクタか、あるいは設定用メソッドで渡します。

$data = new Zend_Dojo_Data('id', $items);

$data = new Zend_Dojo_Data();
$data->setIdentifier('id')
     ->addItems($items);

アイテムをひとつずつ追加したり複数一括で追加したりするには、それぞれ addItem() および addItems() を使用します。

$data = new Zend_Dojo_Data($identifier, $items);
$data->addItem($someItem);

$data->addItems($someMoreItems);

Note: 常に identifier を使うこと!

すべての dojo.data データストアは、identifier カラムがメタデータに存在することを必須としています。 Zend_Dojo_Data でもそれは同じです。 identifier のないアイテムを追加しようとすると、 例外が発生します。

個々のアイテムは、次のいずれかとなります。

• 連想配列

• toArray() メソッドを実装したオブジェクト

• その他のオブジェクト (get_object_vars() でシリアライズされます)

これらのアイテムのコレクションをアタッチするには addItems() あるいは setItems() (既存のアイテムはすべて消去されます) を使用します。 これを使用するときには、引数をひとつ指定します。

• 配列

• Traversable インターフェイスを実装したオブジェクト (このインターフェイスは Iterator と ArrayAccess を含んでいます)。

アイテムの label として働くフィールドを指定したい場合は setLabel() をコールします。

$data->setLabel('name');

最後に、Zend_Dojo_Data のアイテムを dojo.data JSON 配列から読み込むには fromJson() メソッドを使用します。

$data->fromJson($json);

Dojo コンポーネントの中には、 dojo.data の中に追加のメタデータを必要とするものもあります。 たとえば dojox.grid.Grid は、データを動的に dojox.data.QueryReadStore から取得することができます。 ページ移動を正しく行うには、返されるデータの中に numRows というキーのデータ (中身はクエリが返す行の数) が必要となります。 これにより、グリッドが (a) サーバ側へのリクエストをいつ送ったらいいのか、 そして (b) いつリクエストが不要になるのか (つまり最終ページに達するのがいつなのか) を知ることができるようになります。 このテクニックを使用すると、大規模なデータセットをグリッドに表示させる際に データ全体をいちどに取得する必要はなくなります。

Zend_Dojo_Data では、 このようなプロパティをオブジェクトのメタデータとして設定することができます。 以下の使用例をご覧ください。

// "numRows" を 100 に設定します
$data->setMetadata('numRows', 100);

// 複数の項目をいちどに設定します
$data->setMetadata(array(
    'numRows' => 100,
    'sort'    => 'name',
));

// メタデータの値を調べます
$numRows = $data->getMetadata('numRows');

// すべてのメタデータを取得します
$metadata = $data->getMetadata();

// メタデータを削除します
$data->clearMetadata('numRows');

// すべてのメタデータを削除します
$data->clearMetadata();

シリアライズ可能なデータコンテナとしての働きだけではなく、 Zend_Dojo_Data にはデータを様々な方法で操作したり 読み込んだりする機能もあります。

Zend_Dojo_Data は、インターフェイス ArrayAccess、Iterator および Countable を実装しています。 そのため、データコレクションをまるで配列であるかのように使用することができます。

すべてのアイテムは、その identifier フィールドを用いて参照します。 identifier は一意でなければならないので、 この値を使用すればレコードを特定できるのです。 参照する方法には、getItem() メソッドを使用するものと配列表記を使用するものの 2 通りがあります。

// getItem() を使用します
$item = $data->getItem('foo');

// あるいは配列表記を使用します
$item = $data['foo'];

identifier がわかれば、それを使用してアイテムを取得したり、 あるいは更新したり削除したり作成したり調べたりすることができます。

// アイテムの更新あるいは作成
$data['foo'] = array('title' => 'Foo', 'email' => 'foo@foo.com');

// アイテムの削除
unset($data['foo']);

// アイテムの確認
if (isset($data[foo])) {
}

すべてのアイテムをループ処理することもできます。 内部的には、すべてのアイテムは配列として格納されています。

foreach ($data as $item) {
    echo $item['title'] . ': ' . $item['description'] . "\n";
}

count で、アイテムの総数を調べることも可能です。

echo count($data), " items found!";

また、このクラスは __toString() を実装しているので、 JSON への変換は単に echo するか文字列にキャストするだけで可能です。

echo $data; // JSON 文字列として echo

$json = (string) $data; // 文字列へのキャスト == JSON へのキャスト