15.2. 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。

15.2.1. Zend_Dojo_Data 用法

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

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

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

            

例 15.2. 通过 mutators 初始化 Zend_Dojo_Data

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

            

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

例 15.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接口的对象(包括 IteratorArrayAccess 接口)。

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

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

$data->setLabel('name');

            

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

例 15.5.  从 JSON 组装 Zend_Dojo_Data

$data->fromJson($json);

            

15.2.2. 高级用例

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

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

所有的条目通过标识符字段来引用。因为表示符必须是独一无二的,你可用它的值来取出每个记录。 有两个方法可以做这个:通过 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' => '[email protected]');

// 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

        

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