repo_zf1Php7/documentation/manual/en/module_specs/Zend_Dojo-Data.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.dojo.data">
    <title>Zend_Dojo_Data: dojo.data Envelopes</title>

    <para>
        Dojo provides data abstraction 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.
    </para>

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

    <programlisting language="javascript"><![CDATA[
{
    identifier: '<name>',
    <label: '<label>',>
    items: [
        { name: '...', label: '...', someKey: '...' },
        ...
    ]
}
]]></programlisting>

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

    <sect2 id="zend.dojo.data.usage">
        <title>Zend_Dojo_Data Usage</title>

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

        <example id="zend.dojo.data.usage.constructor">
            <title>Zend_Dojo_Data initialization via constructor</title>

            <programlisting language="php"><![CDATA[
$data = new Zend_Dojo_Data('id', $items);
]]></programlisting>
        </example>

        <example id="zend.dojo.data.usage.mutators">
            <title>Zend_Dojo_Data initialization via mutators</title>

            <programlisting language="php"><![CDATA[
$data = new Zend_Dojo_Data();
$data->setIdentifier('id')
     ->addItems($items);
]]></programlisting>
        </example>

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

        <example id="zend.dojo.data.usage.append">
            <title>Appending data to Zend_Dojo_Data</title>

            <programlisting language="php"><![CDATA[
$data = new Zend_Dojo_Data($identifier, $items);
$data->addItem($someItem);

$data->addItems($someMoreItems);
]]></programlisting>
        </example>

        <note>
            <title>Always use an identifier!</title>

            <para>
                Every dojo.data data store requires that the identifier column
                be provided as metadata, including <classname>Zend_Dojo_Data</classname>. In fact,
                if you attempt to add items without an identifier, it will raise an exception.
            </para>
        </note>

        <para>
            Individual items may be one of the following:
        </para>

        <itemizedlist>
            <listitem><para>
                Associative arrays
            </para></listitem>

            <listitem><para>
                Objects implementing a <code>toArray()</code> method
            </para></listitem>

            <listitem><para>
                Any other objects (will serialize via get_object_vars())
            </para></listitem>
        </itemizedlist>

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

        <itemizedlist>
            <listitem><para>
                Arrays
            </para></listitem>

            <listitem><para>
                Objects implementing the <code>Traversable</code> interface
                ,which includes the interfaces <code>Iterator</code> and
                <code>ArrayAccess</code>.
            </para></listitem>
        </itemizedlist>

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

        <example id="zend.dojo.data.usage.label">
            <title>Specifying a label field in Zend_Dojo_Data</title>

            <programlisting language="php"><![CDATA[
$data->setLabel('name');
]]></programlisting>
        </example>

        <para>
            Finally, you can also load a <classname>Zend_Dojo_Data</classname> item from a
            dojo.data JSON array, using the <code>fromJson()</code> method.
        </para>

        <example id="zend.dojo.data.usage.populate">
            <title>Populating Zend_Dojo_Data from JSON</title>

            <programlisting language="php"><![CDATA[
$data->fromJson($json);
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.dojo.data.metadata">
        <title>Adding metadata to your containers</title>

        <para>
            Some Dojo components require additional metadata along with
            the dojo.data payload. As an example, <code>dojox.grid.Grid</code>
            can pull data dynamically from a
            <code>dojox.data.QueryReadStore</code>. For pagination to work
            correctly, each return payload should contain a <code>numRows</code>
            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.
        </para>

        <para>
            <classname>Zend_Dojo_Data</classname> allows assigning metadata properties as
            to the object. The following illustrates usage:
        </para>

        <programlisting language="php"><![CDATA[
// 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();
]]></programlisting>
    </sect2>

    <sect2 id="zend.dojo.data.advanced">
        <title>Advanced Use Cases</title>

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

        <para>
            <classname>Zend_Dojo_Data</classname> implements the interfaces
            <code>ArrayAccess</code>, <code>Iterator</code>, and
            <code>Countable</code>. You can therefore use the data
            collection almost as if it were an array.
        </para>

        <para>
            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
            <code>getItem()</code> method, or via array notation.
        </para>

        <programlisting language="php"><![CDATA[
// Using getItem():
$item = $data->getItem('foo');

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

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

        <programlisting language="php"><![CDATA[
// 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])) {
}
]]></programlisting>

        <para>
            You can loop over all items as well. Internally, all items are
            stored as arrays.
        </para>

        <programlisting language="php"><![CDATA[
foreach ($data as $item) {
    echo $item['title'] . ': ' . $item['description'] . "\n";
}
]]></programlisting>

        <para>
            Or even count to see how many items you have:
        </para>

        <programlisting language="php"><![CDATA[
echo count($data), " items found!";
]]></programlisting>

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

        <programlisting language="php"><![CDATA[
echo $data; // echo as JSON string

$json = (string) $data; // cast to string == cast to JSON
]]></programlisting>

        <sect3 id="zend.dojo.data.advanced.methods">
            <title>Available Methods</title>

            <para>
                Besides the methods necessary for implementing the interfaces
                listed above, the following methods are available.
            </para>

            <itemizedlist>
                <listitem><para>
                    <code>setItems($items)</code>: set multiple items at once,
                    overwriting any items that were previously set in the
                    object. <code>$items</code> should be an array or a
                    <code>Traversable</code> object.
                </para></listitem>

                <listitem><para>
                    <code>setItem($item, $id = null)</code>: 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
                    <code>toArray()</code>, or any object with public
                    properties.
                </para></listitem>

                <listitem><para>
                    <code>addItem($item, $id = null)</code>: 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
                    <code>toArray()</code>, or any object with public
                    properties.
                </para></listitem>

                <listitem><para>
                    <code>addItems($items)</code>: 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. <code>$items</code>
                    should be an array or a <code>Traversable</code> object.
                </para></listitem>

                <listitem><para>
                    <code>getItems()</code>: retrieve all items as an array of
                    arrays.
                </para></listitem>

                <listitem><para>
                    <code>hasItem($id)</code>: determine whether an item with
                    the given identifier exists in the collection.
                </para></listitem>

                <listitem><para>
                    <code>getItem($id)</code>: 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.
                </para></listitem>

                <listitem><para>
                    <code>removeItem($id)</code>: remove an item with the given
                    identifier from the collection.
                </para></listitem>

                <listitem><para>
                    <code>clearItems()</code>: remove all items from the
                    collection.
                </para></listitem>

                <listitem><para>
                    <code>setIdentifier($identifier)</code>: set the name of the
                    field that represents the unique identifier for each item in
                    the collection.
                </para></listitem>

                <listitem><para>
                    <code>getIdentifier()</code>: retrieve the name of the
                    identifier field.
                </para></listitem>

                <listitem><para>
                    <code>setLabel($label)</code>: set the name of a field
                    to be used as a display label for an item.
                </para></listitem>

                <listitem><para>
                    <code>getLabel()</code>: retrieve the label field name.
                </para></listitem>

                <listitem><para>
                    <code>toArray()</code>: 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.
                </para></listitem>

                <listitem><para>
                    <code>toJson()</code>: cast the object to a JSON
                    representation.
                </para></listitem>
            </itemizedlist>
        </sect3>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->