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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.dojo.data">
   4     <title>Zend_Dojo_Data: dojo.data Envelopes</title>
   5
   6     <para>
   7         Dojo provides data abstractions for data-enabled widgets via its
   8         <command>dojo.data</command> component. This component provides the ability to attach a
   9         data store, provide some metadata regarding the identity field and
  10         optionally a label field, and an <acronym>API</acronym> for querying, sorting, and
  11         retrieving records and sets of records from the datastore.
  12     </para>
  13
  14     <para>
  15         <command>dojo.data</command> is often used with XmlHttpRequest to pull dynamic data from
  16         the server. The primary mechanism for this is to extend the
  17         QueryReadStore to point at a <acronym>URL</acronym> and specify the query information. The
  18         server side then returns data in the following <acronym>JSON</acronym> format:
  19     </para>
  20
  21     <programlisting language="javascript"><![CDATA[
  22 {
  23     identifier: '<name>',
  24     <label: '<label>',>
  25     items: [
  26         { name: '...', label: '...', someKey: '...' },
  27         ...
  28     ]
  29 }
  30 ]]></programlisting>
  31
  32     <para>
  33         <classname>Zend_Dojo_Data</classname> provides a simple interface for building
  34         such structures programmatically, interacting with them, and serializing
  35         them to an array or <acronym>JSON</acronym>.
  36     </para>
  37
  38     <sect2 id="zend.dojo.data.usage">
  39         <title>Zend_Dojo_Data Usage</title>
  40
  41         <para>
  42             At its simplest, <command>dojo.data</command> requires that you provide the name of the
  43             identifier field in each item, and a set of items (data). You
  44             can either pass these in via the constructor, or via mutators:
  45         </para>
  46
  47         <example id="zend.dojo.data.usage.constructor">
  48             <title>Zend_Dojo_Data initialization via constructor</title>
  49
  50             <programlisting language="php"><![CDATA[
  51 $data = new Zend_Dojo_Data('id', $items);
  52 ]]></programlisting>
  53         </example>
  54
  55         <example id="zend.dojo.data.usage.mutators">
  56             <title>Zend_Dojo_Data initialization via mutators</title>
  57
  58             <programlisting language="php"><![CDATA[
  59 $data = new Zend_Dojo_Data();
  60 $data->setIdentifier('id')
  61      ->addItems($items);
  62 ]]></programlisting>
  63         </example>
  64
  65         <para>
  66             You can also add a single item at a time, or append items, using
  67             <methodname>addItem()</methodname> and <methodname>addItems()</methodname>.
  68         </para>
  69
  70         <example id="zend.dojo.data.usage.append">
  71             <title>Appending data to Zend_Dojo_Data</title>
  72
  73             <programlisting language="php"><![CDATA[
  74 $data = new Zend_Dojo_Data($identifier, $items);
  75 $data->addItem($someItem);
  76
  77 $data->addItems($someMoreItems);
  78 ]]></programlisting>
  79         </example>
  80
  81         <note>
  82             <title>Always use an identifier!</title>
  83
  84             <para>
  85                 Every <command>dojo.data</command> datastore requires that the identifier column
  86                 be provided as metadata, including <classname>Zend_Dojo_Data</classname>. In fact,
  87                 if you attempt to add items without an identifier, it will raise an exception.
  88             </para>
  89         </note>
  90
  91         <para>
  92             Individual items may be one of the following:
  93         </para>
  94
  95         <itemizedlist>
  96             <listitem><para>Associative arrays</para></listitem>
  97
  98             <listitem>
  99                 <para>Objects implementing a <methodname>toArray()</methodname> method</para>
 100             </listitem>
 101
 102             <listitem>
 103                 <para>
 104                     Any other objects (will serialize via
 105                     <methodname>get_object_vars()</methodname>)
 106                 </para>
 107             </listitem>
 108         </itemizedlist>
 109
 110         <para>
 111             You can attach collections of the above items via
 112             <methodname>addItems()</methodname> or <methodname>setItems()</methodname> (overwrites
 113             all previously set items); when doing so, you may pass a single argument:
 114         </para>
 115
 116         <itemizedlist>
 117             <listitem><para>Arrays</para></listitem>
 118
 119             <listitem>
 120                 <para>
 121                     Objects implementing the <classname>Traversable</classname> interface
 122                     ,which includes the interfaces <classname>Iterator</classname> and
 123                     <classname>ArrayAccess</classname>.
 124                 </para>
 125             </listitem>
 126         </itemizedlist>
 127
 128         <para>
 129             If you want to specify a field that will act as a label for the
 130             item, call <methodname>setLabel()</methodname>:
 131         </para>
 132
 133         <example id="zend.dojo.data.usage.label">
 134             <title>Specifying a label field in Zend_Dojo_Data</title>
 135
 136             <programlisting language="php"><![CDATA[
 137 $data->setLabel('name');
 138 ]]></programlisting>
 139         </example>
 140
 141         <para>
 142             Finally, you can also load a <classname>Zend_Dojo_Data</classname> item from a
 143             <command>dojo.data</command> <acronym>JSON</acronym> array, using the
 144             <methodname>fromJson()</methodname> method.
 145         </para>
 146
 147         <example id="zend.dojo.data.usage.populate">
 148             <title>Populating Zend_Dojo_Data from JSON</title>
 149
 150             <programlisting language="php"><![CDATA[
 151 $data->fromJson($json);
 152 ]]></programlisting>
 153         </example>
 154     </sect2>
 155
 156     <sect2 id="zend.dojo.data.metadata">
 157         <title>Adding metadata to your containers</title>
 158
 159         <para>
 160             Some Dojo components require additional metadata along with
 161             the <command>dojo.data</command> payload. As an example,
 162             <command>dojox.grid.Grid</command> can pull data dynamically from a
 163             <command>dojox.data.QueryReadStore</command>. For pagination to work
 164             correctly, each return payload should contain a <property>numRows</property>
 165             key with the total number of rows that could be returned by the
 166             query. With this data, the grid knows when to continue making small
 167             requests to the server for subsets of data and when to stop
 168             making more requests (i.e., it has reached the last page of data).
 169             This technique is useful for serving large sets of data in your
 170             grids without loading the entire set at once.
 171         </para>
 172
 173         <para>
 174             <classname>Zend_Dojo_Data</classname> allows assigning metadata properties as
 175             to the object. The following illustrates usage:
 176         </para>
 177
 178         <programlisting language="php"><![CDATA[
 179 // Set the "numRows" to 100
 180 $data->setMetadata('numRows', 100);
 181
 182 // Set several items at once:
 183 $data->setMetadata(array(
 184     'numRows' => 100,
 185     'sort'    => 'name',
 186 ));
 187
 188 // Inspect a single metadata value:
 189 $numRows = $data->getMetadata('numRows');
 190
 191 // Inspect all metadata:
 192 $metadata = $data->getMetadata();
 193
 194 // Remove a metadata item:
 195 $data->clearMetadata('numRows');
 196
 197 // Remove all metadata:
 198 $data->clearMetadata();
 199 ]]></programlisting>
 200     </sect2>
 201
 202     <sect2 id="zend.dojo.data.advanced">
 203         <title>Advanced Use Cases</title>
 204
 205         <para>
 206             Besides acting as a serializable data container,
 207             <classname>Zend_Dojo_Data</classname> also provides the ability to manipulate
 208             and traverse the data in a variety of ways.
 209         </para>
 210
 211         <para>
 212             <classname>Zend_Dojo_Data</classname> implements the interfaces
 213             <classname>ArrayAccess</classname>, <classname>Iterator</classname>, and
 214             <classname>Countable</classname>. You can therefore use the data
 215             collection almost as if it were an array.
 216         </para>
 217
 218         <para>
 219             All items are referenced by the identifier field. Since identifiers
 220             must be unique, you can use the values of this field to pull
 221             individual records. There are two ways to do this: with the
 222             <methodname>getItem()</methodname> method, or via array notation.
 223         </para>
 224
 225         <programlisting language="php"><![CDATA[
 226 // Using getItem():
 227 $item = $data->getItem('foo');
 228
 229 // Or use array notation:
 230 $item = $data['foo'];
 231 ]]></programlisting>
 232
 233         <para>
 234             If you know the identifier, you can use it to retrieve an item,
 235             update it, delete it, create it, or test for it:
 236         </para>
 237
 238         <programlisting language="php"><![CDATA[
 239 // Update or create an item:
 240 $data['foo'] = array('title' => 'Foo', 'email' => 'foo@foo.com');
 241
 242 // Delete an item:
 243 unset($data['foo']);
 244
 245 // Test for an item:
 246 if (isset($data[foo])) {
 247 }
 248 ]]></programlisting>
 249
 250         <para>
 251             You can loop over all items as well. Internally, all items are
 252             stored as arrays.
 253         </para>
 254
 255         <programlisting language="php"><![CDATA[
 256 foreach ($data as $item) {
 257     echo $item['title'] . ': ' . $item['description'] . "\n";
 258 }
 259 ]]></programlisting>
 260
 261         <para>
 262             Or even count to see how many items you have:
 263         </para>
 264
 265         <programlisting language="php"><![CDATA[
 266 echo count($data), " items found!";
 267 ]]></programlisting>
 268
 269         <para>
 270             Finally, as the class implements <methodname>__toString()</methodname>, you can
 271             also cast it to <acronym>JSON</acronym> simply by echoing it or casting to string:
 272         </para>
 273
 274         <programlisting language="php"><![CDATA[
 275 echo $data; // echo as JSON string
 276
 277 $json = (string) $data; // cast to string == cast to JSON
 278 ]]></programlisting>
 279
 280         <sect3 id="zend.dojo.data.advanced.methods">
 281             <title>Available Methods</title>
 282
 283             <para>
 284                 Besides the methods necessary for implementing the interfaces
 285                 listed above, the following methods are available.
 286             </para>
 287
 288             <itemizedlist>
 289                 <listitem>
 290                     <para>
 291                         <methodname>setItems($items)</methodname>: set multiple items at once,
 292                         overwriting any items that were previously set in the
 293                         object. <varname>$items</varname> should be an array or a
 294                         <classname>Traversable</classname> object.
 295                     </para>
 296                 </listitem>
 297
 298                 <listitem>
 299                     <para>
 300                         <methodname>setItem($item, $id = null)</methodname>: set an individual
 301                         item, optionally passing an explicit identifier. Overwrites
 302                         the item if it is already in the collection. Valid items
 303                         include associative arrays, objects implementing
 304                         <methodname>toArray()</methodname>, or any object with public properties.
 305                     </para>
 306                 </listitem>
 307
 308                 <listitem>
 309                     <para>
 310                         <methodname>addItem($item, $id = null)</methodname>: add an individual
 311                         item, optionally passing an explicit identifier. Will raise
 312                         an exception if the item already exists in the collection.
 313                         Valid items include associative arrays, objects implementing
 314                         <methodname>toArray()</methodname>, or any object with public properties.
 315                     </para>
 316                 </listitem>
 317
 318                 <listitem>
 319                     <para>
 320                         <methodname>addItems($items)</methodname>: add multiple items at once,
 321                         appending them to any current items. Will raise an exception
 322                         if any of the new items have an identifier matching an
 323                         identifier already in the collection. <varname>$items</varname>
 324                         should be an array or a <classname>Traversable</classname> object.
 325                     </para>
 326                 </listitem>
 327
 328                 <listitem>
 329                     <para>
 330                         <methodname>getItems()</methodname>: retrieve all items as an array of
 331                         arrays.
 332                     </para>
 333                 </listitem>
 334
 335                 <listitem>
 336                     <para>
 337                         <methodname>hasItem($id)</methodname>: determine whether an item with
 338                         the given identifier exists in the collection.
 339                     </para>
 340                 </listitem>
 341
 342                 <listitem>
 343                     <para>
 344                         <methodname>getItem($id)</methodname>: retrieve an item with the given
 345                         identifier from the collection; the item returned will be an associative
 346                         array. If no item matches, a <constant>NULL</constant> value is returned.
 347                     </para>
 348                 </listitem>
 349
 350                 <listitem>
 351                     <para>
 352                         <methodname>removeItem($id)</methodname>: remove an item with the given
 353                         identifier from the collection.
 354                     </para>
 355                 </listitem>
 356
 357                 <listitem>
 358                     <para>
 359                         <methodname>clearItems()</methodname>: remove all items from the collection.
 360                     </para>
 361                 </listitem>
 362
 363                 <listitem>
 364                     <para>
 365                         <methodname>setIdentifier($identifier)</methodname>: set the name of the
 366                         field that represents the unique identifier for each item in
 367                         the collection.
 368                     </para>
 369                 </listitem>
 370
 371                 <listitem>
 372                     <para>
 373                         <methodname>getIdentifier()</methodname>: retrieve the name of the
 374                         identifier field.
 375                     </para>
 376                 </listitem>
 377
 378                 <listitem>
 379                     <para>
 380                         <methodname>setLabel($label)</methodname>: set the name of a field
 381                         to be used as a display label for an item.
 382                     </para>
 383                 </listitem>
 384
 385                 <listitem>
 386                     <para>
 387                         <methodname>getLabel()</methodname>: retrieve the label field name.
 388                     </para>
 389                 </listitem>
 390
 391                 <listitem>
 392                     <para>
 393                         <methodname>toArray()</methodname>: cast the object to an array. At a
 394                         minimum, the array will contain the keys 'identifier',
 395                         'items', and 'label' if a label field has been set in the object.
 396                     </para>
 397                 </listitem>
 398
 399                 <listitem>
 400                     <para>
 401                         <methodname>toJson()</methodname>: cast the object to a
 402                         <acronym>JSON</acronym> representation.
 403                     </para>
 404                 </listitem>
 405             </itemizedlist>
 406         </sect3>
 407     </sect2>
 408 </sect1>
 409 <!--
 410 vim:se ts=4 sw=4 et:
 411 -->
 412