Two-way Data Binding - Functional and Design Specification

Glossary

Data binding is the process of tying the data in one object to another object. It provides a convenient way to pass data between the different layers of the application. Data binding requires a source property, a destination property, and a triggering event that indicates when to copy the data from the source to the destination. An object dispatches the triggering event when the source property changes.

Summary and Background

Two-way data binding, aka bidirectional data binding, refers to two components acting as the source object for the destination properties of each other. This is possible to do in Flex 3 using a combination of curly braces, <mx:Binding> statements, and calls to mx.binding.utils.BindingUtils.bindProperty(). This spec introduces a few shorthand ways to accomplish the same thing with fewer steps.

This feature has been requested by customers.

Usage Scenarios

Two-way data binding is used whenever two properties need to be tied together, for example, two text fields.

Detailed Description

A two-way data binding expression generates two binding expressions, one with the given source and destination, and the other, with the source and destination reversed. Since the destination must be a bindable property or property chain (reference value), the source must be a bindable property or property chain as well. The source and destination must be the same type.

The two ways to specify a two-way data binding are:

1. inline declaration using the syntax, @{bindable_property}
2. with MXML, <mx:Binding source="a.property" destination="b.property" twoWay="true />

In both cases, E4X statements can be used to reference bindable properties.

For the <mx:Binding> tag, because both the source and the destination must resolve to a bindable property or property chain, neither can be a one-way or two-way inline binding expression.

All the current ways of specifying bindings remain valid. This adds other alternatives to allow two-way bindings to be specified in shorthand.

API Description

• The inline syntax, @{bindable_property}, will be used for an inline declaration.
• The boolean property, twoWay, will be added to <mx:Binding>

B Features

(Not currently scheduled to be implemented for Flex 4)

• Add bindPropertyTwoWay() to mx.binding.utils to allow property chains on both sides of the binding.

The chain would be extended from bindProperty(), to accept an object that contains not just the name of, and a getter function for, but a setter function as well, for a public bindable property of the respective object.

// Returns and Array of up to two ChangeWatcher objects.
   public static function bindPropertyTwoWay(
                                obj1:Object, chain1:Object,
                                obj2:Object, chain2:Object,
                                commitOnly:Boolean = false):Array

Examples and Usage

In Flex 3, to implement two-way binding, the code would like the following:

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
      <mx:TextInput id="t1" text="{t2.text}"/>
      <mx:TextInput id="t2" text="{t1.text}"/>
  </mx:Application>

Using the new shorthand two-way binding syntax this could also be written as:

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
      <mx:TextInput id="t1" text="@{t2.text}"/>
      <mx:TextInput id="t2"/>
  </mx:Application>

A more useful example would be something like:

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
      <mx:XML id="myWebServiceResult"/>
      <mx:TextInput id="t1" text="{myWebServiceResult.foo.bar}"/>
      <mx:Binding source="t1.text" destination="myWebServiceResult.foo.bar"/>
  </mx:Application>

which becomes:

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
      <mx:XML id="myWebServiceResult"/>
      <mx:TextInput id="t1" text="@{myWebServiceResult.foo.bar}"/>
  </mx:Application>

In Flex 3, if you want to set two-way binding using the <mx:Binding> tag you need to set it twice:

<mx:Binding source="a.property" destination="b.property"/>
<mx:Binding source="b.property" destination="a.property"/>

which becomes:

<mx:Binding source="a.property" destination="b.property" twoWay="true"/>

All of the inline binding expressions below are invalid.

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
      <mx:TextInput id="t1" text="text is @{t2.text}"/>
      <mx:TextInput id="t2"/>
      <mx:TextInput id="t3" text="@{t4.text.toUpperCase()}"/>
      <mx:TextInput id="t4"/>
      <mx:Binding source="{t2.text}" destination="@{t4.text}" twoWay="true" />
  </mx:Application>

Additional Implementation Details

In order to create a complete BindableExpression, the sourceExpression, the xml line number and the destination lvalue or the destination property must be known. For two-way inline binding, there are also additional binding expression flags which need to be set so that the destination path can be generated properly.

Bindable expressions are supported in the many places, not all or which are appropriate for two-way bindable expressions.

Until bug SDK-16804 is fixed neither one-way or two-way binding will work at the top-level for <mx:XML> or <mx:XMLList>.

Prototype Work

I have prototyped enough of this to figure out how data binding is setup.

Compiler Work

no additional changes other than described above

Web Tier Compiler Impact

none

Flex Feature Dependencies

none

Backwards Compatibility

n/a

Accessibility

n/a

Performance

n/a

Globalization

new messages added to appropriate message files

Localization

Compiler Features

mxml.builder.AbstractBuilder.TwoWayBindingNotAllowedInitializer=Initializer for '${desc}': two-way data binding expression not allowed here.
mxml.builder.AbstractBuilder.TwoWayBindingNotAllowed=Inline two-way data binding expression not allowed here.
mxml.builder.AbstractBuilder.InvalidTwoWayBindingInitializer=Initializer for '${desc}': invalid two-way binding expression: ${text}.
mxml.builder.AbstractBuilder.InvalidTwoWayBinding=Invalid two-way binding expression: ${text}.

Framework Features

n/a

Issues and Recommendations

Customer asked

I saw in a promotional article that the methods for setting up 2 way binds are going to be revamped in Flex 4. Is this in the alpha release yet? If not does anyone know what is planned? Is it going to support 2 way binds on E4X statements? And most importantly, can the two way binds on E4X be setup in actionscript via BindUtil calls?

Using the inline notation, it will be possible to bind on E4X statements. Adding support for E4X statements to BindingUtils is another task which needs to be prioritized and scheduled.

Documentation

Since this is a new feature it will need to be documented.