Zend Framework: Zend_Dojo_Data - dojo.data Envelope Component Proposal

Proposed Component Name	Zend_Dojo_Data - dojo.data Envelope
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Dojo_Data - dojo.data Envelope
Proposers	Matthew Weier O'Phinney
Zend Liaison	TBD
Revision	1.0 - 19 June 2008: Initial Draft. (wiki revision: 4)

Dojo and other Javascript toolkits are often choosing to abstract data access for their widgets in order to allow switching data sources. Dojo does this via a variety of data stores, which consume data in the dojo.data format. dojo.data is a simple format for wrapping data sets and providing basic metadata about them:

{
    identifier: <identifier attribute name>,
    [ label: <label attribute name>, ]
    items: [
        {
            <identifier attribute>: <identier>,
            [<label attribute>: <label>,]
            <attribute1>: <value1>,
            <attribute2>: <value2>,
            ...
        },
        ...
    ]
}

To dissect this in PHP terms, we have a structure like the following:

array(
    'identifier' => <identifier attribute name>,
    [ 'label'    => <label attribute name>,]
    'items'      => array(
        array(
            '<identifier attribute>' => <identifier>,
            ['<label attribute>'     => <label>,]
            '<attribute1>            => <value1>,
            '<attribute2>            => <value2>,
            ...
        ),
        ...
    )
)

When using Zend Framework, however, you will rarely have a data construct that matches this. This proposal would provide a component that could consume a variety of data constructs to utilize as dojo.data items, and mutators for specifying the identifier and optional label attributes of the records in the data store. Additionally, accessors would allow for retrieving the information.

This component could then be used as a backend data store for use with Dojo's QueryReadStore. This would require serialization of the data and metadata stored in the object to JSON (which is consumed natively by QueryReadStore). While dojo supports other data stores, these data stores utilize special formats already and will not require usage of this component. As examples, the CsvStore, OpmlStore, and AtomStore all leverage the self-documenting capabilities of those formats in order to provide introspection of the returned data. The only other format of much interest to ZF developers might be the XmlStore. This store allows parsing of arbitrary XML collections. However, it's a read-write store, and would be best used with public, editable XML documents.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

MUST allow attaching arbitrary data sets:
- Zend_Db_Table_Rowset_Abstract
- Arrays
- Service results
MUST require specifying identifier attribute name
MUST require specifying label attribute name
MUST provide accessors and mutators to data items
MUST serialize to JSON
- SHOULD implement string serialization proxying to JSON serialization
MUST allow access to metadata and data within PHP

4. Dependencies on Other Framework Components

HARD depedencies
- Zend_Exception
SOFT dependencies
- Zend_Db_Table_Rowset_Abstract
- Potentially Zend_Service consumables

5. Theory of Operation

A developer will attach a data set and specify an identifier when instantiating Zend_Dojo_Data; alternately, these can be specified via mutators. Serialization will happen on demand via a toJson() method.

6. Milestones / Tasks

Milestone 1: [DONE] Prepare this proposal
Milestone 2: Prepare test suite and API
Milestone 3: Complete initial implementation
Milestone 4: Write documentation

7. Class Index

Zend_Dojo_Data
Zend_Dojo_Data_Exception

8. Use Cases

UC-01

Specifying a Zend_Db_Table_Rowset

$rows = $table->fetchAll($query);

$data = new Zend_Dojo_Data($rows, 'id');
echo $data;

UC-02

Specifying a service consumable

$feed = $gdata->getFeed($query);

$data = new Zend_Dojo_Data($feed, 'eventId');
echo $data;

UC-03

Specifying an array and using accessors

$rows = $db->fetchAll($query);

$data = new Zend_Dojo_Data();
$data->setItems($rows)
     ->setIdentifier('id')
     ->setLabel('title');

echo $data;

9. Class Skeletons

class Zend_Dojo_Data implements ArrayAccess,Iterator,Countable
{
    public function __construct($items = null, $identifier = null, $label = null)
    {
        if (null !== $items) {
            $this->setItems($items);
        }
        if (null !== $identifier) {
            $this->setIdentifier($identifier);
        }
        if (null !== $label) {
            $this->setLabel($label);
        }
    }

    public function setItems($items);
    public function setItem($item, $identifier = null);
    public function addItem($item, $identifier = null);
    public function addItems($items);
    public function getItems();
    public function getItem($identifier);
    public function removeItem($identifier);
    public function clearItems();

    public function setIdentifier($identifier);
    public function getIdentifier();

    public function setLabel($label);
    public function getLabel();

    public function toJson();
    public function __toString();

    // interfaces
    public function offsetExists($offset);
    public function offsetGet($offset);
    public function offsetSet($offset, $value);
    public function offsetUnset($offset);

    public function current();
    public function key();
    public function next();
    public function rewind();
    public function valid();

    public function count();
}

Page Operations

Browse Space

Zend_Dojo_Data - Matthew Weier O'Phinney

Labels