Class: SC.Binding

A binding simply connects the properties of two objects so that whenever the value of one property changes, the other property will be changed also. You do not usually work with Binding objects directly but instead describe bindings in your class definition using something like:

valueBinding: "MyApp.someController.title"

This will create a binding from "MyApp.someController.title" to the "value" property of your object instance automatically. Now the two values will be kept in sync.

Customizing Your Bindings

In addition to synchronizing values, bindings can also perform some basic transforms on values. These transforms can help to make sure the data fed into one object always meets the expectations of that object regardless of what the other object outputs.

To customize a binding, you can use one of the many helper methods defined on SC.Binding like so:

valueBinding: SC.Binding.single("MyApp.someController.title")

This will create a binding just like the example above, except that now the binding will convert the value of MyApp.someController.title to a single object (removing any arrays) before applying it to the "value" property of your object.

You can also chain helper methods to build custom bindings like so:

valueBinding: SC.Binding.single("MyApp.someController.title").notEmpty("(EMPTY)")

This will force the value of MyApp.someController.title to be a single value and then check to see if the value is "empty" (null, undefined, empty array, or an empty string). If it is empty, the value will be set to the string "(EMPTY)".

One Way Bindings

One especially useful binding customization you can use is the oneWay() helper. This helper tells SproutCore that you are only interested in receiving changes on the object you are binding from. For example, if you are binding to a preference and you want to be notified if the preference has changed, but your object will not be changing the preference itself, you could do:

bigTitlesBinding: SC.Binding.oneWay("MyApp.preferencesController.bigTitles")

This way if the value of MyApp.preferencesController.bigTitles changes the "bigTitles" property of your object will change also. However, if you change the value of your "bigTitles" property, it will not update the preferencesController.

One way bindings are almost twice as fast to setup and twice as fast to execute because the binding only has to worry about changes to one side.

You should consider using one way bindings anytime you have an object that may be created frequently and you do not intend to change a property; only to monitor it for changes. (such as in the example above).

Adding Custom Transforms

In addition to using the standard helpers provided by SproutCore, you can also defined your own custom transform functions which will be used to convert the value. To do this, just define your transform function and add it to the binding with the transform() helper. The following example will not allow Integers less than ten. Note that it checks the value of the bindings and allows all other values to pass:

valueBinding: SC.Binding.transform(function(value, binding) {
    return ((SC.typeOf(value) === SC.T_NUMBER) && (value < 10)) ? 10 : value;
  }).from("MyApp.someController.value")

If you would like to instead use this transform on a number of bindings, you can also optionally add your own helper method to SC.Binding. This method should simply return the value of this.transform(). The example below adds a new helper called notLessThan() which will limit the value to be not less than the passed minimum:

SC.Binding.notLessThan = function(minValue) {
  return this.transform(function(value, binding) {
    return ((SC.typeOf(value) === SC.T_NUMBER) && (value < minValue)) ? minValue : value ;
  }) ;
} ;

You could specify this in your core.js file, for example. Then anywhere in your application you can use it to define bindings like so:

valueBinding: SC.Binding.from("MyApp.someController.value").notLessThan(10)

Also, remember that helpers are chained so you can use your helper along with any other helpers. The example below will create a one way binding that does not allow empty values or values less than 10:

valueBinding: SC.Binding.oneWay("MyApp.someController.value").notEmpty().notLessThan(10)

Note that the built in helper methods all allow you to pass a "from" property path so you don't have to use the from() helper to set the path. You can do the same thing with your own helper methods if you like, but it is not required.

Creating Custom Binding Templates

Another way you can customize bindings is to create a binding template. A template is simply a binding that is already partially or completely configured. You can specify this template anywhere in your app and then use it instead of designating your own custom bindings. This is a bit faster on app startup but it is mostly useful in making your code less verbose.

For example, let's say you will be frequently creating one way, not empty bindings that allow values greater than 10 throughout your app. You could create a binding template in your core.js like this:

MyApp.LimitBinding = SC.Binding.oneWay().notEmpty().notLessThan(10);

Then anywhere you want to use this binding, just refer to the template like so:

valueBinding: MyApp.LimitBinding.beget("MyApp.someController.value")

Note that when you use binding templates, it is very important that you always start by using beget() to extend the template. If you do not do this, you will end up using the same binding instance throughout your app which will lead to erratic behavior.

How to Manually Activate a Binding

All of the examples above show you how to configure a custom binding, but the result of these customizations will be a binding template, not a fully active binding. The binding will actually become active only when you instantiate the object the binding belongs to. It is useful however, to understand what actually happens when the binding is activated.

For a binding to function it must have at least a "from" property and a "to" property. The from property path points to the object/key that you want to bind from while the to path points to the object/key you want to bind to.

When you define a custom binding, you are usually describing the property you want to bind from (such as "MyApp.someController.value" in the examples above). When your object is created, it will automatically assign the value you want to bind "to" based on the name of your binding key. In the examples above, during init, SproutCore objects will effectively call something like this on your binding:

binding = this.valueBinding.beget().to("value", this) ;

This creates a new binding instance based on the template you provide, and sets the to path to the "value" property of the new object. Now that the binding is fully configured with a "from" and a "to", it simply needs to be connected to become active. This is done through the connect() method:

binding.connect() ;

Now that the binding is connected, it will observe both the from and to side and relay changes.

If you ever needed to do so (you almost never will, but it is useful to understand this anyway), you could manually create an active binding by doing the following:

SC.Binding.from("MyApp.someController.value")
   .to("MyApp.anotherObject.value")
   .connect();

You could also use the bind() helper method provided by SC.Object. (This is the same method used by SC.Object.init() to setup your bindings):

MyApp.anotherObject.bind("value", "MyApp.someController.value") ;

Both of these code fragments have the same effect as doing the most friendly form of binding creation like so:

MyApp.anotherObject = SC.Object.create({
    valueBinding: "MyApp.someController.value",

    // OTHER CODE FOR THIS OBJECT...

  }) ;

SproutCore's built in binding creation method make it easy to automatically create bindings for you. You should always use the highest-level APIs available, even if you understand how to it works underneath.

Field Summary

Class Methods

• dateTime
• displayValue
• encodeDesign

Instance Methods

• and
• applyBindingValue
• beget
• bool
• builder
• connect
• disconnect
• flushPendingChanges
• from
• fromPropertyDidChange
• isNull
• multiple
• noError
• not
• notEmpty
• notNull
• oneWay
• or
• resetTransforms
• single
• sync
• to
• toPropertyDidChange
• toString
• transform

Field Detail

Class Method Detail

valueBinding: SC.Binding.dateTime('%Y-%m-%d %H:%M:%S')
                        .from('MyApp.myController.myDateTime');

Parameters:

String format

format string

Returns:

SC.Binding this

Parameters:

coder

Instance Method Detail

Parameters:

String pathA

The first part of the conditional

String pathB

The second part of the conditional

Parameters:

String fromPath Optional

Returns:

SC.Binding new binding instance

Parameters:

String fromPath Optional

Returns:

SC.Binding this

Returns:

SC.Binding this

Returns:

SC.Binding this

Returns:

Boolean YES if changes were flushed.

Parameters:

String|Tuple propertyPath

A property path or tuple

Object root Optional

root object to use when resolving the path.

Returns:

SC.Binding this

Parameters:

Object target

The object that contains the key

String key

The name of the property which changed

Parameters:

String fromPath Optional

Returns:

SC.Binding this

Parameters:

String fromPath Optional

Returns:

SC.Binding this

Parameters:

String fromPath Optional

from path to connect.

Boolean aFlag Optional

Pass NO to allow error objects again.

Returns:

SC.Binding this

Parameters:

String fromPath Optional

Returns:

SC.Binding this

Parameters:

String fromPath

from path or null

Object placeholder Optional

Returns:

SC.Binding this

Parameters:

String fromPath

from path or null

Object placeholder Optional

Returns:

SC.Binding this

Parameters:

String fromPath Optional

from path to connect.

Boolean aFlag Optional

Pass NO to set the binding back to two-way

Returns:

SC.Binding this

Parameters:

String pathA

The first part of the conditional

String pathB

The second part of the conditional

Returns:

SC.Binding this

[] => null
  [a] => a
  [a,b,c] => Multiple Placeholder

Parameters:

String fromPath

from path or null

Object placeholder Optional

placeholder value.

Returns:

SC.Binding this

Parameters:

String|Tuple propertyPath

A property path or tuple

Object root Optional

root object to use when resolving the path.

Returns:

SC.Binding this

Parameters:

Object target

The object that contains the key

String key

The name of the property which changed

function(value) {} ;

Parameters:

Function transformFunc

the transform function.

Returns:

SC.Binding this