Documentation

A generic interface and base class for getting, setting, and watching for property changes (with getters and
setters) in a consistent manner. Classes in your model, viewmodel, or view, that have state (i.e., the object
is mutable) should implement this interface.

dojo/Stateful provides the ability to get and set named properties, including using custom accessors, in conjunction
with the ability to monitor these properties for changes. dojo/Stateful is intended to be a base class that can be
extended by other components that wish to support watchable properties. This can be very useful for creating live
bindings that utilize current property states and must react to any changes in properties. It also allows a developer to
customize the behavior of accessing the property by providing auto-magic getters and setters (accessors). Furthermore,
dojo/Stateful makes it possible to create instances using object initialization.

You can create an instance of dojo/Stateful directly, but creating a subclass is recommended:

require(["dojo/Stateful","dojo/_base/declare"],function(Stateful,declare){// Subclass dojo/Stateful:varMyClass=declare([Stateful],{foo:null,_fooGetter:function(){returnthis.foo;},_fooSetter:function(value){this.foo=value;}});// Create an instance and initialize some property values:myObj=newMyClass({foo:"baz"});// Watch changes on a property:myObj.watch("foo",function(name,oldValue,value){// Do something based on the change});// Get the value of a property:myObj.get("foo");// Set the value of a property:myObj.set("foo","bar");});

When calling the constructor, you can pass an optional Object argument. This Object will be used
to initialize the object after the constructors in the inheritance chain have executed.

Sets the value of a property. If a custom setter is defined for the property, the custom setter will be used instead.
The function takes up to two arguments:

Argument

Type

Description

name

String|Object

The name of the property to set, or a hash of key/value pairs of several properties to set.

value

Any?

Optional The value of the property to set, or if name is a hash, this argument should be
omitted.

If no custom setter is defined on an object, performing a set() will result in the property value being set directly on the object. This can be convenient, as the property can be accessed directly through standard JS syntax (object.property). But, be aware that setting arbitrary property names could lead to overriding the object’s methods (like set(), get(), etc.), which may be undesirable. If you are setting arbitrary property names, you may wish to guard against reserved method names, or prefix property names to avoid collision.

This is a helper function to be used in custom setters that is used in scenarios where calling .set() is not
appropriate, but the value of the property needs to be changed and any watches called. The typical scenario is when
there are interlinked values, where changing one value affects another value, and therefore can avoid an infinite loop
of one property changing the value of the other property. The function takes two arguments:

dojo/Stateful supports the ability to define custom accessors (getters and setters) that allow control over how
values of properties are set and retrieved. When a custom accessors is defined, a call to .get() or .set()
will auto-magically use the custom accessor instead of accessing the property directly.

A custom getter is defined in the format of _xxxGetter and a custom setter is defined in the format of _xxxSetter
where the name of the property is xxx. The name of the property is not mutated in any way. For example,
the following demonstrates several different examples of how custom accessors would be defined:

In addition, .set() has the ability to detect promise returns from a custom setter. This can be used in situations
where the customer setter will not be immediately setting the value of the attribute. For example, if a custom setter
needs to validate or post a value to a back end service via XHR before actually setting the value of the attribute. The
custom setter can return a Deferred or promise value and any watch callbacks will not be called until the promise is
resolved. If the promise is rejected, the watch will not be called. For example:

require(["dojo/Stateful","dojo/Deferred","dojo/_base/declare"],function(Stateful,Deferred,declare){varMyClass=declare([Stateful],{foo:null,_fooSetter:function(value){vard=newDeferred();// do something async and thenthis.foo=value;d.resolve(true);returnd;}});});

You should always be able to construct an object of a subclass of Stateful without any arguments:

// Create an instance and initialize some property values:varperson=newPerson();

This should give you an “empty” object, with all properties initialized to default values.

This means subclasses of Statefulcannot have mandatory properties that do not have a sensible default.
Such properties require an initial value in the constructor, which violates the requirement for a no-arguments
constructor.

You can also call the constructor with an Object argument. This is merely syntactic sugar for object initialization:

For classes in the model, viewmodel and view, that have state (i.e., are mutable),
the only good programming idiom is to have only a default, no-arguments constructor. These are exactly the kinds of
classes that would be Stateful.

First of all, you always need a no-arguments constructor, because all kinds of frameworks (e.g., the
dojo/parser) require it. General code cannot provide specific arguments for a custom constructor.

Second, for model and viewmodel objects, you almost always need to be able to construct an “empty” object.
Although semantically a firstName might be mandatory, in a UI you cannot make this an invariant of Person.
Sure, every time you get an existing object from the server, it will have a firstName, but most often the end user
should also be able to create a new person in the UI, and for that he needs to be able to start out with an “empty”
form. It makes things very difficult if you cannot bind a (view)model object to that empty form, so the (view)model
object must allow even semantically mandatory fields to be empty. Such an object might not be “valid” for sending to
the server, but it must be able to exist. A “correct” JavaScript object (i.e., the instance adheres to its invariants
and will function correctly) is not necessarily a semantically valid object. A semantically valid object should always
be a “correct” JavaScript object, though.

In a language like Java or C#, you might then add further overloaded constructor methods, for convenience, but you
quickly learn that you then have to write overloaded methods for all possible combinations, if that is possible at all.
Each of these methods carries a slightly different version of initialisation semantics, needs to have its own unit
tests, and needs to be maintained. The gain of all this extra work in a language like Java would be being able to write:

Classes you declare with dojo/_base/declare can have a postscript method that is
executed immediately after all the chained constructors in the inheritance chain have finished. In Stateful,
this method is used to do object initialization if an instance is constructed with an Object argument.

Your subclass can extend the postscript method (you probably never need to), but should not override it:

The constructor in every subclass in the inheritance chain should do its bit to deliver an “empty” instance with
default values for all properties. Most often this resorts to doing nothing at all in Dojo, so you can leave out
the constructor method entirely.

In the example, we might choose to represent empty name values by null for all 3 properties (alternatives are
undefined or the empty string ""). In a language like Java and C# this would require no work, since null
is the default value. In Dojo, the default is undefined, but you set the default in the prototype, not in the
constructor:

The only real need to do something in the constructor is when you have instance properties that are references,
that you don’t want to be null or undefined in the “empty” state. The best example is a to-many association
that you need to maintain:

Suppose our Person has siblings:

varPerson=declare([Stateful],{// ..._siblings:undefined,constructor:function(){// summary:// After construction, there are no siblings.this._siblings=[];},// ..._siblingsGetter:function(){returnthis._siblings.slice();// return Person[]},_siblingsSetter:function(){thrownewError("Cannot set the siblings directly. Use addSibling and removeSibling instead.");},addSibling:function(/*Person*/sibling){// summary:// `sibling` will be in `this.get("siblings")`.// `sibling` cannot be `null` or `undefined`, and must have the same// `lastName` as `this`.if(!sibling){thrownewError("sibling must be effective");}if(!sibling.isInstanceOf||!sibling.isInstanceOf(Person)){thrownewError("sibling must be a Person");}if(sibling.get("lastName")!==this.get("lastName")){thrownewError("sibling must have the same last name");}if(this._siblings.indexOf(sibling)<0){this._siblings.push(sibling);}},removeSibling:function(sibling){// summary:// `sibling` will not be in `this.get("siblings")`varsiblingIndex=this._siblings.indexOf(sibling);if(siblingIndex>=0){this._siblings.splice(siblingIndex,1);}}});

Here you need to create a distinct array in the constructor of each instance. Setting the prototype property to []
wouldn’t do the trick, because then all instances would share the one array in the prototype, mixing up the siblings
of all Person instances.