The AppStore implements three of the dojo.data APIs: Read, Write, and Identity. Read the following reference documentation about each of these APIs:
This is an abstract API that data provider implementations follow. For more information on the dojo.data APIs, visit . http://www.dojotoolkit.org/node/98.
Function Summary | |
---|---|
Object | getValue(Object item, String attribute, String defaultValue) Retrieves the value of the named attribute on the given item |
Array | getValues(Object item, String attribute) Retrieves the values of the named attribute on the given item |
Array | getAttributes(Object item) Returns an array with all the attributes of this item |
Boolean | hasAttribute(Object item, String attribute) Returns true if the given *item* has a value for the given *attribute* |
Boolean | containsValue(Object item, String attribute, Object value) Returns true if the given *value* is one of the values that the getValues method returns |
Boolean | isItem(Object something) Returns whether *something* is an item and came from this store instance |
Boolean | isItemLoaded(Object something) Returns whether *something* is loaded in local memory |
void | loadItem(Object keywordArgs) Given an item, this method loads the item so that a subsequent call to store.isItemLoaded(item) returns true |
Object | fetch(Object keywordArgs) Given a query and set of defined options, such as a start and count of items to return, this method runs the query and makes the results available as data items |
Object | getFeatures() Returns a simple keyword values object that specifies which interface features that the datastore implements |
void | close(Object request) Instructs the store to close out any information associated with a particular request |
String | getLabel(Object item) Method to inspect the item and return a user-readable label for the item that provides a general or adequate description of the item |
Array | getLabelAttributes(Object item) Method to inspect the item and return an array of what attributes of the item were used to generate its label, if any exist |
Function Detail |
---|
Item x not having a value for an attribute y is identical to an item
x that does not have attribute y. It is an oxymoron for that attribute
to be present without having values or that an item has that attribute
but does not have any attribute values. If store.hasAttribute(item, attribute)
returns false, then store.getValue(item, attribute) returns undefined.
var darthVader = store.getValue(lukeSkywalker, "father");
This getValues() method works just like the getValue() method, but getValues() always returns an array rather than a single attribute value. The array might be empty, contain a single attribute value, or contain multiple attribute values. If the item does not have a value for the given attribute, then getValues() returns an empty array: []. If store.hasAttribute(item, attribute) returns false, then store.getValues(item, attribute) returns [].
var friendsOfLuke = store.getValues(lukeSkywalker, "friends");
Returns an array with all the attributes that this item has. This method always returns an array. If the item has no attributes at all, then getAttributes() returns an empty array: [].
var array = store.getAttributes(kermit);
Returns true if the given *item* has a value for the given *attribute*
var trueOrFalse = store.hasAttribute(kermit, "color");
Returns true if the given *value* is one of the values that the getValues method returns.
var trueOrFalse = store.containsValue(kermit, "color", "green");
Returns true if *something* is an item and came from the store instance. Returns false if *something* is a literal value, an item from another store instance, or is any object other than an item.
var yes = store.isItem(store.newItem()); var no = store.isItem("green");
Returns false if isItem(something) is false. Returns false if isItem(something) is true but the the item is not yet loaded in local memory. For example, a false value is returned if the item has not yet been read from the server.
var yes = store.isItemLoaded(store.newItem()); var no = store.isItemLoaded("green");
Given an item, this method loads the item so that a subsequent call to store.isItemLoaded(item) returns true. If a call to isItemLoaded() returns true before loadItem() is even called, then loadItem() does not work and does not invoke the callback handlers. Before invoking this method, verify that the item has not already been loaded.
{ item: object, onItem: Function, onError: Function, scope: object }
Given a query and set of defined options, such as a start and count of items to return, this method runs the query and makes the results available as data items. The format of the dojo.data API's expect data stores to operate in a generally asynchronous manner; therefore, callbacks are used to return items located by the fetch parameters.
A request object returns immediately. The basic request is the keyword arguments, passed to fetch and an additional function attached, abort(). The returned request object ,might be used to cancel a fetch. All data item returns are passed through the callbacks defined in the fetch parameters and are not present on the 'request' object.
This process does not mean that custom stores cannot 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.
{ query: query-string or query-object, queryOptions: object, onBegin: Function, onItem: Function, onComplete: Function, onError: Function, scope: object, start: int count: int sort: array }
{ ignoreCase: boolean, //Whether or not the query should match case sensitively or not. Default behavior 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. }
{ attribute: attribute || attribute-name-string, descending: true|false; // Optional. Default is false. }When comparing attributes, if an item contains no value for the attribute (undefined), then the default ascending sort logic pushes it to the bottom of the list. In the descending order case, if such items are located at the top of the list.
The request object might also have additional properties when it is returned, such as request.store property, for example, which is a pointer to the data store object where fetch() is a method.
// Fetch all books identified by the query and call 'showBooks' when complete var request = store.fetch({query:"all books", onComplete: showBooks}); // Fetch all items in the story and call 'showEverything' when complete. var request = store.fetch(onComplete: showEverything); // Fetch only 10 books that match the query 'all books', starting at the fifth book found during the search. // This demonstrates how paging can be done for specific queries. var request = store.fetch({query:"all books", start: 4, count: 10, onComplete: showBooks}); // Fetch all items that match the query, calling 'callback' each time an item is located. var request = store.fetch({query:"foo/bar", onItem:callback}); // Fetch the first 100 books by author King, call showKing when up to 100 items have been located. var request = store.fetch({query:{author:"King"}, start: 0, count:100, onComplete: showKing}); // Locate the books written by Author King. Sort it on title and publisher, then return the first 100 items from the sorted items. var request = store.fetch({query:{author:"King"}, sort: [{ attribute: "title", descending: true}, {attribute: "publisher"}], ,start: 0, count:100, onComplete: 'showKing'}); // Fetch the first 100 books by authors starting with the name King, then call showKing when up to 100 items have been located. var request = store.fetch({query:{author:"King*"}, start: 0, count:100, onComplete: showKing}); // Fetch the first 100 books by authors ending with 'ing', but only have one character before it (King, Bing, Ling, Sing, etc.), then call showBooks when up to 100 items // have been located. var request = store.fetch({query:{author:"?ing"}, start: 0, count:100, onComplete: showBooks}); // Fetch the first 100 books by author King, where the name is displayed as King, king, KING, kInG, and so on, then call showKing when up to 100 items have been located. var request = store.fetch({query:{author:"King"}, queryOptions:(ignoreCase: true}, start: 0, count:100, onComplete: showKing}); // Paging: var store = new dojo.data.LargeRdbmsStore({url:"jdbc:odbc:foobar"}); var fetchArgs = { query: {type:"employees", name:"Hillary *"}, // string matching sort: [{attribute:"department", descending:true}], start: 0, count: 20, scope: displayer, onBegin: showThrobber, onItem: displayItem, onComplete: stopThrobber, onError: handleFetchError, }; store.fetch(fetchArgs); // ... // When the user presses the "Next Page" button... fetchArgs.start += 20; store.fetch(fetchArgs); // get the next 20 items
var request = store.fetch({onComplete: doSomething}); //... store.close(request);
This is an abstract API that data provider implementations follow. This API specifies the functions needed to write to a data store.
Function Summary | |
---|---|
Object | getFeatures() See dojo.data.api.Read.getFeatures |
Object | newItem(Object keywordArgs) Returns a newly created item |
Boolean | deleteItem(Object item) Deletes an item from the store |
Boolean | setValue(Object item, String attribute, Object value) Sets the value of an attribute on an item, replacing any previous value or values |
Boolean | setValues(Object item, String attribute, Array values) Adds each value in the *values* array as a value of the given attribute on the given item, replacing any previous value or values |
Boolean | unsetAttribute(Object item, String attribute) Deletes all the values of an attribute on an item |
Boolean | save(keywordArgs) Saves all the changes that have been made locally to the server |
Boolean | revert() Discards any unsaved changes |
Boolean | isDirty(item) Given an item, isDirty(), returns true if the item has been modified since the last save method completion |
Function Detail |
---|
var kermit = store.newItem({name: "Kermit", color:[blue, green]});
var success = store.deleteItem(kermit);
var success = store.set(kermit, "color", "green");
var success = store.setValues(kermit, "color", ["green", "aqua"]); success = store.setValues(kermit, "color", []); if (success) {assert(!store.hasAttribute(kermit, "color"));}
var success = store.unsetAttribute(kermit, "color"); if (success) {assert(!store.hasAttribute(kermit, "color"));}
{ onComplete: function onError: function scope: object }
store.save({onComplete: onSave}); store.save({scope: fooObj, onComplete: onSave, onError: saveFailed});
var success = store.revert();
var trueOrFalse = store.isDirty(kermit); // true if kermit is dirty var trueOrFalse = store.isDirty(); // true if any item is dirty
This is an abstract API that data provider implementations follow. The functions defined retrieve the individual identity of an item, as well as the attributes that provided the identity.
Function Summary | |
---|---|
Object | getFeatures() See dojo.data.api.Read.getFeatures |
Object | getIdentity(Object item) Returns a unique identifier for an item |
Array | getIdentityAttributes(Object item) Returns an array of attribute names that are used to generate the identity |
Object | fetchItemByIdentity(Object keywordArgs) Given the identity of an item, this method returns the item that has that identity through the onItem callback |
Function Detail |
---|
var itemId = store.getIdentity(kermit); assert(kermit === store.findByIdentity(store.getIdentity(kermit)));
var itemId = store.getIdentity(kermit); var identifiers = store.getIdentityAttributes(itemId); assert(typeof identifiers === "array" || identifiers === null);
{ identity: string|object, onItem: Function, onError: Function, scope: object }