]>
Commit | Line | Data |
---|---|---|
f0cfe83e AD |
1 | define("dojo/data/util/simpleFetch", ["../../_base/lang", "../../_base/kernel", "./sorter"], |
2 | function(lang, kernel, sorter){ | |
3 | // module: | |
4 | // dojo/data/util/simpleFetch | |
5 | // summary: | |
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. | |
8 | ||
9 | var simpleFetch = {}; | |
10 | lang.setObject("dojo.data.util.simpleFetch", simpleFetch); | |
11 | ||
12 | simpleFetch.errorHandler = function(/*Object*/ errorData, /*Object*/ requestObject){ | |
13 | // summary: | |
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); | |
19 | } | |
20 | }; | |
21 | ||
22 | simpleFetch.fetchHandler = function(/*Array*/ items, /*Object*/ requestObject){ | |
23 | // summary: | |
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, | |
27 | aborted = false, | |
28 | ||
29 | startIndex = requestObject.start?requestObject.start: 0, | |
30 | endIndex = (requestObject.count && (requestObject.count !== Infinity))?(startIndex + requestObject.count):items.length; | |
31 | ||
32 | requestObject.abort = function(){ | |
33 | aborted = true; | |
34 | if(oldAbortFunction){ | |
35 | oldAbortFunction.call(requestObject); | |
36 | } | |
37 | }; | |
38 | ||
39 | var scope = requestObject.scope || kernel.global; | |
40 | if(!requestObject.store){ | |
41 | requestObject.store = this; | |
42 | } | |
43 | if(requestObject.onBegin){ | |
44 | requestObject.onBegin.call(scope, items.length, requestObject); | |
45 | } | |
46 | if(requestObject.sort){ | |
47 | items.sort(sorter.createSortFunction(requestObject.sort, this)); | |
48 | } | |
49 | if(requestObject.onItem){ | |
50 | for(var i = startIndex; (i < items.length) && (i < endIndex); ++i){ | |
51 | var item = items[i]; | |
52 | if(!aborted){ | |
53 | requestObject.onItem.call(scope, item, requestObject); | |
54 | } | |
55 | } | |
56 | } | |
57 | if(requestObject.onComplete && !aborted){ | |
58 | var subset = null; | |
59 | if(!requestObject.onItem){ | |
60 | subset = items.slice(startIndex, endIndex); | |
61 | } | |
62 | requestObject.onComplete.call(scope, subset, requestObject); | |
63 | } | |
64 | }; | |
65 | ||
66 | simpleFetch.fetch = function(/* Object? */ request){ | |
67 | // summary: | |
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. | |
70 | // description: | |
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. | |
92 | // | |
93 | // For more information on this specific function, see dojo/data/api/Read.fetch() | |
94 | // | |
95 | // request: | |
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: | |
99 | // | { | |
100 | // | query: query-object or query-string, | |
101 | // | queryOptions: object, | |
102 | // | onBegin: Function, | |
103 | // | onItem: Function, | |
104 | // | onComplete: Function, | |
105 | // | onError: Function, | |
106 | // | scope: object, | |
107 | // | start: int | |
108 | // | count: int | |
109 | // | sort: array | |
110 | // | } | |
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}. | |
116 | // | |
117 | // ####The *query* parameter | |
118 | // | |
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 | |
131 | // format. | |
132 | // | |
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'. | |
138 | // | |
139 | // ####The *queryOptions* parameter | |
140 | // | |
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: | |
145 | // | { | |
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. | |
149 | // | } | |
150 | // | |
151 | // ####The *onBegin* parameter. | |
152 | // | |
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. | |
161 | // | |
162 | // ####The *onItem* parameter. | |
163 | // | |
164 | // function(item, request); | |
165 | // | |
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 | |
169 | // Request object. | |
170 | // | |
171 | // ####The *onComplete* parameter. | |
172 | // | |
173 | // function(items, request); | |
174 | // | |
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). | |
181 | // | |
182 | // ####The *onError* parameter. | |
183 | // | |
184 | // function(errorData, request); | |
185 | // | |
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. | |
191 | // | |
192 | // ####The *scope* parameter. | |
193 | // | |
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) | |
201 | // | |
202 | // ####The *start* parameter. | |
203 | // | |
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 | |
209 | // | |
210 | // ####The *count* parameter. | |
211 | // | |
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. | |
215 | // | |
216 | // ####The *sort* parameter. | |
217 | // | |
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: | |
222 | // | { | |
223 | // | attribute: attribute || attribute-name-string, | |
224 | // | descending: true|false; // Optional. Default is false. | |
225 | // | } | |
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. | |
229 | ||
230 | request = request || {}; | |
231 | if(!request.store){ | |
232 | request.store = this; | |
233 | } | |
234 | ||
235 | this._fetchItems(request, lang.hitch(this, "fetchHandler"), lang.hitch(this, "errorHandler")); | |
236 | return request; // Object | |
237 | }; | |
238 | ||
239 | return simpleFetch; | |
240 | }); |