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.

Location Two-way Data Binding Supported
property text Yes
style text No
effect text No
<Model>{bindable_expression}</Model> Yes
<mx:XML> top-level* or nodes or attributes Yes
<mx:XMLList> top-level* or nodes or attributes Yes
in <mx:request> for <mx:HttpService>, <mx:RemoteObject> and <mx:WebService> No
in <mx:arguments> for <mx:RemoteObject> No
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.

You must be logged in to comment.

Comments (5)

 

  1. Mar 05, 2009

    Christophe JOLIF says:

    How 2 way binding can work with type conversion. With 1 way I could (can) do: ...

    How 2 way binding can work with type conversion.

    With 1 way I could (can) do:

    <?xml version="1.0" encoding="utf-8"?>
    <FxApplication xmlns="http://ns.adobe.com/mxml/2009">
    <layout>
    <VerticalLayout/>
    </layout>
    <FxHSlider id="slider" value="{Number(field.text)}"/>
    <FxTextInput id="field" text="{String(slider.value)}"/>
    </FxApplication>

    Can we have a syntax to achieve this with 2-way binding? (or there is one and I missed it).

    1. Mar 06, 2009

      Matt Chotin says:

      This was also a B feature that we're not going to have time to implement. We'd ...

      This was also a B feature that we're not going to have time to implement. We'd welcome the potential contribution though! We are also thinking about different ways for data to flow through an application as part of our long-term planning, that might be a little more formal than binding, but allow this kind of flexibility.

  2. Jun 21, 2009

    s r says:

    This topic looks great. For more Flex 4 and Flash Builder 4 information, see th...

    This topic looks great. For more Flex 4 and Flash Builder 4 information, see this new course 'Flex 4 Top 10 Features' taught by Rivello Multimedia Consulting. Sign up or request it come to your town today! http://www.blog.rivello.org/?p=324

  3. Feb 07, 2010

    Lohandus Ribeiro says:

    First, sorry for my english. Two-way Data Binding is an incredible feature, but...

    First, sorry for my english.

    Two-way Data Binding is an incredible feature, but as the Christophe Jolife, I stumbled on the variable types problem.

    I solved this (at least for me) with the following custom component:

     
import flash.events.Event;
import spark.components.TextInput;

[DefaultProperty("number")]

public class TextInputNumber extends TextInput
{
	private var _number:Number;

	public function TextInputNumber()
	{
		super();
		addEventListener("change", changeHandler);
	}

	private function changeHandler(event:Event):void
	{
		_number = Number(super.text);
		dispatchEvent(new Event("numberChanged"));
	}
	
	public function set number(value:Number):void
	{
		_number = value;
		super.text = isNaN(_number) ? "" : String(_number);
		dispatchEvent(new Event("numberChanged"));
	}
	
	[Bindable("numberChanged")]
	public function get number():Number
	{
		return _number;
	}
}

    Use:

     
<my:TextInputNumber number="@{product.prince}" />

    You can improve this component by adding numerical filter and decimal precision, but for this example is enough.
    I have little experience with Flex, so sorry for some bad coding.

  4. Feb 10, 2011

    Andy Fleming says:

    I battled with this for a while, then came up with this: <s:TextInput id=...

    I battled with this for a while, then came up with this:

    <s:TextInput id="NumberInput" change="myObject.numberField = Number(NumberInput.text)" text="{myObject.numberField.toString()}"/>

    It seems to work, but I'm not sure how proper it is - the custom component solution from Lohandus Ribeiro above is probably nicer.