dojo/data/api/Write

Summary

This is an abstract API that data provider implementations conform to. This file defines function signatures and intentionally leaves all the functions unimplemented.

See the dojo/data/api/Write reference documentation for more information.

Methods

close(request)

Defined by dojo/data/api/Read

The close() method is intended for instructing the store to 'close' out any information associated with a particular request.

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 receive 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.

Examples

Example 1

var request = store.fetch({onComplete: doSomething});
...
store.close(request);

containsValue(item,attribute,value)

Defined by dojo/data/api/Read

Returns true if the given value is one of the values that getValues() would return.

Examples

Example 1

var trueOrFalse = store.containsValue(kermit, "color", "green");

deleteItem(item)

Defined by dojo/data/api/Write

Deletes an item from the store.

Examples

Example 1

var success = store.deleteItem(kermit);

fetch(keywordArgs)

Defined by dojo/data/api/Read

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.

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

{
    query: query-object or query-string,
    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 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.
}

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

Returns: any

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.

Examples

Example 1

Fetch all books identified by the query and call 'showBooks' when complete

var request = store.fetch({query:"all books", onComplete: showBooks});

Example 2

Fetch all items in the story and call 'showEverything' when complete.

var request = store.fetch(onComplete: showEverything);

Example 3

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});

Example 4

Fetch all items that match the query, calling 'callback' each time an item is located.

var request = store.fetch({query:"foo/bar", onItem:callback});

Example 5

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});

Example 6

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'});

Example 7

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});

Example 8

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});

Example 9

Fetch the first 100 books by author King, where the name may appear 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});

Example 10

Paging

var store = new 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);
...

and then when the user presses the "Next Page" button...

fetchArgs.start += 20;
store.fetch(fetchArgs);  // get the next 20 items

getAttributes(item)

Defined by dojo/data/api/Read

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: [].

Examples

Example 1

var array = store.getAttributes(kermit);

getFeatures()

Defined by dojo/data/api/Write

See dojo/data/api/Read.getFeatures()

Returns: object

getLabel(item)

Defined by dojo/data/api/Read

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.

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.

Returns: any

A user-readable string representing the item or undefined if no user-readable label can be generated.

getLabelAttributes(item)

Defined by dojo/data/api/Read

Method to inspect the item and return an array of what attributes of the item were used to generate its label, if any.

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.

Returns: any

An array of attribute names that were used to generate the label, or null if public attributes were not used to generate the label.

getValue(item,attribute,defaultValue)

Defined by dojo/data/api/Read

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).

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.

Returns: any

a literal, an item, null, or undefined (never an array)

Examples

Example 1

var darthVader = store.getValue(lukeSkywalker, "father");

getValues(item,attribute)

Defined by dojo/data/api/Read

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) has a return of false, then store.getValues(item, attribute) will return [].)

Returns: any

an array that may contain literals and items

Examples

Example 1

var friendsOfLuke = store.getValues(lukeSkywalker, "friends");

hasAttribute(item,attribute)

Defined by dojo/data/api/Read

Returns true if the given item has a value for the given attribute.

Examples

Example 1

var trueOrFalse = store.hasAttribute(kermit, "color");

isDirty(item)

Defined by dojo/data/api/Write

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 function returns true if any item has been modified since the last save().

Examples

Example 1

var trueOrFalse = store.isDirty(kermit); // true if kermit is dirty
var trueOrFalse = store.isDirty();       // true if any item is dirty

isItem(something)

Defined by dojo/data/api/Read

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.

Examples

Example 1

var yes = store.isItem(store.newItem());
var no  = store.isItem("green");

isItemLoaded(something)

Defined by dojo/data/api/Read

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).

Examples

Example 1

var yes = store.isItemLoaded(store.newItem());
var no  = store.isItemLoaded("green");

loadItem(keywordArgs)

Defined by dojo/data/api/Read

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.

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

newItem(keywordArgs,parentInfo)

Defined by dojo/data/api/Write

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 targeted is multi-valued and a new item is appended onto the list of values for that attribute.

{
    parent: someItem,
    attribute: "attribute-name-string"
}

Examples

Example 1

var kermit = store.newItem({name: "Kermit", color:[blue, green]});

revert()

Defined by dojo/data/api/Write

Discards any unsaved changes.

Discards any unsaved changes.

Examples

Example 1

var success = store.revert();

save(keywordArgs)

Defined by dojo/data/api/Write

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.

{
    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: any

Nothing. Since the saves are generally asynchronous, there is no need to return anything. All results are passed via callbacks.

Examples

Example 1

store.save({onComplete: onSave});
store.save({scope: fooObj, onComplete: onSave, onError: saveFailed});

setValue(item,attribute,value)

Defined by dojo/data/api/Write

Sets the value of an attribute on an item. Replaces any previous value or values.

Examples

Example 1

var success = store.set(kermit, "color", "green");

setValues(item,attribute,values)

Defined by dojo/data/api/Write

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).

Examples

Example 1

var success = store.setValues(kermit, "color", ["green", "aqua"]);
success = store.setValues(kermit, "color", []);
if (success){assert(!store.hasAttribute(kermit, "color"));}

unsetAttribute(item,attribute)

Defined by dojo/data/api/Write

Deletes all the values of an attribute on an item.

Examples

Example 1

var success = store.unsetAttribute(kermit, "color");
if (success){assert(!store.hasAttribute(kermit, "color"));}