analytics/webcontent/dojo17/dojox/mvc/StatefulModel.js

define("dojox/mvc/StatefulModel", [
	"dojo/_base/lang",
	"dojo/_base/array",
	"dojo/_base/declare",
	"dojo/Stateful"
], function(lang, array, declare, Stateful){
	/*=====
		declare = dojo.declare;
		Stateful = dojo.Stateful;
	=====*/

	var StatefulModel = declare("dojox.mvc.StatefulModel", [Stateful], {
		// summary:
		//		The first-class native JavaScript data model based on dojo.Stateful
		//		that wraps any data structure(s) that may be relevant for a view,
		//		a view portion, a dijit or any custom view layer component.
		//
		//  description:
		//		A data model is effectively instantiated with a plain JavaScript
		//		object which specifies the initial data structure for the model.
		//
		//		|	var struct = {
		//		|		order	: "abc123",
		//		|		shipto	: {
		//		|			address	: "123 Example St, New York, NY",
		//		|			phone	: "212-000-0000"
		//		|		},
		//		|		items : [
		//		|			{ part : "x12345", num : 1 },
		//		|			{ part : "n09876", num : 3 }
		//		|		]
		//		|	};
		//		|
		//		|	var model = dojox.mvc.newStatefulModel({ data : struct });
		//
		//		The simple example above shows an inline plain JavaScript object
		//		illustrating the data structure to prime the model with, however
		//		the underlying data may be made available by other means, such as
		//		from the results of a dojo.store or dojo.data query.
		//
		//		To deal with stores providing immediate values or Promises, a
		//		factory method for model instantiation is provided. This method
		//		will either return an immediate model or a model Promise depending
		//		on the nature of the store.
		//
		//		|	var model = dojox.mvc.newStatefulModel({ store: someStore });
		//
		//		The created data model has the following properties:
		//
		//		- It enables dijits or custom components in the view to "bind" to
		//		  data within the model. A bind creates a bi-directional update
		//		  mechanism between the bound view and the underlying data:
		//			- The data model is "live" data i.e. it maintains any updates
		//			  driven by the view on the underlying data.
		//			- The data model issues updates to portions of the view if the
		//			  data they bind to is updated in the model. For example, if two
		//			  dijits are bound to the same part of a data model, updating the
		//			  value of one in the view will cause the data model to issue an
		//			  update to the other containing the new value.
		//
		//		- The data model internally creates a tree of dojo.Stateful
		//		  objects that matches the input, which is effectively a plain
		//		  JavaScript object i.e. "pure data". This tree allows dijits or
		//		  other view components to bind to any node within the data model.
		//		  Typically, dijits with simple values bind to leaf nodes of the
		//		  datamodel, whereas containers bind to internal nodes of the
		//		  datamodel. For example, a datamodel created using the object below
		//		  will generate the dojo.Stateful tree as shown:
		//
		//		|	var model = dojox.mvc.newStatefulModel({ data : {
		//		|		prop1	: "foo",
		//		|		prop2	: {
		//		|			leaf1	: "bar",
		//		|			leaf2	: "baz"
		//		|		}
		//		|	}});
		//		|
		//		|	// The created dojo.Stateful tree is illustrated below (all nodes are dojo.Stateful objects)
		//		|	//
		//		|	//	                o  (root node)
		//		|	//	               / \
		//		|	//	 (prop1 node) o   o (prop2 node)
		//		|	//	                 / \
		//		|	//	   (leaf1 node)	o   o (leaf2 node)
		//		|	//
		//		|	// The root node is accessed using the expression "model" (the var name above). The prop1
		//		|	// node is accessed using the expression "model.prop1", the leaf2 node is accessed using
		//		|	// the expression "model.prop2.leaf2" and so on.
		//
		//		- Each of the dojo.Stateful nodes in the model may store data as well
		//		  as associated "meta-data", which includes things such as whether
		//		  the data is required or readOnly etc. This meta-data differs from
		//		  that maintained by, for example, an individual dijit in that this
		//		  is maintained by the datamodel and may therefore be affected by
		//		  datamodel-level constraints that span multiple dijits or even
		//		  additional criteria such as server-side computations.
		//
		//		- When the model is backed by a dojo.store or dojo.data query, the
		//		  client-side updates can be persisted once the client is ready to
		//		  "submit" the changes (which may include both value changes or
		//		  structural changes - adds/deletes). The datamodel allows control
		//		  over when the underlying data is persisted i.e. this can be more
		//		  incremental or batched per application needs.
		//
		//		There need not be a one-to-one association between a datamodel and
		//		a view or portion thereof. For example, multiple datamodels may
		//		back the dijits in a view. Indeed, this may be useful where the
		//		binding data comes from a number of data sources or queries, for
		//		example. Just as well, dijits from multiple portions of the view
		//		may be bound to a single datamodel.
		//
		//		Finally, requiring this class also enables all dijits to become data
		//		binding aware. The data binding is commonly specified declaratively
		//		via the "ref" property in the "data-dojo-props" attribute value.
		//
		//		To illustrate, the following is the "Hello World" of such data-bound
		//		widget examples:
		//
		//		|	<script>
		//		|		dojo.require("dojox.mvc");
		//		|		dojo.require("dojo.parser");
		//		|		var model;
		//		|		dojo.addOnLoad(function(){
		//		|			model = dojox.mvc.newStatefulModel({ data : {
		//		|				hello : "Hello World"
		//		|			}});
		//		|			dojo.parser.parse();
		//		|		}
		//		|	</script>
		//		|
		//		|	<input id="helloInput" dojoType="dijit.form.TextBox"
		//		|		ref="model.hello">
		//
		//		or
		//
		//		|	<script>
		//		|		var model;
		//		|		require(["dojox/mvc", "dojo/parser"], function(dxmvc, parser){
		//		|			model = dojox.mvc.newStatefulModel({ data : {
		//		|				hello : "Hello World"
		//		|			}});
		//		|			parser.parse();
		//		|		});
		//		|	</script>
		//		|
		//		|	<input id="helloInput" data-dojo-type="dijit.form.TextBox"
		//		|		data-dojo-props="ref: 'model.hello'">
		//
		//		Such data binding awareness for dijits is added by extending the
		//		dijit._WidgetBase class to include data binding capabilities
		//		provided by dojox.mvc._DataBindingMixin, and this class declares a
		//		dependency on dojox.mvc._DataBindingMixin.
		//
		//		The presence of a data model and the data-binding capabilities
		//		outlined above support the flexible development of a number of MVC
		//		patterns on the client. As an example, CRUD operations can be
		//		supported with minimal application code.
	
		// data: Object
		//		The plain JavaScript object / data structure used to initialize
		//		this model. At any point in time, it holds the lasted saved model
		//		state.
		//		Either data or store property must be provided.
		data: null,

		// store: dojo.store.DataStore
		//		The data store from where to retrieve initial data for this model.
		//		An optional query may also be provided along with this store.
		//		Either data or store property must be provided.
		store: null,
	
		// valid: boolean
		//		Whether this model deems the associated data to be valid.
		valid: true,

		// value: Object
		//		The associated value (if this is a leaf node). The value of
		//		intermediate nodes in the model is not defined.
		value: "",

		//////////////////////// PUBLIC METHODS / API ////////////////////////

		reset: function(){
			// summary:
			//		Resets this data model values to its original state.
			//		Structural changes to the data model (such as adds or removes)
			//		are not restored.
			if(lang.isObject(this.data) && !(this.data instanceof Date) && !(this.data instanceof RegExp)){	
				for(var x in this){
					if(this[x] && lang.isFunction(this[x].reset)){
						this[x].reset();
					}
				}
			}else{
				this.set("value", this.data);
			}
		},

		commit: function(/*"dojo.store.DataStore?"*/ store){
			// summary:
			//		Commits this data model:
			//		- Saves the current state such that a subsequent reset will not
			//		  undo any prior changes.
			//		- Persists client-side changes to the data store, if a store
			//		  has been supplied as a parameter or at instantiation.
			//	store:
			//		dojo.store.DataStore
			//		Optional dojo.store.DataStore to use for this commit, if none
			//		provided but one was provided at instantiation time, that store
			//		will be used instead.
			this._commit();
			var ds = store || this.store;
			if(ds){
				this._saveToStore(ds);
			}
		},

		toPlainObject: function(){
			// summary:
			//		Produces a plain JavaScript object representation of the data
			//		currently within this data model.
			// returns:
			//		Object
			//		The plain JavaScript object representation of the data in this
			//		model.
			var ret = {};
			var nested = false;
			for(var p in this){
				if(this[p] && lang.isFunction(this[p].toPlainObject)){
					if(!nested && typeof this.get("length") === "number"){
						ret = [];
					}
					nested = true;
					ret[p] = this[p].toPlainObject();
				}
			}
			if(!nested){
				if(this.get("length") === 0){
					ret = [];
				}else{				
					ret = this.value;
				}
			}
			return ret;
		},

		add: function(/*String*/ name, /*dojo.Stateful*/ stateful){
			// summary:
			//		Adds a dojo.Stateful tree represented by the given
			//		dojox.mvc.StatefulModel at the given property name.
			//	name:
			//		The property name to use whose value will become the given
			//		dijit.Stateful tree.
			//	stateful:
			//		The dojox.mvc.StatefulModel to insert.
			// description:
			//		In case of arrays, the property names are indices passed
			//		as Strings. An addition of such a dojo.Stateful node
			//		results in right-shifting any trailing sibling nodes.
			var n, n1, elem, elem1, save = new StatefulModel({ data : "" });
			if(typeof this.get("length") === "number" && /^[0-9]+$/.test(name.toString())){
				n = name;
				if(!this.get(n)){
					if(this.get("length") == 0 && n == 0){ // handle the empty array case
						this.set(n, stateful);
					} else {
						n1 = n-1;
						if(!this.get(n1)){
							throw new Error("Out of bounds insert attempted, must be contiguous.");
						}
						this.set(n, stateful);
					}
				}else{
					n1 = n-0+1;
					elem = stateful;
					elem1 = this.get(n1);
					if(!elem1){
						this.set(n1, elem);
					}else{
						do{
							this._copyStatefulProperties(elem1, save);
							this._copyStatefulProperties(elem, elem1);
							this._copyStatefulProperties(save, elem);
							this.set(n1, elem1); // for watchers
							elem1 = this.get(++n1);
						}while(elem1);
						this.set(n1, elem);
					}
				}
				this.set("length", this.get("length") + 1);
			}else{
				this.set(name, stateful);
			}
		},

		remove: function(/*String*/ name){
			// summary:
			//		Removes the dojo.Stateful tree at the given property name.
			//	name:
			//		The property name from where the tree will be removed.
			// description:
			//		In case of arrays, the property names are indices passed
			//		as Strings. A removal of such a dojo.Stateful node
			//		results in left-shifting any trailing sibling nodes.
			var n, elem, elem1;
			if(typeof this.get("length") === "number" && /^[0-9]+$/.test(name.toString())){
				n = name;
				elem = this.get(n);
				if(!elem){
					throw new Error("Out of bounds delete attempted - no such index: " + n);
				}else{
					this._removals = this._removals || [];
					this._removals.push(elem.toPlainObject());
					n1 = n-0+1;
					elem1 = this.get(n1);
					if(!elem1){
						this.set(n, undefined);
						delete this[n];
					}else{
						while(elem1){
							this._copyStatefulProperties(elem1, elem);
							elem = this.get(n1++);
							elem1 = this.get(n1);
						}
						this.set(n1-1, undefined);
						delete this[n1-1];
					}
					this.set("length", this.get("length") - 1);
				}
			}else{
				elem = this.get(name);
				if(!elem){
					throw new Error("Illegal delete attempted - no such property: " + name);
				}else{
					this._removals = this._removals || [];
					this._removals.push(elem.toPlainObject());
					this.set(name, undefined);
					delete this[name];
				}
			}
		},

		valueOf: function(){
			// summary:
			//		Returns the value representation of the data currently within this data model.
			// returns:
			//		Object
			//		The object representation of the data in this model.
			return this.toPlainObject();
		},

		toString: function(){
			// summary:
			//		Returns the string representation of the data currently within this data model.
			// returns:
			//		String
			//		The object representation of the data in this model.
			return this.value === "" && this.data ? this.data.toString() : this.value.toString();
		},

		//////////////////////// PRIVATE INITIALIZATION METHOD ////////////////////////

		constructor: function(/*Object*/ args){
			// summary:
			//		Instantiates a new data model that view components may bind to.
			//		This is a private constructor, use the factory method
			//		instead: dojox.mvc.newStatefulModel(args)
			//	args:
			//		The mixin properties.
			// description:
			//		Creates a tree of dojo.Stateful objects matching the initial
			//		data structure passed as input. The mixin property "data" is
			//		used to provide a plain JavaScript object directly representing
			//		the data structure.
			// tags:
			//		private
			var data = (args && "data" in args) ? args.data : this.data; 
			this._createModel(data);
		},

		//////////////////////// PRIVATE METHODS ////////////////////////

		_createModel: function(/*Object*/ obj){
			// summary:
			//		Create this data model from provided input data.
			//	obj:
			//		The input for the model, as a plain JavaScript object.
			// tags:
			//		private
			if(lang.isObject(obj) && !(obj instanceof Date) && !(obj instanceof RegExp) && obj !== null){
				for(var x in obj){
					var newProp = new StatefulModel({ data : obj[x] });
					this.set(x, newProp);
				}
				if(lang.isArray(obj)){
					this.set("length", obj.length);
				}
			}else{
				this.set("value", obj);
			}
		},

		_commit: function(){
			// summary:
			//		Commits this data model, saves the current state into data to become the saved state, 
			//		so a reset will not undo any prior changes.  
			// tags:
			//		private
			for(var x in this){
				if(this[x] && lang.isFunction(this[x]._commit)){
					this[x]._commit();
				}
			}
			this.data = this.toPlainObject();
		},

		_saveToStore: function(/*"dojo.store.DataStore"*/ store){
			// summary:
			//		Commit the current values to the data store:
			//		- remove() any deleted entries
			//		- put() any new or updated entries
			//	store:
			//		dojo.store.DataStore to use for this commit.
			// tags:
			//		private
			if(this._removals){
				array.forEach(this._removals, function(d){
					store.remove(store.getIdentity(d));
				}, this);
				delete this._removals;
			}
			var dataToCommit = this.toPlainObject();
			if(lang.isArray(dataToCommit)){
				array.forEach(dataToCommit, function(d){
					store.put(d);
				}, this);
			}else{
				store.put(dataToCommit);
			}
		},

		_copyStatefulProperties: function(/*dojo.Stateful*/ src, /*dojo.Stateful*/ dest){
			// summary:
			//		Copy only the dojo.Stateful properties from src to dest (uses
			//		duck typing).
			//	src:
			//		The source object for the copy.
			//	dest:
			//		The target object of the copy.
			// tags:
			//		private
			for(var x in src){
				var o = src.get(x);
				if(o && lang.isObject(o) && lang.isFunction(o.get)){
					dest.set(x, o);
				}
			}
		}
	});

	return StatefulModel;
});