dojox/mvc/Bind.StatefulModel (version 1.10)

dojo/Stateful

Summary

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.

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.

Usage

var foo = new Bind.StatefulModel(args);
dojox/mvc/StatefulModel
<

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.

Property Summary

  • _attrPairNamesUsed across all instances a hash to cache attribute names and their getter and setter names.
  • dataThe plain JavaScript object / data structure used to initialize this model.
  • getPlainValueOptionsAn object that defines how plain value should be created from model object.
  • getStatefulOptionsAn object that defines how model object should be created from plain object hierarchy.
  • storeThe data store from where to retrieve initial data for this model.
  • validWhether this model deems the associated data to be valid.
  • valueThe associated value (if this is a leaf node).

Method Summary

  • _changeAttrValue(name,value) Internal helper for directly changing an attribute value.
  • _commit() Commits this data model, saves the current state into data to become the saved state, so a reset will not undo any prior changes.
  • _createModel(data) Create this data model from provided input data. obj: The input for the model, as a plain JavaScript object.
  • _get(name,names) Private function that does a get based off a hash of names
  • _getAttrNames(name) Helper function for get() and set().
  • _saveToStore(store) Commit the current values to the data store: remove() any deleted entries put() any new or updated entries
  • add(name,stateful) Adds a dojo/Stateful tree represented by the given dojox/mvc/StatefulModel at the given property name.
  • commit(store) Commits this data model: Saves the current state such that a subsequent reset will not undo any prior changes.
  • get(name) Get a property on a Stateful instance.
  • postscript(params)
  • remove(name) Removes the dojo/Stateful tree at the given property name.
  • reset() Resets this data model values to its original state.
  • set(name,value) Set a property on a Stateful instance
  • splice(idx,n) Removes and then adds some elements to this array.
  • toPlainObject() Produces a plain JavaScript object representation of the data currently within this data model.
  • toString() Returns the string representation of the data currently within this data model.
  • valueOf() Returns the value representation of the data currently within this data model.
  • watch(name,callback) Watches a property for changes

Properties

_attrPairNames
Defined by: dojo/Stateful

Used across all instances a hash to cache attribute names and their getter and setter names.

data

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.

getPlainValueOptions

An object that defines how plain value should be created from model object.

getStatefulOptions

An object that defines how model object should be created from plain object hierarchy.

store

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.

valid

Whether this model deems the associated data to be valid.

value

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

Methods

_changeAttrValue(name,value)
Defined by dojo/Stateful

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.

Returns:function

Internal helper for directly changing an attribute value.

_commit()

Commits this data model, saves the current state into data to become the saved state, so a reset will not undo any prior changes.

_createModel(data)

Create this data model from provided input data. obj: The input for the model, as a plain JavaScript object.

Parameter Type Description
data Object
_get(name,names)
Defined by dojo/Stateful

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

Returns:undefined
_getAttrNames(name)
Defined by dojo/Stateful

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
Returns:undefined | object
_saveToStore(store)

Commit the current values to the data store:

  • remove() any deleted entries
  • put() any new or updated entries
Parameter Type Description
store "dojo/store/DataStore"

dojo/store/DataStore to use for this commit.

add(name,stateful)

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.

commit(store)

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.
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(name)
Defined by dojo/Stateful

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.

Returns:any | undefined

The property value on this Stateful instance.

Examples

Example 1

require(["dojo/Stateful", function(Stateful) {
    var stateful = new Stateful({foo: 3});
    stateful.get("foo") // returns 3
    stateful.foo // returns 3
});
postscript(params)
Defined by dojo/Stateful
Parameter Type Description
params Object
Optional
remove(name)

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.

reset()

Resets this data model values to its original state. Structural changes to the data model (such as adds or removes) are not restored.

set(name,value)
Defined by dojo/Stateful

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.

Returns:any | function

The function returns this dojo.Stateful instance.

Examples

Example 1

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)

splice(idx,n)

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.

Returns:dojox/mvc/StatefulArray | undefined

The removed elements.

toPlainObject()

Produces a plain JavaScript object representation of the data currently within this data model.

Returns:any | undefined

Object The plain JavaScript object representation of the data in this model.

toString()

Returns the string representation of the data currently within this data model.

Returns:any | undefined

String The object representation of the data in this model.

valueOf()

Returns the value representation of the data currently within this data model.

Returns:any | undefined

Object The object representation of the data in this model.

watch(name,callback)
Defined by dojo/Stateful

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.

Returns:any | object

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
Error in the documentation? Can’t find what you are looking for? Let us know!