12.2. Zend_Dojo_Data: dojo.data Envelopes

发布于 2015-10-07 09:46:23 | 119 次阅读 | 评论: 0 | 来源: 网络整理

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

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

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

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

12.2.1. Zend_Dojo_Data 用法

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

例 12.1. 通过构造函数初始化 Zend_Dojo_Data

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

例 12.2. 通过 mutators 初始化 Zend_Dojo_Data

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

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

例 12.3. 追加数据到 Zend_Dojo_Data

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

$data->addItems($someMoreItems);

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

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

联合数组
实现 toArray() 方法的对象
任何其它对象（将通过 get_object_vars() 系列化）

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

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

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

例 12.4. 在 Zend_Dojo_Data 里指定一个标签字段

$data->setLabel('name');

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

例 12.5. 从 JSON 组装 Zend_Dojo_Data

$data->fromJson($json);

12.2.2. 高级用例

除了可以作为可系列化的数据容器，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

12.2.2.1. 可用的方法

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

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 表达。

12.2. Zend_Dojo_Data: dojo.data Envelopes