Property A is one of the two state properties that can be connected together via an instance of the Uize.Util.PropertyAdapter class.

To set the instance and property for property A, set the value of the propertyA state property of the Uize.Util.PropertyAdapter instance to a valid property specifier (see A Basic Example).

1.1.2.1.1.1. Property A Is Primary

Property B is one of the two state properties that can be connected together via an instance of the Uize.Util.PropertyAdapter class.

To set the instance and property for property B, set the value of the propertyB state property of the Uize.Util.PropertyAdapter instance to a valid property specifier (see A Basic Example).

1.1.2.1.2.1. Property B Is Secondary

Specifying the instance and property for either property A or property B is done using a property specifier.

A property specifier can take one of several forms, as outlined below...

1.1.2.1.3.1. Property Specifier Object Form

{
  instance : instanceOBJ,     // reference to an instance of a Uize subclass
  property : propertyNameSTR  // name of a state property on the specified instance
}

1.1.2.1.3.2. Property Specifier Array Form

[
  instanceOBJ,     // reference to an instance of a Uize subclass
  propertyNameSTR  // name of a state property on the specified instance
]

1.1.2.1.3.3. Property Specifier Instance Form

instanceOBJ  // reference to an instance of a Uize subclass

1.1.2.1.3.4. Versatile Conformer

The aToB property of a value adapter object specifies a value transformer function that should be used to transform a value for property A to produce a value for property B.

The bToA property specifies a value transformer function that should be used to transform a value for property B to produce a value for property A.

A value transformer specified for either of the properties aToB or bToA should be a function that expects to receive a single parameter representing the value to be transformed, and that should return the transformed value.

EXAMPLE

{
  aToB:function (value) {return value * value},
  bToA:function (value) {return Math.sqrt (value)}
}

In the above example, a value adapter is defining a mathematical relationship between a value A and a value B, where value B is the square of value A and, conversely, where value A is the square root of value B. The aToB property specifies the function that is use to convert value A to value B, which takes a value parameter and returns its square. The bToA property specifies the function that is use to convert value B to value A, which takes a value parameter and returns its square root.

A value adapter allows the values of the two state properties that are connected through a property adapter to be encoded or serialized differently, or to have some other form of relationship to one another (such as a mathematical relationship, for example).

1.1.2.2.4.1. Value Adapter for Mathematical Relationships

Uize.Util.PropertyAdapter ({
  propertyA:numberTextInput,         // instance of Uize.Widget.TextInput
  propertyB:numberSquaredTextInput,  // instance of Uize.Widget.TextInput
  valueAdapter:{
    aToB:function (value) {return value * value},
    bToA:function (value) {return Math.sqrt (value)}
  }
});

1.1.2.2.4.2. Value Adapter for Different Encodings

Uize.Util.PropertyAdapter ({
  propertyA:colorAsHexTextInput,
  propertyB:colorAsRgbTextInput,
  valueAdapter:Uize.Color.adapter ('#hex','RGB string')
});

If a value adapter is specified for a property adapter instance, it is used whenever synchronization needs to be performed between the state properties that are connected through the property adapter.

When property A to property B synchronization is performed, the value transformer function specified by the aToB property of the value adapter object is applied to the value of property A to produce a new value for property B. Conversely, when property B to property A synchronization is performed, the value transformer function specified by the bToA property of the value adapter object is applied to the value of property B to produce a new value for property A.

Initial connection is when the two state properties are either connected for the very first time, or are reconnected after having been disconnected.

Specifically, initial connection occurs when...

Whenever initial connection occurs, the propery adapter instance performs property A to property B synchronization, and value change event handlers are wired on the instances that own the two state properties in order to ensure that the appropriate synchronization is performed when the value of either property A or property B is modified.

Disconnection is when two state properties that were previously connected through a property adapter instance become disconnected so that their values are no longer kept synchronized.

Specifically, disconnection occurs when two state properties were previously connected and then ...

Once initial connection has occured between two state properties specified for a property adapter instance, a change in the value of property A will result in the value of property B being synchronized to the new value of property A.

When the value of property B is synchronized to the value of property A, any value adapter specified for the property adapter instance is taken into account (see How a Value Adapter is Used).

1.1.2.4.1.1. Property A to Property B Synchronization on Initial Connection

Once initial connection has occured between two state properties specified for a property adapter instance, a change in the value of property B will result in the value of property A being synchronized to the new value of property B.

When the value of property A is synchronized to the value of property B, any value adapter specified for the property adapter instance is taken into account (see How a Value Adapter is Used).

The Uize.Util.PropertyAdapter class supports dynamically connecting and disconnecting the two state properties that are connected through a property adapter instance.

The properties can be connected or disconneced at any time, simply by setting the value of the property adapter instance's connected state property.

Any or both of the two state properties that are connected through a property adapter instance can be changed midstream, simply by setting the value of either or both of the property adapter instance's propertyA and propertyB state properties.

When dynamically changing the properties that are connected through a property adapter, disconnection will occur for any previously connected properties, after which initial connection will occur for the new configuration of properties.

The Uize.Util.PropertyAdapter class supports dynamically changing the value adapter that is used to transform values when performing synchronization from property A to property B, and vice versa.

Changing the value adapter that is used by a property adapter instance is as simple as setting the value of the instance's valueAdapter state property. When dynamically changing the value adapter, disconnection will occur for any previously connected properties, after which initial connection will occur for the new configuration of properties and value adapter.

Non-settling property values is a problem that could occur if a value adapter is specified where a value for property B that is generated from property A using the aToB transformer function cannot be converted back to the exact original value for property A using the bToA tranformer function, and the same is also true for transforming with property B as the original value.

The actual cause of non-settling property values could be a value adapter whose transformer functions involve mathematical calculations that suffer from insufficient precision.

1.1.2.6.1.1. Divergent Value Adapter

Uize.Util.PropertyAdapter ({
  propertyA:sliderA,
  propertyB:sliderB,
  valueAdapter:{
    aToB:function (value) {return value + 1},
    bToA:function (value) {return value + 1}
  }
});

Fortunately, the Uize.Util.PropertyAdapter class implements a simple mechanism to prevent infinite loops that could otherwise occur with non-settling property values.

In simple terms, while value change event handlers are wired for both property A and property B in order to support synchronization in both directions, a change in the value of one of the properties that is synchronized to the other property blocks the change in the value of the other property from causing synchronization back to the property that originally changed and initiated the synchronization in the first place. Simple. Nipped in the bud.

In the most simple case of connecting the same named property of two instances, without any value adapting between the properties, either of the Uize.Util.PropertyAdapter and Uize.Util.Coupler classes could be used to the same effect.

USING A COUPLER...

Uize.Util.Coupler ({
  instances:[instanceA,instanceB],
  properties:['someProperty']
});

USING A PROPERTY ADAPTER...

Uize.Util.PropertyAdapter ({
  propertyA:[instanceA,'someProperty'],
  propertyA:[instanceB,'someProperty']
});