简介
Zend_Dojo
Programmer's Reference Guide

Zend_Dojo_Data: dojo.data Envelopes

Dojo 通过它的 dojo.data 组件为 data-enabled 小部件提供数据抽象。 该组件提供附加数据存储的能力，提供一些关于身份字段和可选的标签字段的元数据以及 从数据存储查询、排序和获取记录和一组记录的 API。

dojo.data 常和XmlHttpRequest一起使用来从服务器取出动态数据。 它的基本机制是扩展 QueryReadStore 来指向一个 URL 并指定查询信息，服务器端就用 下列 JSON 格式来返回数据： 

{
    identifier: '<name>',
    <label: '<label>',>
    items: [
        { name: '...', label: '...', someKey: '...' },
        ...
    ]
}

Zend_Dojo_Data 提供一个简单的接口通过程序来构造这样的结构， 交互并系列化成一个数组或 JSON。

Zend_Dojo_Data 用法

很简单，dojo.data 要求你在每个条目和一组条目（数据）中提供标识符字段的名字。 你可以通过构造函数或 mutators 来传递它们：

Example #1 通过构造函数初始化 Zend_Dojo_Data

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

Example #2 通过 mutators 初始化 Zend_Dojo_Data

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

用 addItem() 和 addItems() 添加一个单个条目或追加多个条目。

Example #3 追加数据到 Zend_Dojo_Data

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

$data->addItems($someMoreItems);

Note: 永远使用标识符！
 每个 dojo.data 数据存储要求以元数据来提供标识符列，Zend_Dojo_Data 也一样。 实际上，如果不用标识符添加条目，将会抛出异常。

条目可以是下列其中之一：

  • 联合数组

  • 实现 toArray() 方法的对象

  • 任何其它对象（将通过 get_object_vars() 系列化 ）

你可以通过 addItems() 或 setItems()（覆盖先前的条目） 附加上述条目的集合； 用的时候，你可以传递一个参数：

  • 数组

  • 实现Traversable接口的对象（包括 Iterator 和 ArrayAccess 接口）。

如果想为条目指定一个用作标签的字段，调用setLabel():

Example #4 在 Zend_Dojo_Data 里指定一个标签字段 

$data->setLabel('name');

最后，你也可以用 fromJson() 方法从 dojo.data JSON 数组加载一个 Zend_Dojo_Data 条目，

Example #5 从 JSON 组装 Zend_Dojo_Data 

$data->fromJson($json);

高级用例

除了可以作为可系列化的数据容器，Zend_Dojo_Data 也可以用各种各样的方法处理和疏导（traverse）数据。

Zend_Dojo_Data 实现 ArrayAccess、 Iterator 和 Countable 的接口。 这意味着你可以使用数据集合几乎就像使用数组一样。

所有的条目通过标识符字段来引用。因为表示符必须是独一无二的，你可用它的值来取出每个记录。 有两个方法可以做这个：通过 getItem() 方法，或通过数组符号。 

// Using getItem():
$item = $data->getItem('foo');

// Or use array notation:
$item = $data['foo'];

如果你知道标识符，你可以用它来读取、更新、删除、创建或测试条目： 

// Update or create an item:
$data['foo'] = array('title' => 'Foo', 'email' => 'foo@foo.com');

// Delete an item:
unset($data['foo']);

// Test for an item:
if (isset($data[foo])) {
}

你也可以遍历所有条目，在内部，所有的条目以数组形式存储。 

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

甚至还可以数出你有多少条目： 

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

最后，因为这个类实现 __toString()， 你也可以通过 echo 它把它传给 JSON 或 字符串： 

echo $data; // echo as JSON string

$json = (string) $data; // cast to string == cast to JSON

可用的方法

除了上述实现接口必须的方法外，下列方法也可用。

  • setItems($items): 一次设置多个条目，覆盖在对象里先前的任何条目。 $items 是一个数组或一个 Traversable 对象。

  • setItem($item, $id = null): 设置一个条目，可选地传递一个显式标识符。 如果有的话，覆盖先前在集合里的条目。有效的条目包括联合数组，实现 toArray() 的对象或任何有 public 属性的对象。

  • addItem($item, $id = null): 添加一个条目，可选地传递一个显式标识符。 如果在集合理已经存在该条目，将产生异常。有效的条目包括联合数组，实现 toArray() 的对象或任何有 public 属性的对象。

  • addItems($items): 一次添加多个条目，追加到任何当前条目。如果新条目的标识符在集合理已经存在，将产生异常。 $items 是一个数组或一个 Traversable 对象。

  • getItems(): 以数组的数组（array of arrays）的形式获取所有条目。

  • hasItem($id): 确定一个条目的标识符是否在集合理存在。

  • getItem($id): 从集合里按给定的标识符获取一个条目；返回一个联合数组。 如果没有条目匹配，返回 null。

  • removeItem($id): 从集合里按给定的标识符删除一个条目。

  • clearItems(): 从集合里删除所有条目。

  • setIdentifier($identifier): 为集合里的每个条目设置表示独一无二的标识符的字段名。

  • getIdentifier(): 获取标识符字段的名字。

  • setLabel($label): 设置用于为条目显示标签的字段的名字。

  • getLabel(): 读取标签字段名。

  • toArray(): 传递对象到一个数组。数组里最少包含键 'identifier' 和 'items'， 如果在对象里设置了标签，也要包含 'label'。

  • toJson(): 传递对象给一个JSON 表达。

简介
Zend_Dojo
Programmer's Reference Guide