Adds a transform to format the DateTime value to a String value according to the passed format string.

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

Defined in: datetime.js.

Defined in: binding.js.

Defined in: binding.js.

Adds a transform that returns the logical 'AND' of all the values at the provided paths. This is a quick and useful way to bind a Boolean property to two or more other Boolean properties.

For example, imagine that we wanted to only enable a deletion button when an item in a list is selected and the current user is allowed to delete items. If these two values are set on controllers respectively at MyApp.itemsController.hasSelection and MyApp.userController.canDelete. We could do the following,

deleteButton: SC.ButtonView.design({

  // Action & target for the button.
  action: 'deleteSelectedItem',
  target: MyApp.statechart,

  // Whether the list has a selection or not.
  listHasSelectionBinding: SC.Binding.oneWay('MyApp.itemsController.hasSelection'),

  // Whether the user can delete items or not.
  userCanDeleteBinding: SC.Binding.oneWay('MyApp.userController.canDelete'),

  // Note: Only enable when the list has a selection and the user is allowed!
  isEnabled: function () {
    return this.get('listHasSelection') && this.get('userCanDelete');
  }.property('listHasSelection', 'userCanDelete').cacheable()

})

However, this would be much simpler to write by using the and binding transform like so,

deleteButton: SC.ButtonView.design({

  // Action & target for the button.
  action: 'deleteSelectedItem',
  target: MyApp.statechart,

  // Note: Only enable when the list has a selection and the user is allowed!
  isEnabledBinding: SC.Binding.and('MyApp.itemsController.hasSelection', 'MyApp.userController.canDelete')

})

Note:* the transform acts strictly as a one-way binding, working only in the one direction.

Adds a transform to convert the value to a bool value. If the value is an array it will return YES if array is not empty. If the value is a string it will return YES if the string is not empty.

Attempts to connect this binding instance so that it can receive and relay changes. This method will raise an exception if you have not set the from/to properties yet.

Disconnects the binding instance. Changes will no longer be relayed. You will not usually need to call this method.

Adds a transform that will return YES if the value is equal to equalValue, NO otherwise.

isVisibleBinding: SC.Binding.oneWay("MyApp.someController.title").equalTo(comparisonValue)

Or:

isVisibleBinding: SC.Binding.equalTo("MyApp.someController.title", comparisonValue)

This will set "from" property path to the specified value. It will not attempt to resolve this property path to an actual object/property tuple until you connect the binding.

The binding will search for the property path starting at the root level unless you specify an alternate root object as the second parameter to this method. Alternatively, you can begin your property path with either "." or "*", which will use the root object of the to side be default. This special behavior is used to support the high-level API provided by SC.Object.

Adds a transform that will always return an integer Number value. Null and undefined values will return 0 while String values will be transformed using the parseInt method (according to the radix) and Boolean values will be 1 or 0 if true or false accordingly. Other edge cases like NaN or other non-Numbers will also return 0.

Example results,

• null => 0
• undefined => 0
• '123' => 123
• true => 1
• {} => 0

Adds a transform that will return YES if the value is null or undefined, NO otherwise.

Adds a transform that aggregates through a given function the values at the provided paths. The given function is called whenever any of the values are updated. This is a quick way to aggregate multiple properties into a single property value.

For example, to concatenate two properties 'MyApp.groupController.name' and 'MyApp.userController.fullName', we could do the following,

currentGroupUserLabel: SC.LabelView.extend({

  // The group name (may be null).
  groupNameBinding: SC.Binding.oneWay('MyApp.groupController.name'),

  // The user full name (may be null).
  userFullNameBinding: SC.Binding.oneWay('MyApp.userController.fullName'),

  // Ex. Returns one of "", "Selected Group", or "Selected Group: Selected User"
  value: function () {
    var groupName = this.get('groupName'),
        userFullName = this.get('userFullName');

    if (SC.none(userFullName)) {
      if (SC.none(groupName)) {
        return ''; // No group and no user.
      } else {
        return groupName; // Just a group.
      }
    } else {
      return '%@: %@'.fmt(groupName, userFullName); // Group and user.
    }
  }.property('groupName', 'userFullName').cacheable()

})

However, this is simpler (ex. 86 fewer characters) to write by using the mix binding transform like so,

currentGroupUserLabel: SC.LabelView.extend({

  // Ex. Returns one of "", "Selected Group", or "Selected Group: Selected User"
  valueBinding: SC.Binding.mix(
    'MyApp.groupController.name', // The group name (may be null).
    'MyApp.userController.fullName', // The user full name (may be null).

    // Aggregate function. The arguments match the bound property values above.
    function (groupName, userFullName) {
      if (SC.none(userFullName)) {
        if (SC.none(groupName)) {
          return ''; // No group and no user.
        } else {
          return groupName; // Just a group.
        }
      } else {
        return '%@: %@'.fmt(groupName, userFullName); // Group and user.
      }
    })

})

Note:* the number of parameters of mixFunction should match the number of paths provided. Note:* the transform acts strictly as a one-way binding, working only in the one direction.

Adds a transform that will convert the passed value to an array. If the value is null or undefined, it will be converted to an empty array.

Specifies that the binding should not return error objects. If the value of a binding is an Error object, it will be transformed to a null value instead.

Note that this is not a transform function since it will be called at the end of the transform chain.

Adds a transform to convert the value to the inverse of a bool value. This uses the same transform as bool() but inverts it.

Adds a transform that will return the placeholder value if the value is null, undefined, an empty array or an empty string. See also notNull().

Adds a transform that will return the placeholder value if the value is null or undefined. Otherwise it will pass through untouched. See also notEmpty().

Configures the binding as one way. A one-way binding will relay changes on the "from" side to the "to" side, but not the other way around. This means that if you change the "to" side directly, the "from" side will not be updated, and may have a different value.

Adds a transform that returns the logical 'OR' of all the values at the provided paths. This is a quick and useful way to bind a Boolean property to two or more other Boolean properties.

For example, imagine that we wanted to show a button when one or both of two values are present. If these two values are set on controllers respectively at MyApp.profileController.hasDisplayName and MyApp.profileController.hasFullName. We could do the following,

saveButton: SC.ButtonView.design({

  // Action & target for the button.
  action: 'saveProfile',
  target: MyApp.statechart,

  // Whether the profile has a displayName or not.
  profileHasDisplayNameBinding: SC.Binding.oneWay('MyApp.profileController.hasDisplayName'),

  // Whether the profile has a fullName or not.
  profileHasFullNameBinding: SC.Binding.oneWay('MyApp.profileController.hasFullName'),

  // Note: Only show when the profile has a displayName or a fullName or both!
  isVisible: function () {
    return this.get('profileHasDisplayName') || this.get('profileHasFullName');
  }.property('profileHasDisplayName', 'profileHasFullName').cacheable()

})

However, this would be much simpler to write by using the or binding transform like so,

saveButton: SC.ButtonView.design({

  // Action & target for the button.
  action: 'saveProfile',
  target: MyApp.statechart,

  // Note: Only show when the profile has a displayName or a fullName or both!
  isVisibleBinding: SC.Binding.or('MyApp.profileController.hasDisplayName', 'MyApp.profileController.hasFullName')

})

Note:* the transform acts strictly as a one-way binding, working only in the one direction.

Resets the transforms for the binding. After calling this method the binding will no longer transform values. You can then add new transforms as needed.

Adds a transform to the chain that will allow only single values to pass. This will allow single values, nulls, and error values to pass through. If you pass an array, it will be mapped as so:

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

You can pass in an optional multiple placeholder or it will use the default.

Note that this transform will only happen on forwarded valued. Reverse values are send unchanged.

Adds a transform that will always return a String value. Null and undefined values will return an empty string while all other non-String values will be transformed using the toString method.

Example results,

• null => ''
• undefined => ''
• 123 => '123'
• true => 'true'
• {} => '[object Object]' (i.e. x = {}; return x.toString())

Calling this method on a binding will cause it to check the value of the from side of the binding matches the current expected value of the binding. If not, it will relay the change as if the from side's value has just changed.

This method is useful when you are dynamically connecting bindings to a network of objects that may have already been initialized. Otherwise you should not need to call this method.

This will set the "to" property path to the specified value. It will not attempt to reoslve this property path to an actual object/property tuple until you connect the binding.

If you are using the convenience format fooBinding, for example isVisibleBinding, you do not need to call this method, as the to property path will be generated for you when its object is created.

Adds the specified transform function to the array of transform functions.

The function you pass must have the following signature:

function (value) {};

or:

function (value, binding) {};

It must return either the transformed value or an error object.

Transform functions are chained, so they are called in order. If you are extending a binding and want to reset its transforms, you can call resetTransform() first.