1 if(!dojo._hasResource["dojox.data.QueryReadStore"]){ //_hasResource checks added by build. Do not use _hasResource directly in your code.
2 dojo._hasResource["dojox.data.QueryReadStore"] = true;
3 dojo.provide("dojox.data.QueryReadStore");
5 dojo.require("dojo.string");
7 dojo.declare("dojox.data.QueryReadStore",
11 // This class provides a store that is mainly intended to be used
12 // for loading data dynamically from the server, used i.e. for
13 // retreiving chunks of data from huge data stores on the server (by server-side filtering!).
14 // Upon calling the fetch() method of this store the data are requested from
15 // the server if they are not yet loaded for paging (or cached).
17 // For example used for a combobox which works on lots of data. It
18 // can be used to retreive the data partially upon entering the
19 // letters "ac" it returns only items like "action", "acting", etc.
22 // The field name "id" in a query is reserved for looking up data
23 // by id. This is necessary as before the first fetch, the store
24 // has no way of knowing which field the server will declare as
28 // | // The parameter "query" contains the data that are sent to the server.
29 // | var store = new dojox.data.QueryReadStore({url:'/search.php'});
30 // | store.fetch({query:{name:'a'}, queryOptions:{ignoreCase:false}});
32 // | // Since "serverQuery" is given, it overrules and those data are
33 // | // sent to the server.
34 // | var store = new dojox.data.QueryReadStore({url:'/search.php'});
35 // | store.fetch({serverQuery:{name:'a'}, queryOptions:{ignoreCase:false}});
37 // | <div dojoType="dojox.data.QueryReadStore"
39 // | url="../tests/stores/QueryReadStore.php"
40 // | requestMethod="post"></div>
41 // | <div dojoType="dojox.grid.data.DojoData"
44 // | sortFields="[{attribute: 'name', descending: true}]"
45 // | rowsPerPage="30"></div>
46 // | <div dojoType="dojox.Grid" id="grid2"
48 // | structure="gridLayout"
49 // | style="height:300px; width:800px;"></div>
53 // - there is a bug in the paging, when i set start:2, count:5 after an initial fetch() and doClientPaging:true
54 // it returns 6 elemetns, though count=5, try it in QueryReadStore.html
55 // - add optional caching
56 // - when the first query searched for "a" and the next for a subset of
57 // the first, i.e. "ab" then we actually dont need a server request, if
58 // we have client paging, we just need to filter the items we already have
59 // that might also be tooo much logic
65 // We use the name in the errors, once the name is fixed hardcode it, may be.
66 _className:"dojox.data.QueryReadStore",
68 // This will contain the items we have loaded from the server.
69 // The contents of this array is optimized to satisfy all read-api requirements
70 // and for using lesser storage, so the keys and their content need some explaination:
71 // this._items[0].i - the item itself
72 // this._items[0].r - a reference to the store, so we can identify the item
73 // securly. We set this reference right after receiving the item from the
77 // Store the last query that triggered xhr request to the server.
78 // So we can compare if the request changed and if we shall reload
79 // (this also depends on other factors, such as is caching used, etc).
80 _lastServerQuery:null,
83 // Store a hash of the last server request. Actually I introduced this
84 // for testing, so I can check if no unnecessary requests were issued for
85 // client-side-paging.
89 // By default every request for paging is sent to the server.
93 // By default all the sorting is done serverside before the data is returned
94 // which is the proper place to be doing it for really large datasets.
95 doClientSorting:false,
97 // Items by identify for Identify API
98 _itemsByIdentity:null,
103 _features: {'dojo.data.api.Read':true, 'dojo.data.api.Identity':true},
107 constructor: function(/* Object */ params){
108 dojo.mixin(this,params);
111 getValue: function(/* item */ item, /* attribute-name-string */ attribute, /* value? */ defaultValue){
112 // According to the Read API comments in getValue() and exception is
113 // thrown when an item is not an item or the attribute not a string!
114 this._assertIsItem(item);
115 if (!dojo.isString(attribute)) {
116 throw new Error(this._className+".getValue(): Invalid attribute, string expected!");
118 if(!this.hasAttribute(item, attribute)){
119 // read api says: return defaultValue "only if *item* does not have a value for *attribute*."
120 // Is this the case here? The attribute doesn't exist, but a defaultValue, sounds reasonable.
124 console.log(this._className+".getValue(): Item does not have the attribute '"+attribute+"'.");
126 return item.i[attribute];
129 getValues: function(/* item */ item, /* attribute-name-string */ attribute){
130 this._assertIsItem(item);
132 if(this.hasAttribute(item, attribute)){
133 ret.push(item.i[attribute]);
138 getAttributes: function(/* item */ item){
139 this._assertIsItem(item);
141 for(var i in item.i){
147 hasAttribute: function(/* item */ item, /* attribute-name-string */ attribute) {
149 // See dojo.data.api.Read.hasAttribute()
150 return this.isItem(item) && typeof item.i[attribute]!="undefined";
153 containsValue: function(/* item */ item, /* attribute-name-string */ attribute, /* anything */ value){
154 var values = this.getValues(item, attribute);
155 var len = values.length;
156 for(var i=0; i<len; i++){
157 if(values[i]==value){
164 isItem: function(/* anything */ something){
165 // Some basic tests, that are quick and easy to do here.
166 // >>> var store = new dojox.data.QueryReadStore({});
167 // >>> store.isItem("");
170 // >>> var store = new dojox.data.QueryReadStore({});
171 // >>> store.isItem({});
174 // >>> var store = new dojox.data.QueryReadStore({});
175 // >>> store.isItem(0);
178 // >>> var store = new dojox.data.QueryReadStore({});
179 // >>> store.isItem({name:"me", label:"me too"});
183 return typeof something.r!="undefined" && something.r==this;
188 isItemLoaded: function(/* anything */ something) {
189 // Currently we dont have any state that tells if an item is loaded or not
190 // if the item exists its also loaded.
191 // This might change when we start working with refs inside items ...
192 return this.isItem(something);
195 loadItem: function(/* object */ args){
196 if(this.isItemLoaded(args.item)){
199 // Actually we have nothing to do here, or at least I dont know what to do here ...
202 fetch:function(/* Object? */ request){
204 // See dojo.data.util.simpleFetch.fetch() this is just a copy and I adjusted
205 // only the paging, since it happens on the server if doClientPaging is
206 // false, thx to http://trac.dojotoolkit.org/ticket/4761 reporting this.
207 // Would be nice to be able to use simpleFetch() to reduce copied code,
208 // but i dont know how yet. Ideas please!
209 request = request || {};
211 request.store = this;
215 var _errorHandler = function(errorData, requestObject){
216 if(requestObject.onError){
217 var scope = requestObject.scope || dojo.global;
218 requestObject.onError.call(scope, errorData, requestObject);
222 var _fetchHandler = function(items, requestObject, numRows){
223 var oldAbortFunction = requestObject.abort || null;
226 var startIndex = requestObject.start?requestObject.start:0;
227 if (self.doClientPaging==false) {
228 // For client paging we dont need no slicing of the result.
231 var endIndex = requestObject.count?(startIndex + requestObject.count):items.length;
233 requestObject.abort = function(){
235 if(oldAbortFunction){
236 oldAbortFunction.call(requestObject);
240 var scope = requestObject.scope || dojo.global;
241 if(!requestObject.store){
242 requestObject.store = self;
244 if(requestObject.onBegin){
245 requestObject.onBegin.call(scope, numRows, requestObject);
247 if(requestObject.sort && this.doClientSorting){
248 items.sort(dojo.data.util.sorter.createSortFunction(requestObject.sort, self));
250 if(requestObject.onItem){
251 for(var i = startIndex; (i < items.length) && (i < endIndex); ++i){
254 requestObject.onItem.call(scope, item, requestObject);
258 if(requestObject.onComplete && !aborted){
260 if (!requestObject.onItem) {
261 subset = items.slice(startIndex, endIndex);
263 requestObject.onComplete.call(scope, subset, requestObject);
266 this._fetchItems(request, _fetchHandler, _errorHandler);
267 return request; // Object
270 getFeatures: function(){
271 return this._features;
274 close: function(/*dojo.data.api.Request || keywordArgs || null */ request){
275 // I have no idea if this is really needed ...
278 getLabel: function(/* item */ item){
280 // See dojo.data.api.Read.getLabel()
281 if(this._labelAttr && this.isItem(item)){
282 return this.getValue(item, this._labelAttr); //String
284 return undefined; //undefined
287 getLabelAttributes: function(/* item */ item){
289 // See dojo.data.api.Read.getLabelAttributes()
291 return [this._labelAttr]; //array
296 _fetchItems: function(request, fetchHandler, errorHandler){
298 // The request contains the data as defined in the Read-API.
299 // Additionally there is following keyword "serverQuery".
301 // The *serverQuery* parameter, optional.
302 // This parameter contains the data that will be sent to the server.
303 // If this parameter is not given the parameter "query"'s
304 // data are sent to the server. This is done for some reasons:
305 // - to specify explicitly which data are sent to the server, they
306 // might also be a mix of what is contained in "query", "queryOptions"
307 // and the paging parameters "start" and "count" or may be even
308 // completely different things.
309 // - don't modify the request.query data, so the interface using this
310 // store can rely on unmodified data, as the combobox dijit currently
311 // does it, it compares if the query has changed
312 // - request.query is required by the Read-API
314 // I.e. the following examples might be sent via GET:
315 // fetch({query:{name:"abc"}, queryOptions:{ignoreCase:true}})
316 // the URL will become: /url.php?name=abc
318 // fetch({serverQuery:{q:"abc", c:true}, query:{name:"abc"}, queryOptions:{ignoreCase:true}})
319 // the URL will become: /url.php?q=abc&c=true
320 // // The serverQuery-parameter has overruled the query-parameter
321 // // but the query parameter stays untouched, but is not sent to the server!
322 // // The serverQuery contains more data than the query, so they might differ!
325 var serverQuery = request.serverQuery || request.query || {};
326 //Need to add start and count
327 if(!this.doClientPaging){
328 serverQuery.start = request.start || 0;
329 // Count might not be sent if not given.
331 serverQuery.count = request.count;
334 if(!this.doClientSorting){
336 var sort = request.sort[0];
337 if(sort && sort.attribute){
338 var sortStr = sort.attribute;
340 sortStr = "-" + sortStr;
342 serverQuery.sort = sortStr;
346 // Compare the last query and the current query by simply json-encoding them,
347 // so we dont have to do any deep object compare ... is there some dojo.areObjectsEqual()???
348 if(this.doClientPaging && this._lastServerQuery!==null &&
349 dojo.toJson(serverQuery)==dojo.toJson(this._lastServerQuery)
351 fetchHandler(this._items, request);
353 var xhrFunc = this.requestMethod.toLowerCase()=="post" ? dojo.xhrPost : dojo.xhrGet;
354 var xhrHandler = xhrFunc({url:this.url, handleAs:"json-comment-optional", content:serverQuery});
355 xhrHandler.addCallback(dojo.hitch(this, function(data){
356 data = this._filterResponse(data);
358 this._labelAttr = data.label;
360 var numRows = data.numRows || -1;
363 // Store a ref to "this" in each item, so we can simply check if an item
364 // really origins form here (idea is from ItemFileReadStore, I just don't know
365 // how efficient the real storage use, garbage collection effort, etc. is).
366 dojo.forEach(data.items,function(e){
367 this._items.push({i:e, r:this});
370 var identifier = data.identifier;
371 this._itemsByIdentity = {};
373 this._identifier = identifier;
374 for(i = 0; i < this._items.length; ++i){
375 var item = this._items[i].i;
376 var identity = item[identifier];
377 if(!this._itemsByIdentity[identity]){
378 this._itemsByIdentity[identity] = item;
380 throw new Error(this._className+": The json data as specified by: [" + this.url + "] is malformed. Items within the list have identifier: [" + identifier + "]. Value collided: [" + identity + "]");
384 this._identifier = Number;
385 for(i = 0; i < this._items.length; ++i){
386 this._items[i].n = i;
390 // TODO actually we should do the same as dojo.data.ItemFileReadStore._getItemsFromLoadedData() to sanitize
391 // (does it really sanititze them) and store the data optimal. should we? for security reasons???
392 numRows = (numRows === -1) ? this._items.length : numRows;
393 fetchHandler(this._items, request, numRows);
395 xhrHandler.addErrback(function(error){
396 errorHandler(error, request);
398 // Generate the hash using the time in milliseconds and a randon number.
399 // Since Math.randon() returns something like: 0.23453463, we just remove the "0."
400 // probably just for esthetic reasons :-).
401 this.lastRequestHash = new Date().getTime()+"-"+String(Math.random()).substring(2);
402 this._lastServerQuery = dojo.mixin({}, serverQuery);
406 _filterResponse: function(data){
408 // If the data from servers needs to be processed before it can be processed by this
409 // store, then this function should be re-implemented in subclass. This default
410 // implementation just return the data unchanged.
412 // The data received from server
416 _assertIsItem: function(/* item */ item){
418 // It throws an error if item is not valid, so you can call it in every method that needs to
419 // throw an error when item is invalid.
421 // The item to test for being contained by the store.
422 if(!this.isItem(item)){
423 throw new Error(this._className+": Invalid item argument.");
427 _assertIsAttribute: function(/* attribute-name-string */ attribute){
429 // This function tests whether the item passed in is indeed a valid 'attribute' like type for the store.
431 // The attribute to test for being contained by the store.
432 if(typeof attribute !== "string"){
433 throw new Error(this._className+": Invalid attribute argument ('"+attribute+"').");
437 fetchItemByIdentity: function(/* Object */ keywordArgs){
439 // See dojo.data.api.Identity.fetchItemByIdentity()
441 // See if we have already loaded the item with that id
442 // In case there hasn't been a fetch yet, _itemsByIdentity is null
443 // and thus a fetch will be triggered below.
444 if(this._itemsByIdentity){
445 var item = this._itemsByIdentity[keywordArgs.identity];
446 if(!(item === undefined)){
447 if(keywordArgs.onItem){
448 var scope = keywordArgs.scope?keywordArgs.scope:dojo.global;
449 keywordArgs.onItem.call(scope, {i:item, r:this});
455 // Otherwise we need to go remote
456 // Set up error handler
457 var _errorHandler = function(errorData, requestObject){
458 var scope = keywordArgs.scope?keywordArgs.scope:dojo.global;
459 if(keywordArgs.onError){
460 keywordArgs.onError.call(scope, error);
464 // Set up fetch handler
465 var _fetchHandler = function(items, requestObject){
466 var scope = keywordArgs.scope?keywordArgs.scope:dojo.global;
468 // There is supposed to be only one result
470 if(items && items.length == 1){
474 // If no item was found, item is still null and we'll
475 // fire the onItem event with the null here
476 if(keywordArgs.onItem){
477 keywordArgs.onItem.call(scope, item);
480 if(keywordArgs.onError){
481 keywordArgs.onError.call(scope, error);
487 var request = {serverQuery:{id:keywordArgs.identity}};
490 this._fetchItems(request, _fetchHandler, _errorHandler);
493 getIdentity: function(/* item */ item){
495 // See dojo.data.api.Identity.getIdentity()
496 var identifier = null;
497 if(this._identifier === Number){
498 identifier = item.n; // Number
500 identifier = item.i[this._identifier];
505 getIdentityAttributes: function(/* item */ item){
507 // See dojo.data.api.Identity.getIdentityAttributes()
508 return [this._identifier];