diff options
Diffstat (limited to 'lib/dojo/data/util/simpleFetch.js.uncompressed.js')
| -rw-r--r-- | lib/dojo/data/util/simpleFetch.js.uncompressed.js | 240 |
1 files changed, 240 insertions, 0 deletions
diff --git a/lib/dojo/data/util/simpleFetch.js.uncompressed.js b/lib/dojo/data/util/simpleFetch.js.uncompressed.js new file mode 100644 index 000000000..94eb9e7a5 --- /dev/null +++ b/lib/dojo/data/util/simpleFetch.js.uncompressed.js @@ -0,0 +1,240 @@ +define("dojo/data/util/simpleFetch", ["../../_base/lang", "../../_base/kernel", "./sorter"], + function(lang, kernel, sorter){ + // module: + // dojo/data/util/simpleFetch + // summary: + // The simpleFetch mixin is designed to serve as a set of function(s) that can + // be mixed into other datastore implementations to accelerate their development. + +var simpleFetch = {}; +lang.setObject("dojo.data.util.simpleFetch", simpleFetch); + +simpleFetch.errorHandler = function(/*Object*/ errorData, /*Object*/ requestObject){ + // summary: + // The error handler when there is an error fetching items. This function should not be called + // directly and is used by simpleFetch.fetch(). + if(requestObject.onError){ + var scope = requestObject.scope || kernel.global; + requestObject.onError.call(scope, errorData, requestObject); + } +}; + +simpleFetch.fetchHandler = function(/*Array*/ items, /*Object*/ requestObject){ + // summary: + // The handler when items are sucessfully fetched. This function should not be called directly + // and is used by simpleFetch.fetch(). + var oldAbortFunction = requestObject.abort || null, + aborted = false, + + startIndex = requestObject.start?requestObject.start: 0, + endIndex = (requestObject.count && (requestObject.count !== Infinity))?(startIndex + requestObject.count):items.length; + + requestObject.abort = function(){ + aborted = true; + if(oldAbortFunction){ + oldAbortFunction.call(requestObject); + } + }; + + var scope = requestObject.scope || kernel.global; + if(!requestObject.store){ + requestObject.store = this; + } + if(requestObject.onBegin){ + requestObject.onBegin.call(scope, items.length, requestObject); + } + if(requestObject.sort){ + items.sort(sorter.createSortFunction(requestObject.sort, this)); + } + if(requestObject.onItem){ + for(var i = startIndex; (i < items.length) && (i < endIndex); ++i){ + var item = items[i]; + if(!aborted){ + requestObject.onItem.call(scope, item, requestObject); + } + } + } + if(requestObject.onComplete && !aborted){ + var subset = null; + if(!requestObject.onItem){ + subset = items.slice(startIndex, endIndex); + } + requestObject.onComplete.call(scope, subset, requestObject); + } +}; + +simpleFetch.fetch = function(/* Object? */ request){ + // summary: + // The simpleFetch mixin is designed to serve as a set of function(s) that can + // be mixed into other datastore implementations to accelerate their development. + // description: + // The simpleFetch mixin should work well for any datastore that can respond to a _fetchItems() + // call by returning an array of all the found items that matched the query. The simpleFetch mixin + // is not designed to work for datastores that respond to a fetch() call by incrementally + // loading items, or sequentially loading partial batches of the result + // set. For datastores that mixin simpleFetch, simpleFetch + // implements a fetch method that automatically handles eight of the fetch() + // arguments -- onBegin, onItem, onComplete, onError, start, count, sort and scope + // The class mixing in simpleFetch should not implement fetch(), + // but should instead implement a _fetchItems() method. The _fetchItems() + // method takes three arguments, the keywordArgs object that was passed + // to fetch(), a callback function to be called when the result array is + // available, and an error callback to be called if something goes wrong. + // The _fetchItems() method should ignore any keywordArgs parameters for + // start, count, onBegin, onItem, onComplete, onError, sort, and scope. + // The _fetchItems() method needs to correctly handle any other keywordArgs + // parameters, including the query parameter and any optional parameters + // (such as includeChildren). The _fetchItems() method should create an array of + // result items and pass it to the fetchHandler along with the original request object -- + // or, the _fetchItems() method may, if it wants to, create an new request object + // with other specifics about the request that are specific to the datastore and pass + // that as the request object to the handler. + // + // For more information on this specific function, see dojo/data/api/Read.fetch() + // + // request: + // 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. + + request = request || {}; + if(!request.store){ + request.store = this; + } + + this._fetchItems(request, lang.hitch(this, "fetchHandler"), lang.hitch(this, "errorHandler")); + return request; // Object +}; + +return simpleFetch; +}); |