class sap.ui.model.CompositeBinding

Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/model/CompositeBinding
Application Component: CA-UI5-COR

Combines multiple property bindings (called 'parts') into a single one.

A CompositeBinding combines the values from all its binding parts (each an instance of PropertyBinding), either by calling a formatter function or by involving a composite type. When a formatter function is used, the composite binding is automatically limited to OneWay mode. When a type is used, the binding can also operate in TwoWay mode.

Higher layers of the framework derive composite bindings from easy-to-write string representations (the following features require complex binding syntax, e.g. data-sap-ui-bindingSyntax="complex"):

XML views, for example, convert attribute values with nested curly braces like

  text="{fullname} <{email}>"
into a composite binding with two parts (one property binding for property "fullname" and one for property "email") and with a generic formatter function that injects the values of the parts into the string literal "{0} <{1}>" accordingly.

Similarly, expression bindings are parsed and converted into composite bindings, too. The formatter function is created by the framework and executes the calculations as defined by the expression string, taking the values from the binding parts as input.

Note: A nesting of composite bindings is currently not supported (albeit being helpful).


Constructor

Constructor for CompositeBinding.

new sap.ui.model.CompositeBinding()

Methods Overview

Method Description
attachAggregatedDataStateChange

Attaches event handler fnFunction to the AggregatedDataStateChange event of this sap.ui.model.CompositeBinding.

The AggregatedDataStateChange event is fired asynchronously, meaning that the DataState object given as parameter of the event contains all changes that were applied to the DataState in the running thread.

attachChange

Attaches event handler fnFunction to the change event of this sap.ui.model.CompositeBinding.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.model.CompositeBinding itself.

attachDataStateChange

Attaches event handler fnFunction to the DataStateChange event of this sap.ui.model.CompositeBinding.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.model.CompositeBinding itself.

detachAggregatedDataStateChange

Detaches event handler fnFunction from the AggregatedDataStateChange event of this sap.ui.model.CompositeBinding.

detachChange

Detaches event handler fnFunction from the change event of this sap.ui.model.CompositeBinding.

detachDataStateChange

Detaches event handler fnFunction from the DataStateChange event of this sap.ui.model.CompositeBinding.

sap.ui.model.CompositeBinding.extend

Creates a new subclass of class sap.ui.model.CompositeBinding with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.model.PropertyBinding.extend.

getBindings

Returns the property bindings contained in this composite binding.

getExternalValue

Returns the current external value of the bound target which is formatted via a type or formatter function.

getInternalValue

Returns the current internal value of the bound target which is an array of the internal (JS native) values of nested bindings.

sap.ui.model.CompositeBinding.getMetadata

Returns a metadata object for class sap.ui.model.CompositeBinding.

getRawValue

Returns the current raw value of the bound target which is an array of the raw (model) values of nested bindings.

getValue

Returns the raw values of the property bindings in an array.

initialize

Initialize the binding. The method should be called when creating a binding. The default implementation calls checkUpdate(true). Prevent checkUpdate to be triggered while initializing nested bindings, it is sufficient to call checkUpdate when all nested bindings are initialized.

resume

Suspends the binding update. No change events will be fired.

A refresh call with bForceUpdate set to true will also update the binding and fire a change in suspended mode. Special operations on bindings, which require updates to work properly (as paging or filtering in list bindings) will also update and cause a change event although the binding is suspended.

setExternalValue

Sets the external value of a composite binding. If no CompositeType is assigned to the binding, the default implementation assumes a space-separated list of values. This will cause the setValue to be called for each nested binding, except for undefined values in the array.

setInternalValue

Sets the internal value of the bound target. Parameter must be an array of values matching the internal (JS native) types of nested bindings.

setRawValue

Sets the raw value of the bound target. Parameter must be an array of values matching the raw (model) types of nested bindings.

setType

Sets the optional type and internal type for the binding. The type and internal type are used to do the parsing/formatting correctly. The internal type is the property type of the element which the value is formatted to.

setValue

Sets the values. This will cause the setValue to be called for each nested binding, except for undefined values in the array.

suspend

Suspends the binding update. No change events will be fired.

A refresh call with bForceUpdate set to true will also update the binding and fire a change in suspended mode. Special operations on bindings, which require updates to work properly (as paging or filtering in list bindings) will also update and cause a change event although the binding is suspended.

updateRequired

Determines if the property bindings in the composite binding should be updated by calling updateRequired on all property bindings with the specified model.

attachAggregatedDataStateChange

Attaches event handler fnFunction to the AggregatedDataStateChange event of this sap.ui.model.CompositeBinding.

The AggregatedDataStateChange event is fired asynchronously, meaning that the DataState object given as parameter of the event contains all changes that were applied to the DataState in the running thread.

Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Object on which to call the given function

attachChange

Attaches event handler fnFunction to the change event of this sap.ui.model.CompositeBinding.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.model.CompositeBinding itself.

Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Object on which to call the given function

attachDataStateChange

Attaches event handler fnFunction to the DataStateChange event of this sap.ui.model.CompositeBinding.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.model.CompositeBinding itself.

Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Object on which to call the given function

detachAggregatedDataStateChange

Detaches event handler fnFunction from the AggregatedDataStateChange event of this sap.ui.model.CompositeBinding.

Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Object on which to call the given function

detachChange

Detaches event handler fnFunction from the change event of this sap.ui.model.CompositeBinding.

Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Object on which to call the given function

detachDataStateChange

Detaches event handler fnFunction from the DataStateChange event of this sap.ui.model.CompositeBinding.

Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Object on which to call the given function

sap.ui.model.CompositeBinding.extend

Creates a new subclass of class sap.ui.model.CompositeBinding with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.model.PropertyBinding.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

getBindings

Returns the property bindings contained in this composite binding.

getExternalValue

Returns the current external value of the bound target which is formatted via a type or formatter function.

getInternalValue

Returns the current internal value of the bound target which is an array of the internal (JS native) values of nested bindings.

sap.ui.model.CompositeBinding.getMetadata

Returns a metadata object for class sap.ui.model.CompositeBinding.

getRawValue

Returns the current raw value of the bound target which is an array of the raw (model) values of nested bindings.

getValue

Returns the raw values of the property bindings in an array.

initialize

Initialize the binding. The method should be called when creating a binding. The default implementation calls checkUpdate(true). Prevent checkUpdate to be triggered while initializing nested bindings, it is sufficient to call checkUpdate when all nested bindings are initialized.

resume

Suspends the binding update. No change events will be fired.

A refresh call with bForceUpdate set to true will also update the binding and fire a change in suspended mode. Special operations on bindings, which require updates to work properly (as paging or filtering in list bindings) will also update and cause a change event although the binding is suspended.

setExternalValue

Sets the external value of a composite binding. If no CompositeType is assigned to the binding, the default implementation assumes a space-separated list of values. This will cause the setValue to be called for each nested binding, except for undefined values in the array.

Param Type DefaultValue Description
oValue object

The value to set for this binding

setInternalValue

Sets the internal value of the bound target. Parameter must be an array of values matching the internal (JS native) types of nested bindings.

Param Type DefaultValue Description
aValues array

the new values of the nested bindings

setRawValue

Sets the raw value of the bound target. Parameter must be an array of values matching the raw (model) types of nested bindings.

Param Type DefaultValue Description
aValues array

the new values of the nested bindings

setType

Sets the optional type and internal type for the binding. The type and internal type are used to do the parsing/formatting correctly. The internal type is the property type of the element which the value is formatted to.

Param Type DefaultValue Description
oType sap.ui.model.CompositeType

The type for the binding

sInternalType string

The internal type of the element property which this binding is bound against.

setValue

Sets the values. This will cause the setValue to be called for each nested binding, except for undefined values in the array.

Param Type DefaultValue Description
aValues array

The values to set for this binding

suspend

Suspends the binding update. No change events will be fired.

A refresh call with bForceUpdate set to true will also update the binding and fire a change in suspended mode. Special operations on bindings, which require updates to work properly (as paging or filtering in list bindings) will also update and cause a change event although the binding is suspended.

updateRequired

Determines if the property bindings in the composite binding should be updated by calling updateRequired on all property bindings with the specified model.

Param Type DefaultValue Description
oModel object

The model instance to compare against