dojo.data.api.Read.fetch
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
Usage
parameter | type | description |
---|---|---|
keywordArgs | Object | 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. In most implementations the query will probably be a string, but in some implementations the query might be a Date, or a number, or some complex keyword parameter object. The dojo.data.api.Read API is completely agnostic about what the query actually is. In general for query objects that accept strings as attribute value matches, the store should support basic filtering capability, such as * (match any character) and ? (match single character). 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. |
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 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);
...
and then when the user presses the "Next Page" button...
fetchArgs.start += 20;
store.fetch(fetchArgs); // get the next 20 items