Dojo: The Definitive Guide

The APIs

This section provides a summary of the data APIs. If you're just getting started, you may want to skim this section to get a feel for the capabilities the APIs and then come back after you've read the rest of the chapter, which has more concrete examples, to explore it further.

The Read API

All data stores will implement the dojo.data.api.Read API because this API provides the means of retrieving, processing, and accessing the data—clearly a prerequisite for any other operation. The complete API specification follows in Table 9-1. The next section discusses a toolkit-provided implementation: ItemFileReadStore.

Tip

The API listings that follow use descriptors like dojo.data.api.Item to convey the notion of a dojo.data item even though an item is somewhat of an abstract concept.

Table 9-1. The dojo.data.api.Read API

Name	Comment
getValue(/*dojo.data.api.Item*/item, /*String*/attribute, /*Any?*/default)	Given an item and an attribute name, returns the value for the item. A value of undefined is returned if the attribute does not exist (whereas null is returned only if null is explicitly set as the value for the attribute). An optional parameter of default can be used to return a default value if one does not exist.
getValues(/*dojo.data.api.Item*/item, /*String*/attribute)	Works just like getValue except that it allows for multivalued attributes. Always returns an array regardless of the number of items returned. You should always use getValues for multivalued attributes.
getAttributes(/*dojo.data.api.Item*/item)	Introspects the item to return an Array of String values corresponding to the item's attributes. Returns an empty Array in the event that an item has no attributes.
hasAttribute(/*dojo.data.api.Item*/item, /*String*/attribute)	Returns true if the item has the attribute.
containsValue(/*dojo.data.api.Item*/item, /*String*/attribute, /*Any*/value)	Returns true if the item has the attribute and the attribute has the value, i.e., getValues would return true.
isItem(/*Any*/item)	Returns true if the parameter is an item and came from the specified store. Returns false if item is a literal or if the item came from any other store. (This call is also especially handy for situations when local variable references to items can become stale, which is quite ordinary for stores that implement the Write API.)
isItemLoaded(/*Any*/item)	Returns true if the item is loaded and available locally.
loadItem(/*Object*/args)	Loads an item to the effect that a subsequent call to isItemLoaded would return true. The args object provides the following keys: item An Object providing criteria for the item that is to be loaded (possibly an identifier or subset of identifying data). onItem(/*dojo.data.api.Item*/item) A callback to run when the item is loaded; the loaded item is passed as a parameter. onError(/*Object*/error) A callback to run when an error occurs loading the item; the error Object is passed as a parameter. scope An Object providing the context for callback functions.
fetch(/*Object*/args)	Executes a given query and provides an assortment of asynchronous callbacks for handling events related to the query execution. Returns a dojo.data.api.Request Object, whose primary purpose is supplying an abort( ) method that may be used for aborting the fetch. The arguments may include the following nine options, which should be honored by all implementations: query A String or Object providing the query criteria (similar to SELECT in SQL). Note that the query syntax for each store is implementation-dependent. queryOptions An Object containing additional options for the query. All stores should attempt to honor the ignoreCase (Boolean, default false ) parameter, which performs a case-insensitive search and the deep (Boolean, default false ) parameter can trigger a query of all items and child items instead of only items at the root level in the store. onBegin (/*Integer*/size, /*dojo.data.api.Request*/request) Called before the first onItem callback. size indicates the total number of items and request is the original request for the query. If size is unknown, it will be -1. size may not be the total number of items returned since it may have been pared down with start and count. onComplete (/*Array*/items, /*dojo.data.api.Request*/request) Called just after the last onItem callback. If no onItem callback is present, items will be an Array of all items that matched the query; otherwise, it will be null.Request, the original request Object. onError(/*Object*/error, /*dojo.data.api.Request*/request) Called if there is an error when executing the query. error contains the error information and request contains the original request Object. onItem(/*dojo.data.api.Item*/item, /*dojo.data.api.Request*/request) Called for each item that is returned with each item available as item; request contains the original request Object. scope (Object) If provided, executes all of the callback function in this context; otherwise, executes them in the global context. start (Integer) Provides a starting offset for the returned results (similar to OFFSET in an SQL query). count (Integer) Provides a limit for the items to be returned (similar to LIMIT in a SQL query). sort (Array) An Array of JavaScript Objects providing sort criteria for each attribute. Each Object is applied sequentially and must present an attribute key identifying the attribute name and a descending key identifying the sort order.
getFeatures( )	Returns an Object containing key/value pairs that specifies what dojo.data APIs it implements. For example, any API implementing dojo.data.api.Read would necessarily return {'dojo.data.api.Read' : true} for a data store that is read-only.
close(/*dojo.data.api.Request*/request)	Used to close out any information associated with a particular request, which may involve clearing caches, closing connections, etc. The request parameter is expected to be the Object returned from a fetch. For some stores, this may be a no-op.
getLabel(/*dojo.data.api.Item*/item)	Used to return a human-readable label for an item that is generally some kind of identifying description. The label may very well be some combination of attributes.
getLabelAttributes(/*dojo.data.api.Item*/item)	Used to provide an Array of attributes that will generate an item's label. Useful for assisting UI developers in knowing what attributes are useful for display purposes so that redundant information can be hidden when a display includes an item label.

The Identity API

The Identity API, shown in Table 9-2, builds on the Read API to provide a few additional calls for fetching items based upon their identity. Note that the Read API has no stipulations whatsoever that items be unique, and there are certainly use cases where the notion of an identity may not be pertinent; hence the separation between the two of them. With respect to databases, you might think of the Identity API, loosely, as providing a kind of primary key for each item that records can be identified with. It is often the case that data-enabled widgets require the Identity API, particularly when providing Write functionality. (The Write API is coming up next.)

Table 9-2. The dojo.data.api.Identity API

Name	Comment
getFeatures( )	See dojo.data.api.Read. Returns: { 'dojo.data.api.Read' : true, 'dojo.data.api.Identity : true }
getIdentity(/*dojo.data.api.Item*/item)	Returns a unique identifier for the item, which will be a String or an Object that has a toString method.
getIdentityAttributes (/*dojo.data.api.Item*/item)	Returns an Array of attribute names that are used to generate the identity. Most of the time, this is a single attribute that expressly provides a unique identifier, but it could be more than one depending on the specifics of the actual data source. This function is often used to optionally hide attributes comprising the identity for display purposes.
fetchItemByIdentity(/*Object*/args)	Uses the identity of an item to retrieve it; conforming implementations should return null if no such item exists. The keyword args may include the following: identity A String or Object with a toString function that is uses to provide the reference for the desired item. onError(/*Object*/error) Called if there is an error when executing the query. error contains the error information. onItem(/*dojo.data.api.Item*/item) Called for each item that is returned with each item available as item. scope (Object) If provided, executes all of the callback function in this context; otherwise, executes them in the global context.

The Write API

The Write API, shown in Table 9-3, extends the Read API to include facilities for creating, updating, and deleting items, which necessarily entails managing additional issues such as whether items are dirty —out of sync between the in-memory copy and the server—and handling I/O such as save operations.

Table 9-3. The dojo.data.api.Write API

Name	Comment
getFeatures	See dojo.data.api.Read. Returns: { 'dojo.data.api.Read' : true, 'dojo.data.api.Write : true }
newItem(/*Object?*/args, /*Object?*/parentItem)	Returns a newly created item, setting the attributes based on the args Object provided, where generally the key/value pairs in args map directory attributes and attribute values. For stores that support hierarchical item creation, parentItem provides information identifying the parent of the new item and the attribute of the parent that the new item should be assigned (which generally implies that the attribute is multivalued and the new item is appended). Returns the newly created item.
deleteItem(/*dojo.data.api.Item*/item)	Deletes and item from the store. Returns a Boolean value indicating success.
setValue(/*dojo.data.api.Item*/item, /*String*/attribute, /*Any*/value)	Sets an attribute on an item, replacing any previous values. Returns a Boolean value indicating success.
setValues(/*dojo.data.api.Item*/item, /*String*/attribute, /*Array*/values)	Sets values for an attribute, replacing any previous values. Returns a Boolean value indicating success.
unsetAttribute(/*dojo.data.api.Item*/item, /*String*/attribute)	Effectively removes an attribute by deleting all values for it. Returns a Boolean value indicating success.
save(/*Object*/args)	Saves all local changes in memory, and output is passed to a callback function provided in args, which is in the following form: onError(/*Object*/error) Called if there is an error; error contains the error information. onComplete( ) Called to indicate success, usually with no parameters. scope (Object) If provided, executes all of the callback functions in this context; otherwise executes them in the global context. A _saveCustom extension point is available, and if overridden, provides an opportunity to pass the data set back to the server.
revert( )	Discards any local changes. Returns a Boolean value indicating success.
isDirty(/*dojo.data.api.Item?*/)	Returns a Boolean value indicating if a specific item has been modified since the last save operation. If no parameter is provided, returns a Boolean value indicating if any item has been modified.

The Notification API

The Notification API, shown in Table 9-4, is built upon the Read and complements the Write API by providing a unified interface for responding to the typical create, update, and delete events. The Notification API is particularly useful for ensuring visuals properly reflect the state of a store, which may be changing or refreshed via Read and Write operations. (The dijit.Tree and dojox.grid.Grid widgets are great cases in point.)

Table 9-4. The dojo.data.api.Notification API

Name	Comment
getFeatures	See dojo.data.api.Read. Returns: { 'dojo.data.api.Read' : true, 'dojo.data.api.Notification: true }
onSet(/*dojo.data.api.Item*/item, /*String*/attribute, /*Object|Array*/old, /*Object|Array*/new)	Called any time an item is modified via setValue, setValues, or unsetAttribute, providing means of monitoring actions on items in the store. The parameters are self-descriptive and provide the item being modified, the attribute being modified, and the old and new value or values, respectively.
onNew(/*dojo.data.api.Item*/item, /*Object?*/parentItem)	Called when a new item is created in the store where item is what was just created; parentItem is not passed if the created item is placed in the root level. parentItem, however, is provided if the item is not a root-level item. (Note that an onSet notification is not generated stating that the parentItem 's attributes have been modified because it is implied and parentItem gives access to that information.)
onDelete(/*dojo.data.api.Item*/item)	Called when an item is deleted from the store where item is what was just deleted.