New feature: basic Ajax suggestion for tags and implementation of Dojo toolkit

git-svn-id: https://semanticscuttle.svn.sourceforge.net/svnroot/semanticscuttle/trunk@151 b3834d28-1941-0410-a4f8-b48e95affb8f

1 files changed, 513 insertions, 0 deletions

diff --git a/includes/js/dojox/data/QueryReadStore.js b/includes/js/dojox/data/QueryReadStore.js
new file mode 100644
index 0000000..95af166
--- /dev/null
+++ b/includes/js/dojox/data/QueryReadStore.js
@@ -0,0 +1,513 @@
+if(!dojo._hasResource["dojox.data.QueryReadStore"]){ //_hasResource checks added by build. Do not use _hasResource directly in your code.
+dojo._hasResource["dojox.data.QueryReadStore"] = true;
+dojo.provide("dojox.data.QueryReadStore");
+
+dojo.require("dojo.string");
+
+dojo.declare("dojox.data.QueryReadStore",
+	null,
+	{
+		//	summary:
+		//		This class provides a store that is mainly intended to be used
+		//		for loading data dynamically from the server, used i.e. for
+		//		retreiving chunks of data from huge data stores on the server (by server-side filtering!).
+		//		Upon calling the fetch() method of this store the data are requested from
+		//		the server if they are not yet loaded for paging (or cached).
+		//
+		//		For example used for a combobox which works on lots of data. It
+		//		can be used to retreive the data partially upon entering the
+		//		letters "ac" it returns only items like "action", "acting", etc.
+		//
+		// note:
+		//		The field name "id" in a query is reserved for looking up data
+		//		by id. This is necessary as before the first fetch, the store
+		//		has no way of knowing which field the server will declare as
+		//		identifier.
+		//
+		//	examples:
+		// |	// The parameter "query" contains the data that are sent to the server.
+		// |	var store = new dojox.data.QueryReadStore({url:'/search.php'});
+		// |	store.fetch({query:{name:'a'}, queryOptions:{ignoreCase:false}});
+		//
+		// |	// Since "serverQuery" is given, it overrules and those data are
+		// |	// sent to the server.
+		// |	var store = new dojox.data.QueryReadStore({url:'/search.php'});
+		// |	store.fetch({serverQuery:{name:'a'}, queryOptions:{ignoreCase:false}});
+		//
+		// |	<div dojoType="dojox.data.QueryReadStore"
+		// |		jsId="store2"
+		// |		url="../tests/stores/QueryReadStore.php"
+		// |		requestMethod="post"></div>
+		// |	<div dojoType="dojox.grid.data.DojoData"
+		// |		jsId="model2"
+		// |		store="store2"
+		// |		sortFields="[{attribute: 'name', descending: true}]"
+		// |		rowsPerPage="30"></div>
+		// |	<div dojoType="dojox.Grid" id="grid2"
+		// |		model="model2"
+		// |		structure="gridLayout"
+		// |		style="height:300px; width:800px;"></div>
+	
+		//
+		//	todo:
+		//		- there is a bug in the paging, when i set start:2, count:5 after an initial fetch() and doClientPaging:true
+		//		  it returns 6 elemetns, though count=5, try it in QueryReadStore.html
+		//		- add optional caching
+		//		- when the first query searched for "a" and the next for a subset of
+		//		  the first, i.e. "ab" then we actually dont need a server request, if
+		//		  we have client paging, we just need to filter the items we already have
+		//		  that might also be tooo much logic
+		
+		url:"",
+		requestMethod:"get",
+		//useCache:false,
+		
+		// We use the name in the errors, once the name is fixed hardcode it, may be.
+		_className:"dojox.data.QueryReadStore",
+		
+		// This will contain the items we have loaded from the server.
+		// The contents of this array is optimized to satisfy all read-api requirements
+		// and for using lesser storage, so the keys and their content need some explaination:
+		// 		this._items[0].i - the item itself 
+		//		this._items[0].r - a reference to the store, so we can identify the item
+		//			securly. We set this reference right after receiving the item from the
+		//			server.
+		_items:[],
+		
+		// Store the last query that triggered xhr request to the server.
+		// So we can compare if the request changed and if we shall reload 
+		// (this also depends on other factors, such as is caching used, etc).
+		_lastServerQuery:null,
+		
+		
+		// Store a hash of the last server request. Actually I introduced this
+		// for testing, so I can check if no unnecessary requests were issued for
+		// client-side-paging.
+		lastRequestHash:null,
+		
+		// summary:
+		//		By default every request for paging is sent to the server.
+		doClientPaging:false,
+	
+		// summary:
+		//		By default all the sorting is done serverside before the data is returned
+		//		which is the proper place to be doing it for really large datasets.
+		doClientSorting:false,
+	
+		// Items by identify for Identify API
+		_itemsByIdentity:null,
+		
+		// Identifier used
+		_identifier:null,
+	
+		_features: {'dojo.data.api.Read':true, 'dojo.data.api.Identity':true},
+	
+		_labelAttr: "label",
+		
+		constructor: function(/* Object */ params){
+			dojo.mixin(this,params);
+		},
+		
+		getValue: function(/* item */ item, /* attribute-name-string */ attribute, /* value? */ defaultValue){
+			//	According to the Read API comments in getValue() and exception is
+			//	thrown when an item is not an item or the attribute not a string!
+			this._assertIsItem(item);
+			if (!dojo.isString(attribute)) {
+				throw new Error(this._className+".getValue(): Invalid attribute, string expected!");
+			}
+			if(!this.hasAttribute(item, attribute)){
+				// read api says: return defaultValue "only if *item* does not have a value for *attribute*." 
+				// Is this the case here? The attribute doesn't exist, but a defaultValue, sounds reasonable.
+				if(defaultValue){
+					return defaultValue;
+				}
+				console.log(this._className+".getValue(): Item does not have the attribute '"+attribute+"'.");
+			}
+			return item.i[attribute];
+		},
+		
+		getValues: function(/* item */ item, /* attribute-name-string */ attribute){
+			this._assertIsItem(item);
+			var ret = [];
+			if(this.hasAttribute(item, attribute)){
+				ret.push(item.i[attribute]);
+			}
+			return ret;
+		},
+		
+		getAttributes: function(/* item */ item){
+			this._assertIsItem(item);
+			var ret = [];
+			for(var i in item.i){
+				ret.push(i);
+			}
+			return ret;
+		},
+	
+		hasAttribute: function(/* item */ item,	/* attribute-name-string */ attribute) {
+			//	summary: 
+			//		See dojo.data.api.Read.hasAttribute()
+			return this.isItem(item) && typeof item.i[attribute]!="undefined";
+		},
+		
+		containsValue: function(/* item */ item, /* attribute-name-string */ attribute, /* anything */ value){
+			var values = this.getValues(item, attribute);
+			var len = values.length;
+			for(var i=0; i<len; i++){
+				if(values[i]==value){
+					return true;
+				}
+			}
+			return false;
+		},
+		
+		isItem: function(/* anything */ something){
+			// Some basic tests, that are quick and easy to do here.
+			// >>> var store = new dojox.data.QueryReadStore({});
+			// >>> store.isItem("");
+			// false
+			//
+			// >>> var store = new dojox.data.QueryReadStore({});
+			// >>> store.isItem({});
+			// false
+			//
+			// >>> var store = new dojox.data.QueryReadStore({});
+			// >>> store.isItem(0);
+			// false
+			//
+			// >>> var store = new dojox.data.QueryReadStore({});
+			// >>> store.isItem({name:"me", label:"me too"});
+			// false
+			//
+			if(something){
+				return typeof something.r!="undefined" && something.r==this;
+			}
+			return false;
+		},
+		
+		isItemLoaded: function(/* anything */ something) {
+			// Currently we dont have any state that tells if an item is loaded or not
+			// if the item exists its also loaded.
+			// This might change when we start working with refs inside items ...
+			return this.isItem(something);
+		},
+	
+		loadItem: function(/* object */ args){
+			if(this.isItemLoaded(args.item)){
+				return;
+			}
+			// Actually we have nothing to do here, or at least I dont know what to do here ...
+		},
+	
+		fetch:function(/* Object? */ request){
+			//	summary:
+			//		See dojo.data.util.simpleFetch.fetch() this is just a copy and I adjusted
+			//		only the paging, since it happens on the server if doClientPaging is
+			//		false, thx to http://trac.dojotoolkit.org/ticket/4761 reporting this.
+			//		Would be nice to be able to use simpleFetch() to reduce copied code,
+			//		but i dont know how yet. Ideas please!
+			request = request || {};
+			if(!request.store){
+				request.store = this;
+			}
+			var self = this;
+		
+			var _errorHandler = function(errorData, requestObject){
+				if(requestObject.onError){
+					var scope = requestObject.scope || dojo.global;
+					requestObject.onError.call(scope, errorData, requestObject);
+				}
+			};
+		
+			var _fetchHandler = function(items, requestObject, numRows){
+				var oldAbortFunction = requestObject.abort || null;
+				var aborted = false;
+				
+				var startIndex = requestObject.start?requestObject.start:0;
+				if (self.doClientPaging==false) {
+					// For client paging we dont need no slicing of the result.
+					startIndex = 0;
+				}
+				var endIndex   = requestObject.count?(startIndex + requestObject.count):items.length;
+		
+				requestObject.abort = function(){
+					aborted = true;
+					if(oldAbortFunction){
+						oldAbortFunction.call(requestObject);
+					}
+				};
+		
+				var scope = requestObject.scope || dojo.global;
+				if(!requestObject.store){
+					requestObject.store = self;
+				}
+				if(requestObject.onBegin){
+					requestObject.onBegin.call(scope, numRows, requestObject);
+				}
+				if(requestObject.sort && this.doClientSorting){
+					items.sort(dojo.data.util.sorter.createSortFunction(requestObject.sort, self));
+				}
+				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);   
+				}
+			};
+			this._fetchItems(request, _fetchHandler, _errorHandler);
+			return request;	// Object
+		},
+	
+		getFeatures: function(){
+			return this._features;
+		},
+	
+		close: function(/*dojo.data.api.Request || keywordArgs || null */ request){
+			// I have no idea if this is really needed ... 
+		},
+	
+		getLabel: function(/* item */ item){
+			//	summary:
+			//		See dojo.data.api.Read.getLabel()
+			if(this._labelAttr && this.isItem(item)){
+				return this.getValue(item, this._labelAttr); //String
+			}
+			return undefined; //undefined
+		},
+	
+		getLabelAttributes: function(/* item */ item){
+			//	summary:
+			//		See dojo.data.api.Read.getLabelAttributes()
+			if(this._labelAttr){
+				return [this._labelAttr]; //array
+			}
+			return null; //null
+		},
+		
+		_fetchItems: function(request, fetchHandler, errorHandler){
+			//	summary:
+			// 		The request contains the data as defined in the Read-API.
+			// 		Additionally there is following keyword "serverQuery".
+			//
+			//	The *serverQuery* parameter, optional.
+			//		This parameter contains the data that will be sent to the server.
+			//		If this parameter is not given the parameter "query"'s
+			//		data are sent to the server. This is done for some reasons:
+			//		- to specify explicitly which data are sent to the server, they
+			//		  might also be a mix of what is contained in "query", "queryOptions"
+			//		  and the paging parameters "start" and "count" or may be even
+			//		  completely different things.
+			//		- don't modify the request.query data, so the interface using this
+			//		  store can rely on unmodified data, as the combobox dijit currently
+			//		  does it, it compares if the query has changed
+			//		- request.query is required by the Read-API
+			//
+			// 		I.e. the following examples might be sent via GET:
+			//		  fetch({query:{name:"abc"}, queryOptions:{ignoreCase:true}})
+			//		  the URL will become:   /url.php?name=abc
+			//
+			//		  fetch({serverQuery:{q:"abc", c:true}, query:{name:"abc"}, queryOptions:{ignoreCase:true}})
+			//		  the URL will become:   /url.php?q=abc&c=true
+			//		  // The serverQuery-parameter has overruled the query-parameter
+			//		  // but the query parameter stays untouched, but is not sent to the server!
+			//		  // The serverQuery contains more data than the query, so they might differ!
+			//
+	
+			var serverQuery = request.serverQuery || request.query || {};
+			//Need to add start and count
+			if(!this.doClientPaging){
+				serverQuery.start = request.start || 0;
+				// Count might not be sent if not given.
+				if (request.count) {
+					serverQuery.count = request.count;
+				}
+			}
+			if(!this.doClientSorting){
+				if(request.sort){
+					var sort = request.sort[0];
+					if(sort && sort.attribute){
+						var sortStr = sort.attribute;
+						if(sort.descending){
+							sortStr = "-" + sortStr;
+						}
+						serverQuery.sort = sortStr;
+					}
+				}
+			}
+			// Compare the last query and the current query by simply json-encoding them,
+			// so we dont have to do any deep object compare ... is there some dojo.areObjectsEqual()???
+			if(this.doClientPaging && this._lastServerQuery!==null &&
+				dojo.toJson(serverQuery)==dojo.toJson(this._lastServerQuery)
+				){
+				fetchHandler(this._items, request);
+			}else{
+				var xhrFunc = this.requestMethod.toLowerCase()=="post" ? dojo.xhrPost : dojo.xhrGet;
+				var xhrHandler = xhrFunc({url:this.url, handleAs:"json-comment-optional", content:serverQuery});
+				xhrHandler.addCallback(dojo.hitch(this, function(data){
+					data = this._filterResponse(data);
+					if (data.label){
+						this._labelAttr = data.label;
+					}
+					var numRows = data.numRows || -1;
+	
+					this._items = [];
+					// Store a ref to "this" in each item, so we can simply check if an item
+					// really origins form here (idea is from ItemFileReadStore, I just don't know
+					// how efficient the real storage use, garbage collection effort, etc. is).
+					dojo.forEach(data.items,function(e){ 
+						this._items.push({i:e, r:this}); 
+					},this); 
+					
+					var identifier = data.identifier;
+					this._itemsByIdentity = {};
+					if(identifier){
+						this._identifier = identifier;
+						for(i = 0; i < this._items.length; ++i){
+							var item = this._items[i].i;
+							var identity = item[identifier];
+							if(!this._itemsByIdentity[identity]){
+								this._itemsByIdentity[identity] = item;
+							}else{
+								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 + "]");
+							}
+						}
+					}else{
+						this._identifier = Number;
+						for(i = 0; i < this._items.length; ++i){
+							this._items[i].n = i;
+						}
+					}
+					
+					// TODO actually we should do the same as dojo.data.ItemFileReadStore._getItemsFromLoadedData() to sanitize
+					// (does it really sanititze them) and store the data optimal. should we? for security reasons???
+					numRows = (numRows === -1) ? this._items.length : numRows;
+					fetchHandler(this._items, request, numRows);
+				}));
+				xhrHandler.addErrback(function(error){
+					errorHandler(error, request);
+				});
+				// Generate the hash using the time in milliseconds and a randon number.
+				// Since Math.randon() returns something like: 0.23453463, we just remove the "0."
+				// probably just for esthetic reasons :-).
+				this.lastRequestHash = new Date().getTime()+"-"+String(Math.random()).substring(2);
+				this._lastServerQuery = dojo.mixin({}, serverQuery);
+			}
+		},
+		
+		_filterResponse: function(data){
+			//	summary:
+			//		If the data from servers needs to be processed before it can be processed by this
+			//		store, then this function should be re-implemented in subclass. This default 
+			//		implementation just return the data unchanged.
+			//	data:
+			//		The data received from server
+			return data;
+		},
+	
+		_assertIsItem: function(/* item */ item){
+			//	summary:
+			//		It throws an error if item is not valid, so you can call it in every method that needs to
+			//		throw an error when item is invalid.
+			//	item: 
+			//		The item to test for being contained by the store.
+			if(!this.isItem(item)){
+				throw new Error(this._className+": Invalid item argument.");
+			}
+		},
+	
+		_assertIsAttribute: function(/* attribute-name-string */ attribute){
+			//	summary:
+			//		This function tests whether the item passed in is indeed a valid 'attribute' like type for the store.
+			//	attribute: 
+			//		The attribute to test for being contained by the store.
+			if(typeof attribute !== "string"){ 
+				throw new Error(this._className+": Invalid attribute argument ('"+attribute+"').");
+			}
+		},
+	
+		fetchItemByIdentity: function(/* Object */ keywordArgs){
+			//	summary: 
+			//		See dojo.data.api.Identity.fetchItemByIdentity()
+	
+			// See if we have already loaded the item with that id
+			// In case there hasn't been a fetch yet, _itemsByIdentity is null
+			// and thus a fetch will be triggered below.
+			if(this._itemsByIdentity){
+				var item = this._itemsByIdentity[keywordArgs.identity];
+				if(!(item === undefined)){
+					if(keywordArgs.onItem){
+						var scope =  keywordArgs.scope?keywordArgs.scope:dojo.global;
+						keywordArgs.onItem.call(scope, {i:item, r:this});
+					}
+					return;
+				}
+			}
+	
+			// Otherwise we need to go remote
+			// Set up error handler
+			var _errorHandler = function(errorData, requestObject){
+				var scope =  keywordArgs.scope?keywordArgs.scope:dojo.global;
+				if(keywordArgs.onError){
+					keywordArgs.onError.call(scope, error);
+				}
+			};
+			
+			// Set up fetch handler
+			var _fetchHandler = function(items, requestObject){
+				var scope =  keywordArgs.scope?keywordArgs.scope:dojo.global;
+				try{
+					// There is supposed to be only one result
+					var item = null;
+					if(items && items.length == 1){
+						item = items[0];
+					}
+					
+					// If no item was found, item is still null and we'll
+					// fire the onItem event with the null here
+					if(keywordArgs.onItem){
+						keywordArgs.onItem.call(scope, item);
+					}
+				}catch(error){
+					if(keywordArgs.onError){
+						keywordArgs.onError.call(scope, error);
+					}
+				}
+			};
+			
+			// Construct query
+			var request = {serverQuery:{id:keywordArgs.identity}};
+			
+			// Dispatch query
+			this._fetchItems(request, _fetchHandler, _errorHandler);
+		},
+		
+		getIdentity: function(/* item */ item){
+			//	summary: 
+			//		See dojo.data.api.Identity.getIdentity()
+			var identifier = null;
+			if(this._identifier === Number){
+				identifier = item.n; // Number
+			}else{
+				identifier = item.i[this._identifier];
+			}
+			return identifier;
+		},
+		
+		getIdentityAttributes: function(/* item */ item){
+			//	summary:
+			//		See dojo.data.api.Identity.getIdentityAttributes()
+			return [this._identifier];
+		}
+	}
+);
+
+}