]>
git.wh0rd.org - tt-rss.git/blob - lib/dojo/data/util/simpleFetch.js.uncompressed.js
1 define("dojo/data/util/simpleFetch", ["../../_base/lang", "../../_base/kernel", "./sorter"],
2 function(lang
, kernel
, sorter
){
4 // dojo/data/util/simpleFetch
6 // The simpleFetch mixin is designed to serve as a set of function(s) that can
7 // be mixed into other datastore implementations to accelerate their development.
10 lang
.setObject("dojo.data.util.simpleFetch", simpleFetch
);
12 simpleFetch
.errorHandler = function(/*Object*/ errorData
, /*Object*/ requestObject
){
14 // The error handler when there is an error fetching items. This function should not be called
15 // directly and is used by simpleFetch.fetch().
16 if(requestObject
.onError
){
17 var scope
= requestObject
.scope
|| kernel
.global
;
18 requestObject
.onError
.call(scope
, errorData
, requestObject
);
22 simpleFetch
.fetchHandler = function(/*Array*/ items
, /*Object*/ requestObject
){
24 // The handler when items are sucessfully fetched. This function should not be called directly
25 // and is used by simpleFetch.fetch().
26 var oldAbortFunction
= requestObject
.abort
|| null,
29 startIndex
= requestObject
.start
?requestObject
.start
: 0,
30 endIndex
= (requestObject
.count
&& (requestObject
.count
!== Infinity
))?(startIndex
+ requestObject
.count
):items
.length
;
32 requestObject
.abort = function(){
35 oldAbortFunction
.call(requestObject
);
39 var scope
= requestObject
.scope
|| kernel
.global
;
40 if(!requestObject
.store
){
41 requestObject
.store
= this;
43 if(requestObject
.onBegin
){
44 requestObject
.onBegin
.call(scope
, items
.length
, requestObject
);
46 if(requestObject
.sort
){
47 items
.sort(sorter
.createSortFunction(requestObject
.sort
, this));
49 if(requestObject
.onItem
){
50 for(var i
= startIndex
; (i
< items
.length
) && (i
< endIndex
); ++i
){
53 requestObject
.onItem
.call(scope
, item
, requestObject
);
57 if(requestObject
.onComplete
&& !aborted
){
59 if(!requestObject
.onItem
){
60 subset
= items
.slice(startIndex
, endIndex
);
62 requestObject
.onComplete
.call(scope
, subset
, requestObject
);
66 simpleFetch
.fetch = function(/* Object? */ request
){
68 // The simpleFetch mixin is designed to serve as a set of function(s) that can
69 // be mixed into other datastore implementations to accelerate their development.
71 // The simpleFetch mixin should work well for any datastore that can respond to a _fetchItems()
72 // call by returning an array of all the found items that matched the query. The simpleFetch mixin
73 // is not designed to work for datastores that respond to a fetch() call by incrementally
74 // loading items, or sequentially loading partial batches of the result
75 // set. For datastores that mixin simpleFetch, simpleFetch
76 // implements a fetch method that automatically handles eight of the fetch()
77 // arguments -- onBegin, onItem, onComplete, onError, start, count, sort and scope
78 // The class mixing in simpleFetch should not implement fetch(),
79 // but should instead implement a _fetchItems() method. The _fetchItems()
80 // method takes three arguments, the keywordArgs object that was passed
81 // to fetch(), a callback function to be called when the result array is
82 // available, and an error callback to be called if something goes wrong.
83 // The _fetchItems() method should ignore any keywordArgs parameters for
84 // start, count, onBegin, onItem, onComplete, onError, sort, and scope.
85 // The _fetchItems() method needs to correctly handle any other keywordArgs
86 // parameters, including the query parameter and any optional parameters
87 // (such as includeChildren). The _fetchItems() method should create an array of
88 // result items and pass it to the fetchHandler along with the original request object --
89 // or, the _fetchItems() method may, if it wants to, create an new request object
90 // with other specifics about the request that are specific to the datastore and pass
91 // that as the request object to the handler.
93 // For more information on this specific function, see dojo/data/api/Read.fetch()
96 // The keywordArgs parameter may either be an instance of
97 // conforming to dojo/data/api/Request or may be a simple anonymous object
98 // that may contain any of the following:
100 // | query: query-object or query-string,
101 // | queryOptions: object,
102 // | onBegin: Function,
103 // | onItem: Function,
104 // | onComplete: Function,
105 // | onError: Function,
111 // All implementations should accept keywordArgs objects with any of
112 // the 9 standard properties: query, onBegin, onItem, onComplete, onError
113 // scope, sort, start, and count. Some implementations may accept additional
114 // properties in the keywordArgs object as valid parameters, such as
115 // {includeOutliers:true}.
117 // ####The *query* parameter
119 // The query may be optional in some data store implementations.
120 // The dojo/data/api/Read API does not specify the syntax or semantics
121 // of the query itself -- each different data store implementation
122 // may have its own notion of what a query should look like.
123 // However, as of dojo 0.9, 1.0, and 1.1, all the provided datastores in dojo.data
124 // and dojox.data support an object structure query, where the object is a set of
125 // name/value parameters such as { attrFoo: valueBar, attrFoo1: valueBar1}. Most of the
126 // dijit widgets, such as ComboBox assume this to be the case when working with a datastore
127 // when they dynamically update the query. Therefore, for maximum compatibility with dijit
128 // widgets the recommended query parameter is a key/value object. That does not mean that the
129 // the datastore may not take alternative query forms, such as a simple string, a Date, a number,
130 // or a mix of such. Ultimately, The dojo/data/api/Read API is agnostic about what the query
133 // Further note: In general for query objects that accept strings as attribute
134 // value matches, the store should also support basic filtering capability, such as *
135 // (match any character) and ? (match single character). An example query that is a query object
136 // would be like: { attrFoo: "value*"}. Which generally means match all items where they have
137 // an attribute named attrFoo, with a value that starts with 'value'.
139 // ####The *queryOptions* parameter
141 // The queryOptions parameter is an optional parameter used to specify options that may modify
142 // the query in some fashion, such as doing a case insensitive search, or doing a deep search
143 // where all items in a hierarchical representation of data are scanned instead of just the root
144 // items. It currently defines two options that all datastores should attempt to honor if possible:
146 // | ignoreCase: boolean, // Whether or not the query should match case sensitively or not. Default behaviour is false.
147 // | deep: boolean // Whether or not a fetch should do a deep search of items and all child
148 // | // items instead of just root-level items in a datastore. Default is false.
151 // ####The *onBegin* parameter.
153 // function(size, request);
154 // If an onBegin callback function is provided, the callback function
155 // will be called just once, before the first onItem callback is called.
156 // The onBegin callback function will be passed two arguments, the
157 // the total number of items identified and the Request object. If the total number is
158 // unknown, then size will be -1. Note that size is not necessarily the size of the
159 // collection of items returned from the query, as the request may have specified to return only a
160 // subset of the total set of items through the use of the start and count parameters.
162 // ####The *onItem* parameter.
164 // function(item, request);
166 // If an onItem callback function is provided, the callback function
167 // will be called as each item in the result is received. The callback
168 // function will be passed two arguments: the item itself, and the
171 // ####The *onComplete* parameter.
173 // function(items, request);
175 // If an onComplete callback function is provided, the callback function
176 // will be called just once, after the last onItem callback is called.
177 // Note that if the onItem callback is not present, then onComplete will be passed
178 // an array containing all items which matched the query and the request object.
179 // If the onItem callback is present, then onComplete is called as:
180 // onComplete(null, request).
182 // ####The *onError* parameter.
184 // function(errorData, request);
186 // If an onError callback function is provided, the callback function
187 // will be called if there is any sort of error while attempting to
188 // execute the query.
189 // The onError callback function will be passed two arguments:
190 // an Error object and the Request object.
192 // ####The *scope* parameter.
194 // If a scope object is provided, all of the callback functions (onItem,
195 // onComplete, onError, etc) will be invoked in the context of the scope
196 // object. In the body of the callback function, the value of the "this"
197 // keyword will be the scope object. If no scope object is provided,
198 // the callback functions will be called in the context of dojo.global().
199 // For example, onItem.call(scope, item, request) vs.
200 // onItem.call(dojo.global(), item, request)
202 // ####The *start* parameter.
204 // If a start parameter is specified, this is a indication to the datastore to
205 // only start returning items once the start number of items have been located and
206 // skipped. When this parameter is paired with 'count', the store should be able
207 // to page across queries with millions of hits by only returning subsets of the
208 // hits for each query
210 // ####The *count* parameter.
212 // If a count parameter is specified, this is a indication to the datastore to
213 // only return up to that many items. This allows a fetch call that may have
214 // millions of item matches to be paired down to something reasonable.
216 // ####The *sort* parameter.
218 // If a sort parameter is specified, this is a indication to the datastore to
219 // sort the items in some manner before returning the items. The array is an array of
220 // javascript objects that must conform to the following format to be applied to the
221 // fetching of items:
223 // | attribute: attribute || attribute-name-string,
224 // | descending: true|false; // Optional. Default is false.
226 // Note that when comparing attributes, if an item contains no value for the attribute
227 // (undefined), then it the default ascending sort logic should push it to the bottom
228 // of the list. In the descending order case, it such items should appear at the top of the list.
230 request
= request
|| {};
232 request
.store
= this;
235 this._fetchItems(request
, lang
.hitch(this, "fetchHandler"), lang
.hitch(this, "errorHandler"));
236 return request
; // Object