Deprecated. Use dojox/mvc/getStateful, dojox/mvc/getPlainValue, dojox/mvc/StatefulArray or one of the dojox/mvc/*RefControllers instead. 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.
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 = mvc.newStatefulModel({ store: someStore });
The created data model has the following properties:
a) The data model is "live" data i.e. it maintains any updates driven by the view on the underlying data.
b) 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.
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> var model; require(["dojox/mvc", "dojo/parser"], function(mvc, parser){ model = 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.
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.
>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. >Parameter | Type | Description |
---|---|---|
args | Object | The mixin properties. |
See the dojox/mvc/Bind.StatefulModel reference documentation for more information.
Used across all instances a hash to cache attribute names and their getter and setter names.
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.
An object that defines how plain value should be created from model object.
An object that defines how model object should be created from plain object hierarchy.
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.
The associated value (if this is a leaf node). The value of intermediate nodes in the model is not defined.
Internal helper for directly changing an attribute value.
Directly change the value of an attribute on an object, bypassing any accessor setter. Also handles the calling of watch and emitting events. It is designed to be used by descendant class when there are two values of attributes that are linked, but calling .set() is not appropriate.
Parameter | Type | Description |
---|---|---|
name | String | The property to set. |
value | Mixed | The value to set in the property. |
Internal helper for directly changing an attribute value.
Commits this data model, saves the current state into data to become the saved state, so a reset will not undo any prior changes.
Create this data model from provided input data. obj: The input for the model, as a plain JavaScript object.
Parameter | Type | Description |
---|---|---|
data | Object |
Private function that does a get based off a hash of names
Parameter | Type | Description |
---|---|---|
name | undefined | |
names | undefined | Hash of names of custom attributes |
Helper function for get() and set(). Caches attribute name values so we don't do the string ops every time.
Parameter | Type | Description |
---|---|---|
name | undefined |
Commit the current values to the data store:
Parameter | Type | Description |
---|---|---|
store | "dojo/store/DataStore" | dojo/store/DataStore to use for this commit. |
Adds a dojo/Stateful tree represented by the given dojox/mvc/StatefulModel at the given property name.
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.
Parameter | Type | Description |
---|---|---|
name | String | The property name to use whose value will become the given dijit/Stateful tree. |
stateful | dojo/Stateful | The dojox/mvc/StatefulModel to insert. |
Commits this data model:
Parameter | Type | Description |
---|---|---|
store | "dojo/store/DataStore?" | 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. |
Get a property on a Stateful instance.
Get a named property on a Stateful object. The property may potentially be retrieved via a getter method in subclasses. In the base class this just retrieves the object's property.
Parameter | Type | Description |
---|---|---|
name | String | The property to get. |
The property value on this Stateful instance.
require(["dojo/Stateful", function(Stateful) { var stateful = new Stateful({foo: 3}); stateful.get("foo") // returns 3 stateful.foo // returns 3 });
Removes the dojo/Stateful tree at the given property name.
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.
Parameter | Type | Description |
---|---|---|
name | String | The property name from where the tree will be removed. |
Resets this data model values to its original state. Structural changes to the data model (such as adds or removes) are not restored.
Set a property on a Stateful instance
Sets named properties on a stateful object and notifies any watchers of the property. A programmatic setter may be defined in subclasses.
Parameter | Type | Description |
---|---|---|
name | String | The property to set. |
value | Object | The value to set in the property. |
The function returns this dojo.Stateful instance.
require(["dojo/Stateful", function(Stateful) { var stateful = new Stateful(); stateful.watch(function(name, oldValue, value){ // this will be called on the set below } stateful.set(foo, 5);
set() may also be called with a hash of name/value pairs, ex:
stateful.set({ foo: "Howdy", bar: 3 }); });
This is equivalent to calling set(foo, "Howdy") and set(bar, 3)
Removes and then adds some elements to this array. Updates the removed/added elements, as well as the length, as stateful.
Parameter | Type | Description |
---|---|---|
idx | Number | The index where removal/addition should be done. |
n | Number | How many elements to be removed at idx. |
The removed elements.
Produces a plain JavaScript object representation of the data currently within this data model.
Object The plain JavaScript object representation of the data in this model.
Returns the string representation of the data currently within this data model.
String The object representation of the data in this model.
Returns the value representation of the data currently within this data model.
Object The object representation of the data in this model.
Watches a property for changes
Parameter | Type | Description |
---|---|---|
name | String |
Optional Indicates the property to watch. This is optional (the callback may be the only parameter), and if omitted, all the properties will be watched |
callback | Function | The function to execute when the property changes. This will be called after the property has been changed. The callback will be called with the |this| set to the instance, the first argument as the name of the property, the second argument as the old value and the third argument as the new value. |
An object handle for the watch. The unwatch method of this object can be used to discontinue watching this property:
var watchHandle = obj.watch("foo", callback); watchHandle.unwatch(); // callback won't be called now