Before diving directly into the APIs of dojo.data, the basic concepts behind the APIs need to be explored because some design descisions that were made might seem odd without an explanation as to why they were chosen. Therefore, read this page in its entirety before moving onto the individual APIs.
Data access is broken down into separate APIs because not every service or data backend is able to provide complete access and functions. So not all datastores could possibly implement functions such as read, write, identify, or notifications. To make it simple to see what features a store provides, each store must provide the 'getFeatures()' function. This function reports which APIs the store implements. The following list of basic APIs are defined:
This concept is likely one of the aspects of dojo.data that might seem confusing at first. The following code snippet shows this concept:
var store = new some.data.Store();
var items;
... //Assume in this time items is now an array populated by a call to store.fetch();
//To iterate over the items and print out the value of a 'foo' attribute, you would do the following:
for (var i = 0; i < items.length; i++){
var item = items[i];
console.log("For attribute 'foo' value was: [" + store.getValue(item, "foo") + "]");
}
This example might make you wonder why attributes are not accessed as shown in one of the following examples:
var value = item["foo"];
var value = item.foo;
var value = item.getValue("foo");
The following list presents the reasons for this requirement:
store.getValue() is called.
As a second example, the item might be a simple JavaScript structure and the store can then access the values through normal JavaScript accessor notation. From the end-users perspective, the access is exactly the same: store.getValue(item, "attribute"). This provides a consistent look and feel to accessing a variety of data types. This also provides efficiency in accessing items by reducing item load times by avoiding conversion to a defined internal format that all stores would have to use.
The most fundamental API of dojo.data is the Read API. All stores will implement this API because all stores need the ability to retrieve and process data items. The Read API is designed to be extremely flexible in how items are handled. The Read API provides the ability to:
getFeatures() call. The following examples, guidelines, and complete API documentation provide further information on the Read API. For more complete examples, review the Using Datastores section.
The following sections provide examples of the Read API in use, as described by each example heading:
var store = new some.Datastore();
var features = store.getFeatures();
for(var i in features){
console.log("Store supports feature: " + i);
}
var store = new some.Datastore();
if(store.isItem(someObject)){
console.log("Object was an item.");
}else{
console.log("Object was NOT an item.");
}
var store = new some.Datastore();
...
//Assume that someItem is an item we got from a load.
var attributes = store.getAttributes(someItem);
for(var i = 0; i < attributes.length; i++){
console.log("Item has attribute; " + attributes[i]);
}
var store = new some.Datastore();
...
//Assume that someItem is an item we got from a load.
if(store.hasAttribute(someItem, "foo")){
console.log("item has attribute foo.");
}else{
console.log("item DOES NOT have attribute foo.");
}
var store = new some.Datastore();
...
//Assume that someItem is an item we got from a load.
var label = store.getLabel(someItem);
console.log("item has label: " + label);
var store = new some.Datastore();
var gotItems = function(items, request){
console.log("Number of items located: " + items.length);
};
store.fetch({onComplete: gotItems});
Further examples of the API usage are covered in the Using Datastores section. Refer to it for examples on paging, sorting, selecting, and so forth.
The following ReadAPI was taken directly from dojo/data/api/Read.js:
getValue: function( /* item */ item,
/* attribute-name-string */ attribute,
/* value? */ defaultValue)
// summary:
// Returns a single attribute value.
// Returns defaultValue if and only if *item* does not have a value for *attribute*.
// Returns null if and only if null was explicitly set as the attribute value.
// Returns undefined if and only if the item does not have a value for the given
// attribute (which is the same as saying the item does not have the attribute).
// description:
// Saying that an "item x does not have a value for an attribute y"
// is identical to saying that an "item x does not have attribute y".
// It is an oxymoron to say "that attribute is present but has no values"
// or "the item has that attribute but does not have any attribute values".
// If store.hasAttribute(item, attribute) returns false, then
// store.getValue(item, attribute) will return undefined.
//
// item:
// The item to access values on.
// attribute:
// The attribute to access represented as a string.
// defaultValue:
// Optional. A default value to use for the getValue return in the attribute does not exist or has no value.
//
// exceptions:
// Throws an exception if *item* is not an item, or *attribute* is not a string
// examples:
// var darthVader = store.getValue(lukeSkywalker, "father");
getValues: function(/* item */ item,
/* attribute-name-string */ attribute)
// summary:
// This getValues() method works just like the getValue() method, but getValues()
// always returns an array rather than a single attribute value. The array
// may be empty, may contain a single attribute value, or may contain many
// attribute values.
// If the item does not have a value for the given attribute, then getValues()
// will return an empty array: []. (So, if store.hasAttribute(item, attribute)
// returns false, then store.getValues(item, attribute) will return [].)
//
// item:
// The item to access values on.
// attribute:
// The attribute to access represented as a string.
//
// exceptions:
// Throws an exception if *item* is not an item, or *attribute* is not a string
getAttributes: function(/* item */ item)
// summary:
// Returns an array with all the attributes that this item has. This
// method will always return an array; if the item has no attributes
// at all, getAttributes() will return an empty array: [].
//
// item:
// The item to access attributes on.
//
// exceptions:
// Throws an exception if *item* is not an item, or *attribute* is not a string
hasAttribute: function( /* item */ item,
/* attribute-name-string */ attribute)
// summary:
// Returns true if the given *item* has a value for the given *attribute*.
//
// item:
// The item to access attributes on.
// attribute:
// The attribute to access represented as a string.
//
// exceptions:
// Throws an exception if *item* is not an item, or *attribute* is not a string
containsValue: function(/* item */ item,
/* attribute-name-string */ attribute,
/* anything */ value)
// summary:
// Returns true if the given *value* is one of the values that getValues()
// would return.
//
// item:
// The item to access values on.
// attribute:
// The attribute to access represented as a string.
// value:
// The value to match as a value for the attribute.
//
// exceptions:
// Throws an exception if *item* is not an item, or *attribute* is not a string
isItem: function(/* anything */ something)
// summary:
// Returns true if *something* is an item and came from the store instance.
// Returns false if *something* is a literal, an item from another store instance,
// or is any object other than an item.
//
// something:
// Can be anything.
//
isItemLoaded: function(/* anything */ something)
// summary:
// Returns false if isItem(something) is false. Returns false if
// if isItem(something) is true but the the item is not yet loaded
// in local memory (for example, if the item has not yet been read
// from the server).
//
// something:
// Can be anything.
//
loadItem: function(/* object */ keywordArgs)
// summary:
// Given an item, this method loads the item so that a subsequent call
// to store.isItemLoaded(item) will return true. If a call to
// isItemLoaded() returns true before loadItem() is even called,
// then loadItem() need not do any work at all and will not even invoke
// the callback handlers. So, before invoking this method, check that
// the item has not already been loaded.
// keywordArgs:
// 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)
fetch: function(/* Object */ keywordArgs)
// summary:
// Given a query and set of defined options, such as a start and count of items to return,
// this method executes the query and makes the results available as data items.
// The format and expectations of stores is that they operate in a generally asynchronous
// manner, therefore callbacks are always used to return items located by the fetch parameters.
//
// description:
// A Request object will always be returned and is returned immediately.
// The basic request is nothing more than the keyword args passed to fetch and
// an additional function attached, abort(). The returned request object may then be used
// to cancel a fetch. All data items returns are passed through the callbacks defined in the
// fetch parameters and are not present on the 'request' object.
//
// This does not mean that custom stores can not add methods and properties to the request object
// returned, only that the API does not require it. For more info about the Request API,
// see dojo.data.api.Request
//
// keywordArgs:
// 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-string or query-object,
// 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 optiosn 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 withh '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.
//
// returns:
// The fetch() method will return a javascript object conforming to the API
// defined in dojo.data.api.Request. In general, it will be the keywordArgs
// object returned with the required functions in Request.js attached.
// Its general purpose is to provide a convenient way for a caller to abort an
// ongoing fetch.
//
// The Request object may also have additional properties when it is returned
// such as request.store property, which is a pointer to the datastore object that
// fetch() is a method of.
//
// exceptions:
// Throws an exception if the query is not valid, or if the query
// is required but was not supplied.
getFeatures: function()
// summary:
// The getFeatures() method returns an simple keyword values object
// that specifies what interface features the datastore implements.
// A simple CsvStore may be read-only, and the only feature it
// implements will be the 'dojo.data.api.Read' interface, so the
// getFeatures() method will return an object like this one:
// {'dojo.data.api.Read': true}.
// A more sophisticated datastore might implement a variety of
// interface features, like 'dojo.data.api.Read', 'dojo.data.api.Write',
// 'dojo.data.api.Identity', and 'dojo.data.api.Attribution'.
close: function(/*dojo.data.api.Request || keywordArgs || null */ request)
// summary:
// The close() method is intended for instructing the store to 'close' out
// any information associated with a particular request.
//
// description:
// The close() method is intended for instructing the store to 'close' out
// any information associated with a particular request. In general, this API
// expects to recieve as a parameter a request object returned from a fetch.
// It will then close out anything associated with that request, such as
// clearing any internal datastore caches and closing any 'open' connections.
// For some store implementations, this call may be a no-op.
//
// request:
// 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.
getLabel: function(/* item */ item)
// summary:
// Method to inspect the item and return a user-readable 'label' for the item
// that provides a general/adequate description of what the item is.
//
// description:
// Method to inspect the item and return a user-readable 'label' for the item
// that provides a general/adequate description of what the item is. In general
// most labels will be a specific attribute value or collection of the attribute
// values that combine to label the item in some manner. For example for an item
// that represents a person it may return the label as: "firstname lastlame" where
// the firstname and lastname are attributes on the item. If the store is unable
// to determine an adequate human readable label, it should return undefined. Users that wish
// to customize how a store instance labels items should replace the getLabel() function on
// their instance of the store, or extend the store and replace the function in
// the extension class.
//
// item:
// The item to return the label for.
//
// returns:
// A user-readable string representing the item or undefined if no user-readable label can
// be generated.
getLabelAttributes: function(/* item */ item)
// summary:
// Method to inspect the item and return an array of what attributes of the item were used
// to generate its label, if any.
//
// description:
// Method to inspect the item and return an array of what attributes of the item were used
// to generate its label, if any. This function is to assist UI developers in knowing what
// attributes can be ignored out of the attributes an item has when displaying it, in cases
// where the UI is using the label as an overall identifer should they wish to hide
// redundant information.
//
// item:
// The item to return the list of label attributes for.
//
// returns:
// An array of attribute names that were used to generate the label, or null if public attributes
// were not used to generate the label.Some datastores provide the ability to create new items and save those items back to a service, in addition to simply reading items from a service. Stores with this capability will implement the Write API, which provides standard functions for creating new items, modifing existing items, and deleting existing items. Review the following examples, guidelines, and complete API documentation for further information on the Write API.
The following sections provide examples of the Read API in use, as described by each example heading:
//Instantiate some write implementing store. var store = some.DataWriteStore(); //Set our load completed hander up... var onCompleteFetch = function(items, request) { //Define the save callbacks to use var onSave = function(){ alert("Save done."); } var onSaveError = function(error) { alert("Error occurred: " + error) } // Process the items and update attribute 'foo' for (var i = 0; i < items.length; i++){ var item = items[i]; store.setValue(item, "foo", ("bar" + 1)); } // If the store has modified items (it should), call save with the handlers above. if (store.isDirty()){ store.save({onComplete: onSave, onError: onSaveError}); } } //Define a fetch error handler, just in case. var onFetchError = function(error, request){ alert("Fetch failed. " + error); } // Fetch some data... All items with a foo attribute, any value. store.fetch({query: {foo:"*"}, onComplete: onCompleteFetch});
//Instantiate some write implementing store. var store = some.DataWriteStore(); //Set our load completed hander up... var onCompleteFetch = function(items, request) { // Process the items test for modification for (int i = 0; i < items.length(); i++){ var item = items[i]; if (store.isDirty(item){ alert("Item with label: " + store.getLabel(item) + " is dirty."); } } } //Define a fetch error handler, just in case. var onFetchError = function(error, request){ alert("Fetch failed. " + error); } // Fetch some data... All items, in fact (no query should return everything) store.fetch({onComplete: onCompleteFetch});
The following list provides the requirements for the Write API:
newItem, deleteItem, and setAttribute calls on items so that the store can both save the items to the persistent store in one chunk and have the ability to revert out all the current changes and return to a pristine (unmodified) data set.Save function, account for any copying of items and generation of save format required by the back end service before it enters into the asynchronous I/O with the server. This is to avoid any contention issues with modifications that are occurring while the datastore is is waiting for the server I/O to complete. newItem is a keywordArgs object. For ease of interoperability, this parameter should be constructed as a JavaScrpt object with attribute names and values that match the conceptual structure of the attribute list the item would return. For example, if the source store is an XML backed store, a call to create a new XML Element in that store with attributes foo, bar, and bit, should look like this:
store.newItem({foo: "fooValue", bar: "barValue", bit: "bitValue"});
The store will then handle constructing the actual DOMElement with the appropriate DOM attributes.store.newItem() are valid items. In other words, store.isItem(item) returns true.store.newItem() are dirty items until the next save. In other words, store.isDirty(item) returns true.store.deleteItem() are no longer valid items. In other words, store.isItem(item) returns false unless store.revert() is called and the delete is undone.The following Write API was taken directly from dojo/data/api/Write.js):
newItem: function(/* Object? */ keywordArgs, /*Object?*/ parentInfo){
// summary:
// Returns a newly created item. Sets the attributes of the new
// item based on the *keywordArgs* provided. In general, the attribute
// names in the keywords become the attributes in the new item and as for
// the attribute values in keywordArgs, they become the values of the attributes
// in the new item. In addition, for stores that support hierarchical item
// creation, an optional second parameter is accepted that defines what item is the parent
// of the new item and what attribute of that item should the new item be assigned to.
// In general, this will assume that the attribute targetted is multi-valued and a new item
// is appended onto the list of values for that attribute.
//
// keywordArgs:
// A javascript object defining the initial content of the item as a set of JavaScript 'property name: value' pairs.
// parentInfo:
// An optional javascript object defining what item is the parent of this item (in a hierarchical store. Not all stores do hierarchical items),
// and what attribute of that parent to assign the new item to. If this is present, and the attribute specified
// is a multi-valued attribute, it will append this item into the array of values for that attribute. The structure
// of the object is as follows:
// {
// parent: someItem,
// attribute: "attribute-name-string"
// }
//
// exceptions:
// Throws an exception if *keywordArgs* is a string or a number or
// anything other than a simple anonymous object.
// Throws an exception if the item in parentInfo is not an item from the store
// or if the attribute isn't an attribute name string.
// examples:
// var kermit = store.newItem({name: "Kermit", color:[blue, green]});
deleteItem: function(/* item */ item)
// summary:
// Deletes an item from the store.
//
// item:
// The item to delete.
//
// exceptions:
// Throws an exception if the argument *item* is not an item
// (if store.isItem(item) returns false).
// examples:
// var success = store.deleteItem(kermit);
setValue: function( /* item */ item,
/* string */ attribute,
/* almost anything */ value)
// summary:
// Sets the value of an attribute on an item.
// Replaces any previous value or values.
//
// item:
// The item to modify.
// attribute:
// The attribute of the item to change represented as a string name.
// value:
// The value to assign to the item.
//
// exceptions:
// Throws an exception if *item* is not an item, or if *attribute*
// is neither an attribute object or a string.
// Throws an exception if *value* is undefined.
// examples:
// var success = store.set(kermit, "color", "green");
setValues: function(/* item */ item,
/* string */ attribute,
/* array */ values)
// summary:
// Adds each value in the *values* array as a value of the given
// attribute on the given item.
// Replaces any previous value or values.
// Calling store.setValues(x, y, []) (with *values* as an empty array) has
// the same effect as calling store.unsetAttribute(x, y).
//
// item:
// The item to modify.
// attribute:
// The attribute of the item to change represented as a string name.
// values:
// An array of values to assign to the attribute..
//
// exceptions:
// Throws an exception if *values* is not an array, if *item* is not an
// item, or if *attribute* is neither an attribute object or a string.
// examples:
// var success = store.setValues(kermit, "color", ["green", "aqua"]);
// success = store.setValues(kermit, "color", []);
// if (success) {assert(!store.hasAttribute(kermit, "color"));}
unsetAttribute: function( /* item */ item,
/* string */ attribute)
// summary:
// Deletes all the values of an attribute on an item.
//
// item:
// The item to modify.
// attribute:
// The attribute of the item to unset represented as a string.
//
// exceptions:
// Throws an exception if *item* is not an item, or if *attribute*
// is neither an attribute object or a string.
// examples:
// var success = store.unsetAttribute(kermit, "color");
// if (success) {assert(!store.hasAttribute(kermit, "color"));}
save: function(/* object */ keywordArgs)
// summary:
// Saves to the server all the changes that have been made locally.
// The save operation may take some time and is generally performed
// in an asynchronous fashion. The outcome of the save action is
// is passed into the set of supported callbacks for the save.
//
// keywordArgs:
// {
// onComplete: function
// onError: function
// scope: object
// }
//
// The *onComplete* parameter.
// function();
//
// If an onComplete callback function is provided, the callback function
// will be called just once, after the save has completed. No parameters
// are generally passed to the onComplete.
//
// The *onError* parameter.
// function(errorData);
//
// 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 save. The onError function will be based one parameter, the
// error.
//
// The *scope* parameter.
// If a scope object is provided, all of the callback function (
// 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, onComplete.call(scope) vs.
// onComplete.call(dojo.global)
//
// returns:
// Nothing. Since the saves are generally asynchronous, there is
// no need to return anything. All results are passed via callbacks.
// examples:
// store.save({onComplete: onSave});
// store.save({scope: fooObj, onComplete: onSave, onError: saveFailed});
revert: function()
// summary:
// Discards any unsaved changes.
// description:
// Discards any unsaved changes.
//
// examples:
// var success = store.revert();
isDirty: function(/* item? */ item)
// summary:
// Given an item, isDirty() returns true if the item has been modified
// since the last save(). If isDirty() is called with no *item* argument,
// then this method returns true if any item has been modified since
// the last save().
//
// item:
// The item to check.
//
// exceptions:
// Throws an exception if isDirty() is passed an argument and the
// argument is not an item.
// examples:
// var trueOrFalse = store.isDirty(kermit); // true if kermit is dirty
// var trueOrFalse = store.isDirty(); // true if any item is dirty
The dojo.data.api.Identity interface defines the set of APIs that are implemented by a datastore if a data source provides a method by which to uniquely identify each item. This API then allows users of that datastore to request a specific item without searching for an item that matches specific attributes. Review the following examples, guidelines, and complete API documentation for futher information on the Identity API.
For all of the examples in the following sections, assume that there is a simple ItemFileReadStore instantiation from the following data in the countries.json file:
{ identifier: 'abbr',
label: 'name',
items: [
{ abbr:'ec', name:'Ecuador', capital:'Quito' },
{ abbr:'eg', name:'Egypt', capital:'Cairo' },
{ abbr:'sv', name:'El Salvador', capital:'San Salvador' },
{ abbr:'gq', name:'Equatorial Guinea', capital:'Malabo' },
{ abbr:'er', name:'Eritrea', capital:'Asmara' },
{ abbr:'ee', name:'Estonia', capital:'Tallinn' },
{ abbr:'et', name:'Ethiopia', capital:'Addis Ababa' }
]}
var itemStore = new dojo.data.ItemFileReadStore({url: countries.json});
function failed(error) {
... //Do something with the provided error.
}
function gotItem(item) {
if (itemStore.isItem(item)){
if(!(itemStore.getValue(item,"name") === "El Salvador")){{
failed(new Error("The item loaded does not have the attribute value for attribute [name] expected."));
}else{
... //Do something with it.
}
}else{
//This should never occur.
console.log("Unable to locate the item with identity [sv]");
}
}
//Invoke the lookup. This is an async call as it may have to call back to a server to get data.
itemStore.fetchItemByIdentity({identity: "sv" onItem: gotItem, onError: failed});
var itemStore = new dojo.data.ItemFileReadStore({url: countries.json});
...
function onError(error, request){
... //Do something with the provided error.
}
function onComplete(items, request) {
if(items.length === 1){
var identifier = itemStore.getIdentity(items[0]);
if(identifier !== null && identifier === "er"){
... //Do something with the located identity.
}else{
onError(new Error("The identifier returned does not match what was expected."), request);
}
}else{
onError(new Error("Too many matches found."), request);
}
}
//Search the store and find the item with the name Eritrea
itemStore.fetch({query: {name:"Eritrea"}, onComplete: onComplete, onError: onError});
var itemStore = new dojo.data.ItemFileReadStore({url: countries.json});
function failed(error) {
... //Do something with the provided error.
}
function gotItem(item) {
if (itemStore.isItem(item)){
if(!(itemStore .getValue(item,"name") === "El Salvador")){{
failed(new Error("The item loaded does not have the attribute value for attribute [name] expected."));
}else{
var identityAttributes = itemStore.getIdentityAttributes(item);
if(identityAttributes !== null){
for(var i = 0; i < identityAttributes.length; i++){
var identifier = identityAttributes[i];
... //Do something with 'identifier'.
}
}else{
failed(new Error("Unable to locate the list of attributes comprising the identity."));
}
}
}else{
//This should never occur.
throw new Error("Unable to locate the item with identity [sv]");
}
}
//Invoke the lookup. This is an async call as it may have to call back to a server to get data.
itemStore.fetchItemByIdentity({identity: "sv" onItem: gotItem, onError: failed});
To see more examples of the Identity API, refer to the test cases defined in the dojo/tests/data/ItemFileReadStore.js file of your dojo source tree.
The following list provides the requirements for the Identity API:
toString() JavaScript API.
Note: This does not keep identities from being compound keys; they just must be able to be represented in a string fashion.
getIdentityAttributes() method. If they are not exposed as public attributes, then the getIdentityAttributes() method must return a null value.getFeatures() function will return, as part of its associative map, a property with the key name of dojo.data.api.Identity. The value of the property can be anything reasonable, such as the boolean value true, the name of the attribute that represents the identity, an array of attributes, or even an object. By the mere presence of this key in the map, the store declares that it implements this API.
The following Identity API was taken directly from dojo/data/api/Identity.js:
getIdentity: function(/* item */ item)
// summary:
// Returns a unique identifier for an item. The return value will be
// either a string or something that has a toString() method.
// item:
// The item from the store from which to obtain its identifier.
// exceptions:
// Conforming implementations may throw an exception or return null if
// item is not an item.
getIdentityAttributes: function(/* item */ item)
// summary:
// Returns an array of attribute names that are used to generate the identity.
// For most stores, this is a single attribute, but for some complex stores
// such as RDB backed stores that use compound (multi-attribute) identifiers
// it can be more than one. If the identity is not composed of attributes
// on the item, it will return null. This function is intended to identify
// the attributes that comprise the identity so that so that during a render
// of all attributes, the UI can hide the the identity information if it
// chooses.
// item:
// The item from the store from which to obtain the array of public attributes that
// compose the identifier, if any.
fetchItemByIdentity: function(/* object */ keywordArgs){
// summary:
// Given the identity of an item, this method returns the item that has
// that identity through the onItem callback. Conforming implementations
// should return null if there is no item with the given identity.
// Implementations of fetchItemByIdentity() may sometimes return an item
// from a local cache and may sometimes fetch an item from a remote server,
//
// keywordArgs:
// 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)When working with data and items, sometimes it is useful to be notified when items are created, deleted, or modified within a given dojo.data datastore. The dojo.data.api.Notification feature is implemented by stores to expose such a capability. This set of functions defines monitoring for the main change events a store can see on an item: create, modify, and delete. Review the following examples, guidelines, and complete API documentation for further information on the Notification API.
There are two general patterns of listening on these functions for change events. The first pattern is to use the dojo.connect() event model to bind to the function on the store and have one of your functions called whenever the store calls the onSet, onNew, and onDelete functions. The second pattern is to replace the implementation of the notification functions on the store with custom logic to do something each time the store calls the function. Example usage of such functions are provided in the following examples.
var store = some.NotifyWriteStore();
var alertOnNew = function(item) {
var label = store.getLabel(item);
alert("New item was created: [" + label + "]");
};
dojo.connect(store, "onNew", alertOnNew);
//An alert should be thrown when this completes
var newItem = store.newItem({foo:"bar"});
var store = some.NotifyWriteStore();
store.onNew = function(item) {
var label = this.getLabel(item);
alert("New item was created: [" + label + "]");
};
//An alert should be thrown when this completes
var newItem = store.newItem({foo:"bar"});
Note that the previous examples can be applied to any of the store Notification APIs. Also note that, by doing either the connect or the function override on the store, you can implement a variety of item event handling. This includes performing actions only when desired items are effected, as needed for your particular notification scenario. As an example, you could look at a list of items your store has specifically kept track of as items of interest and only perform an operation when the item passed into the on*() function matches one in the list.
As with all DataStores, not all stores will implement this API. For stores that implement this API, the following assumptions should be made:
create, set attribute and delete) will trigger a call to the appropriate store notification function.The following Notification API was taken directly from dojo/data/api/Notification.js:
onSet: function(/* item */ item,
/* attribute-name-string */ attribute,
/* object | array */ oldValue,
/* object | array */ newValue)
// summary:
// This function is called any time an item is modified via setValue, setValues, unsetAttribute, etc.
// description:
// This function is called any time an item is modified via setValue, setValues, unsetAttribute, etc.
// Its purpose is to provide a hook point for those who wish to monitor actions on items in the store
// in a simple manner. The general expected usage is to dojo.connect() to the store's
// implementation and be called after the store function is called.
//
// item:
// The item being modified.
// attribute:
// The attribute being changed represented as a string name.
// oldValue:
// The old value of the attribute. In the case of single value calls, such as setValue, unsetAttribute, etc,
// this value will be generally be an atomic value of some sort (string, int, etc, object). In the case of
// multi-valued attributes, it will be an array.
// newValue:
// The new value of the attribute. In the case of single value calls, such as setValue, this value will be
// generally be an atomic value of some sort (string, int, etc, object). In the case of multi-valued attributes,
// it will be an array. In the case of unsetAttribute, the new value will be 'undefined'.
//
// returns:
// Nothing.
onNew: function(/* item */ newItem, /*object?*/ parentInfo){
// summary:
// This function is called any time a new item is created in the store.
// It is called immediately after the store newItem processing has completed.
// description:
// This function is called any time a new item is created in the store.
// It is called immediately after the store newItem processing has completed.
//
// newItem:
// The item created.
// parentInfo:
// An optional javascript object that is passed when the item created was placed in the store
// hierarchy as a value f another item's attribute, instead of a root level item. Note that if this
// function is invoked with a value for parentInfo, then onSet is not invoked stating the attribute of
// the parent item was modified. This is to avoid getting two notification events occurring when a new item
// with a parent is created. The structure passed in is as follows:
// {
// item: someItem, //The parent item
// attribute: "attribute-name-string", //The attribute the new item was assigned to.
// oldValue: something //Whatever was the previous value for the attribute.
// //If it is a single-value attribute only, then this value will be a single value.
// //If it was a multi-valued attribute, then this will be an array of all the values minues the new one.
// newValue: something //The new value of the attribute. In the case of single value calls, such as setValue, this value will be
// //generally be an atomic value of some sort (string, int, etc, object). In the case of multi-valued attributes,
// //it will be an array.
// }
//
// returns:
// Nothing.
onDelete: function(/* item */ deletedItem)
// summary:
// This function is called any time an item is deleted from the store.
// It is called immediately after the store deleteItem processing has completed.
// description:
// This function is called any time an item is deleted from the store.
// It is called immediately after the store deleteItem processing has completed.
//
// deletedItem:
// The item deleted.
//
// returns:
// Nothing.