Zend_Dojo_Data: dojo.data Envelopes

Dojo provides data abstractions for data-enabled widgets via its dojo.data component. This component provides the ability to attach a data store, provide some metadata regarding the identity field and optionally a label field, and an API for querying, sorting, and retrieving records and sets of records from the datastore.

dojo.data is often used with XmlHttpRequest to pull dynamic data from the server. The primary mechanism for this is to extend the QueryReadStore to point at a URL and specify the query information. The server side then returns data in the following JSON format:

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

Zend_Dojo_Data provides a simple interface for building such structures programmatically, interacting with them, and serializing them to an array or JSON.

Zend_Dojo_Data Usage

At its simplest, dojo.data requires that you provide the name of the identifier field in each item, and a set of items (data). You can either pass these in via the constructor, or via mutators:

Example #1 Zend_Dojo_Data initialization via constructor

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

Example #2 Zend_Dojo_Data initialization via mutators

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

You can also add a single item at a time, or append items, using addItem() and addItems().

Example #3 Appending data to Zend_Dojo_Data

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

Note: Always use an identifier!
Every dojo.data datastore requires that the identifier column be provided as metadata, including Zend_Dojo_Data. In fact, if you attempt to add items without an identifier, it will raise an exception.

Individual items may be one of the following:

Associative arrays
Objects implementing a toArray() method
Any other objects (will serialize via get_object_vars())

You can attach collections of the above items via addItems() or setItems() (overwrites all previously set items); when doing so, you may pass a single argument:

Arrays
Objects implementing the Traversable interface ,which includes the interfaces Iterator and ArrayAccess.

If you want to specify a field that will act as a label for the item, call setLabel():

Example #4 Specifying a label field in Zend_Dojo_Data

$data->setLabel('name');

Finally, you can also load a Zend_Dojo_Data item from a dojo.data JSON array, using the fromJson() method.

Example #5 Populating Zend_Dojo_Data from JSON

$data->fromJson($json);

Adding metadata to your containers

Some Dojo components require additional metadata along with the dojo.data payload. As an example, dojox.grid.Grid can pull data dynamically from a dojox.data.QueryReadStore. For pagination to work correctly, each return payload should contain a numRows key with the total number of rows that could be returned by the query. With this data, the grid knows when to continue making small requests to the server for subsets of data and when to stop making more requests (i.e., it has reached the last page of data). This technique is useful for serving large sets of data in your grids without loading the entire set at once.

Zend_Dojo_Data allows assigning metadata properties as to the object. The following illustrates usage:

// Set the "numRows" to 100
$data->setMetadata('numRows', 100);
 
// Set several items at once:
$data->setMetadata(array(
    'numRows' => 100,
    'sort'    => 'name',
));
 
// Inspect a single metadata value:
$numRows = $data->getMetadata('numRows');
 
// Inspect all metadata:
$metadata = $data->getMetadata();
 
// Remove a metadata item:
$data->clearMetadata('numRows');
 
// Remove all metadata:
$data->clearMetadata();

Advanced Use Cases

Besides acting as a serializable data container, Zend_Dojo_Data also provides the ability to manipulate and traverse the data in a variety of ways.

Zend_Dojo_Data implements the interfaces ArrayAccess, Iterator, and Countable. You can therefore use the data collection almost as if it were an array.

All items are referenced by the identifier field. Since identifiers must be unique, you can use the values of this field to pull individual records. There are two ways to do this: with the getItem() method, or via array notation.

// Using getItem():
$item = $data->getItem('foo');
 
// Or use array notation:
$item = $data['foo'];

If you know the identifier, you can use it to retrieve an item, update it, delete it, create it, or test for it:

// 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])) {
}

You can loop over all items as well. Internally, all items are stored as arrays.

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

Or even count to see how many items you have:

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

Finally, as the class implements __toString(), you can also cast it to JSON simply by echoing it or casting to string:

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

Available Methods

Besides the methods necessary for implementing the interfaces listed above, the following methods are available.

setItems($items): set multiple items at once, overwriting any items that were previously set in the object. $items should be an array or a Traversable object.
setItem($item, $id = null): set an individual item, optionally passing an explicit identifier. Overwrites the item if it is already in the collection. Valid items include associative arrays, objects implementing toArray(), or any object with public properties.
addItem($item, $id = null): add an individual item, optionally passing an explicit identifier. Will raise an exception if the item already exists in the collection. Valid items include associative arrays, objects implementing toArray(), or any object with public properties.
addItems($items): add multiple items at once, appending them to any current items. Will raise an exception if any of the new items have an identifier matching an identifier already in the collection. $items should be an array or a Traversable object.
getItems(): retrieve all items as an array of arrays.
hasItem($id): determine whether an item with the given identifier exists in the collection.
getItem($id): retrieve an item with the given identifier from the collection; the item returned will be an associative array. If no item matches, a NULL value is returned.
removeItem($id): remove an item with the given identifier from the collection.
clearItems(): remove all items from the collection.
setIdentifier($identifier): set the name of the field that represents the unique identifier for each item in the collection.
getIdentifier(): retrieve the name of the identifier field.
setLabel($label): set the name of a field to be used as a display label for an item.
getLabel(): retrieve the label field name.
toArray(): cast the object to an array. At a minimum, the array will contain the keys 'identifier', 'items', and 'label' if a label field has been set in the object.
toJson(): cast the object to a JSON representation.