data/api/Identity

An instance of a request for the store to use to identify what to close out. If no request is passed, then the store should clear all internal caches (if any) and close out all 'open' connections. It does not render the store unusable from there on, it merely cleans out any current data and resets the store to initial state.

The item to access values on.

The attribute to access represented as a string.

The value to match as a value for the attribute.

The keywordArgs parameter may either be an instance of conforming to dojo/data/api/Request or may be a simple anonymous object that may contain any of the following:

{
    query: query-object or query-string,
    queryOptions: object,
    onBegin: Function,
    onItem: Function,
    onComplete: Function,
    onError: Function,
    scope: object,
    start: int
    count: int
    sort: array
}

All implementations should accept keywordArgs objects with any of

the 9 standard properties: query, onBegin, onItem, onComplete, onError scope, sort, start, and count. Some implementations may accept additional properties in the keywordArgs object as valid parameters, such as {includeOutliers:true}.

The query parameter

The query may be optional in some data store implementations. The dojo/data/api/Read API does not specify the syntax or semantics of the query itself -- each different data store implementation may have its own notion of what a query should look like. However, as of dojo 0.9, 1.0, and 1.1, all the provided datastores in dojo.data and dojox.data support an object structure query, where the object is a set of name/value parameters such as { attrFoo: valueBar, attrFoo1: valueBar1}. Most of the dijit widgets, such as ComboBox assume this to be the case when working with a datastore when they dynamically update the query. Therefore, for maximum compatibility with dijit widgets the recommended query parameter is a key/value object. That does not mean that the the datastore may not take alternative query forms, such as a simple string, a Date, a number, or a mix of such. Ultimately, The dojo/data/api/Read API is agnostic about what the query format.

Further note: In general for query objects that accept strings as attribute value matches, the store should also support basic filtering capability, such as (match any character) and ? (match single character). An example query that is a query object would be like: { attrFoo: "value"}. Which generally means match all items where they have an attribute named attrFoo, with a value that starts with 'value'.

The queryOptions parameter

The queryOptions parameter is an optional parameter used to specify options that may modify the query in some fashion, such as doing a case insensitive search, or doing a deep search where all items in a hierarchical representation of data are scanned instead of just the root items. It currently defines two options that all datastores should attempt to honor if possible:

{
    ignoreCase: boolean, // Whether or not the query should match case sensitively or not.  Default behaviour is false.
    deep: boolean   // Whether or not a fetch should do a deep search of items and all child
                    // items instead of just root-level items in a datastore.  Default is false.
}

The onBegin parameter.

function(size, request); If an onBegin callback function is provided, the callback function will be called just once, before the first onItem callback is called. The onBegin callback function will be passed two arguments, the the total number of items identified and the Request object. If the total number is unknown, then size will be -1. Note that size is not necessarily the size of the collection of items returned from the query, as the request may have specified to return only a subset of the total set of items through the use of the start and count parameters.

The onItem parameter.

function(item, request);

If an onItem callback function is provided, the callback function will be called as each item in the result is received. The callback function will be passed two arguments: the item itself, and the Request object.

The onComplete parameter.

function(items, request);

If an onComplete callback function is provided, the callback function will be called just once, after the last onItem callback is called. Note that if the onItem callback is not present, then onComplete will be passed an array containing all items which matched the query and the request object. If the onItem callback is present, then onComplete is called as: onComplete(null, request).

The onError parameter.

function(errorData, request);

If an onError callback function is provided, the callback function will be called if there is any sort of error while attempting to execute the query. The onError callback function will be passed two arguments: an Error object and the Request object.

The scope parameter.

If a scope object is provided, all of the callback functions (onItem, onComplete, onError, etc) will be invoked in the context of the scope object. In the body of the callback function, the value of the "this" keyword will be the scope object. If no scope object is provided, the callback functions will be called in the context of dojo.global(). For example, onItem.call(scope, item, request) vs. onItem.call(dojo.global(), item, request)

The start parameter.

If a start parameter is specified, this is a indication to the datastore to only start returning items once the start number of items have been located and skipped. When this parameter is paired with 'count', the store should be able to page across queries with millions of hits by only returning subsets of the hits for each query

The count parameter.

If a count parameter is specified, this is a indication to the datastore to only return up to that many items. This allows a fetch call that may have millions of item matches to be paired down to something reasonable.

The sort parameter.

If a sort parameter is specified, this is a indication to the datastore to sort the items in some manner before returning the items. The array is an array of javascript objects that must conform to the following format to be applied to the fetching of items:

{
    attribute: attribute || attribute-name-string,
    descending: true|false;   // Optional.  Default is false.
}

Note that when comparing attributes, if an item contains no value for the attribute

(undefined), then it the default ascending sort logic should push it to the bottom of the list. In the descending order case, it such items should appear at the top of the list.

An anonymous object that defines the item to locate and callbacks to invoke when the item has been located and load has completed. The format of the object is as follows:

{
    identity: string|object,
    onItem: Function,
    onError: Function,
    scope: object
}

The identity parameter

The identity parameter is the identity of the item you wish to locate and load This attribute is required. It should be a string or an object that toString() can be called on.

The onItem parameter

Function(item) The onItem parameter is the callback to invoke when the item has been loaded. It takes only one parameter, the item located, or null if none found.

The onError parameter

Function(error) The onError parameter is the callback to invoke when the item load encountered an error. It takes only one parameter, the error object

The scope parameter

If a scope object is provided, all of the callback functions (onItem, onError, etc) will be invoked in the context of the scope object. In the body of the callback function, the value of the "this" keyword will be the scope object. If no scope object is provided, the callback functions will be called in the context of dojo.global. For example, onItem.call(scope, item, request) vs. onItem.call(dojo.global, item, request)

The item to access attributes on.

The item from the store from which to obtain its identifier.

The item from the store from which to obtain the array of public attributes that compose the identifier, if any.

The item to return the label for.

The item to return the list of label attributes for.

The item to access values on.

The attribute to access represented as a string.

Optional. A default value to use for the getValue return in the attribute does not exist or has no value.

The item to access values on.

The attribute to access represented as a string.

The item to access attributes on.

The attribute to access represented as a string.

Can be anything.

Can be anything.

An anonymous object that defines the item to load and callbacks to invoke when the load has completed. The format of the object is as follows:

{
    item: object,
    onItem: Function,
    onError: Function,
    scope: object
}

The item parameter

The item parameter is an object that represents the item in question that should be contained by the store. This attribute is required.

The onItem parameter

Function(item) The onItem parameter is the callback to invoke when the item has been loaded. It takes only one parameter, the fully loaded item.

The onError parameter

Function(error) The onError parameter is the callback to invoke when the item load encountered an error. It takes only one parameter, the error object

The scope parameter

If a scope object is provided, all of the callback functions (onItem, onError, etc) will be invoked in the context of the scope object. In the body of the callback function, the value of the "this" keyword will be the scope object. If no scope object is provided, the callback functions will be called in the context of dojo.global(). For example, onItem.call(scope, item, request) vs. onItem.call(dojo.global(), item, request)