dojox/mvc/_DataBindingMixin (version 1.10)

Summary

Deprecated. Use dojox/mvc/at for data binding. Provides the ability for dijits or custom view components to become data binding aware.

Data binding awareness enables dijits or other view layer components to bind to locations within a client-side data model, which is commonly an instance of the dojox/mvc/StatefulModel class. A bind is a bi-directional update mechanism which is capable of synchronizing value changes between the bound dijit or other view component and the specified location within the data model, as well as changes to other properties such as "valid", "required", "readOnly" etc.

The data binding is commonly specified declaratively via the "ref" property in the "data-dojo-props" attribute value.

Consider the following simple example: 

<script>
    var model;
    require(["dijit/StatefulModel", "dojo/parser"], function(StatefulModel, parser){
        model = new StatefulModel({ data : {
            hello : "Hello World"
        }});
        parser.parse();
    });
</script>

<input id="hello1" data-dojo-type="dijit/form/TextBox"
    data-dojo-props="ref: model.hello"></input>

<input id="hello2" data-dojo-type="dijit/form/TextBox"
    data-dojo-props="ref: model.hello"></input>

In the above example, both dijit/form/TextBox instances (with IDs "hello1" and "hello2" respectively) are bound to the same reference location in the data model i.e. "hello" via the "ref" expression "model.hello". Both will have an initial value of "Hello World". Thereafter, a change in the value of either of the two textboxes will cause an update of the value in the data model at location "hello" which will in turn cause a matching update of the value in the other textbox.

See the dojox/mvc/_DataBindingMixin reference documentation for more information.

Property Summary

  • bindingThe read only value of the resolved data binding for this widget.
  • refThe value of the data binding expression passed declaratively by the developer.

Method Summary

  • _dbstartup() Tie data binding initialization into the widget lifecycle, at widget startup.
  • _getParentBindingFromDOM() Get the parent binding by traversing the DOM ancestors to find the first enclosing data-bound widget.
  • _isEqual(one,other)
  • _setupBinding(parentBinding) Calculate and set the dojo/Stateful data binding for the associated dijit or custom view component.
  • _unwatchArray(watchHandles) Given an array of watch handles, unwatch all.
  • _updateBinding(name,old,current) Set the data binding to the supplied value, which must be a dojo/Stateful node of a data model.
  • _updateChildBindings(parentBind) Update this widget's value based on the current binding and set up the bindings of all contained widgets so as to refresh any relative binding references. findWidgets does not return children of widgets so need to also update children of widgets which are not bound but may hold widgets which are.
  • _updateProperty(name,old,current,defaultValue,setPropName,setPropValue) Update a binding property of the bound widget.
  • isValid() Returns the validity of the data binding.

Properties

binding
Defined by: dojox/mvc/_DataBindingMixin

The read only value of the resolved data binding for this widget. This may be a result of resolving various relative refs along the parent axis.

ref
Defined by: dojox/mvc/_DataBindingMixin

The value of the data binding expression passed declaratively by the developer. This usually references a location within an existing datamodel and may be a relative reference based on the parent / container data binding (dot-separated string).

Methods

_dbstartup()
Defined by dojox/mvc/_DataBindingMixin

Tie data binding initialization into the widget lifecycle, at widget startup.

_getParentBindingFromDOM()
Defined by dojox/mvc/_DataBindingMixin

Get the parent binding by traversing the DOM ancestors to find the first enclosing data-bound widget.

Returns:any | undefined

The parent binding, if one exists along the DOM parent axis.

_isEqual(one,other)
Defined by dojox/mvc/_DataBindingMixin
Parameter Type Description
one undefined
other undefined
Returns:boolean
_setupBinding(parentBinding)
Defined by dojox/mvc/_DataBindingMixin

Calculate and set the dojo/Stateful data binding for the associated dijit or custom view component.

The declarative data binding reference may be specified in two ways via markup:

  • For older style documents (non validating), controls may use the "ref" attribute to specify the data binding reference (String).
  • For validating documents using the new Dojo parser, controls may specify the data binding reference (String) as the "ref" property specified in the data-dojo-props attribute.

Once the ref value is obtained using either of the above means, the binding is set up for this control and its required, readOnly etc. properties are refreshed. The data binding may be specified as a direct reference to the dojo/Stateful model node or as a string relative to its DOM parent or another widget. There are three ways in which the data binding node reference is calculated when specified as a string:

  • If an explicit parent widget is specified, the binding is calculated relative to the parent widget's data binding.
  • For any dijits that specify a data binding reference, we walk up their DOM hierarchy to obtain the first container dijit that has a data binding set up and use the reference String as a property name relative to the parent's data binding context.
  • If no such parent is found i.e. for the outermost container dijits that specify a data binding reference, the binding is calculated by treating the reference String as an expression and evaluating it to obtain the dojo/Stateful node in the datamodel.

This method calls console.warn in these two conditions:

  • The ref is an expression i.e. outermost bound dijit, but the expression evaluation fails.
  • The calculated binding turns out to not be an instance of a dojo/Stateful node.
Parameter Type Description
parentBinding undefined

The binding of this widget/view component's data-bound parent, if available.
_unwatchArray(watchHandles)
Defined by dojox/mvc/_DataBindingMixin

Given an array of watch handles, unwatch all.

Parameter Type Description
watchHandles undefined

The array of watch handles.
_updateBinding(name,old,current)
Defined by dojox/mvc/_DataBindingMixin

Set the data binding to the supplied value, which must be a dojo/Stateful node of a data model.

Applies the specified data binding to the attached widget. Loses any prior watch registrations on the previously active bind, registers the new one, updates data binds of any contained widgets and also refreshes all associated properties (valid, required etc.)

Parameter Type Description
name undefined

The name of the binding property (always "binding").
old undefined

The old dojo/Stateful binding node of the data model.
current undefined

The new dojo/Stateful binding node of the data model.
_updateChildBindings(parentBind)
Defined by dojox/mvc/_DataBindingMixin

Update this widget's value based on the current binding and set up the bindings of all contained widgets so as to refresh any relative binding references. findWidgets does not return children of widgets so need to also update children of widgets which are not bound but may hold widgets which are.

Parameter Type Description
parentBind undefined

The binding on the parent of a widget whose children may have bindings which need to be updated.
_updateProperty(name,old,current,defaultValue,setPropName,setPropValue)
Defined by dojox/mvc/_DataBindingMixin

Update a binding property of the bound widget.

Parameter Type Description
name undefined

The binding property name.
old undefined

The old value of the binding property.
current undefined

The new or current value of the binding property.
defaultValue undefined

The optional value to be applied as the current value of the binding property if the current value is null.
setPropName undefined

The optional name of a stateful property to set on the bound widget.
setPropValue undefined

The value, if an optional name is provided, for the stateful property of the bound widget.
isValid()
Defined by dojox/mvc/_DataBindingMixin

Returns the validity of the data binding.

This function is meant to provide an API bridge to the dijit API. Validity of data-bound dijits is a function of multiple concerns:

  • The validity of the value as ascertained by the data binding and constraints specified in the data model (usually semantic).
  • The validity of the value as ascertained by the widget itself based on widget constraints (usually syntactic).

In order for dijits to function correctly in data-bound environments, it is imperative that their isValid() functions assess the model validity of the data binding via the this.inherited(arguments) hierarchy and declare any values failing the test as invalid.

Returns:any | boolean

Boolean The validity associated with the data binding.

Error in the documentation? Can’t find what you are looking for? Let us know!