abstract class sap.ui.model.Binding

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

The Binding is the object, which holds the necessary information for a data binding, like the binding path and the binding context, and acts like an interface to the model for the control, so it is the event provider for changes in the data model and provides getters for accessing properties or lists.


Constructor

Constructor for Binding class.

new sap.ui.model.Binding(oModel, sPath, oContext, mParameters?)
Param Type Default Value Description
oModel sap.ui.model.Model

The model

sPath string

The path

oContext sap.ui.model.Context

The context object

mParameters? object

Additional, implementation-specific parameters


Events Overview

Event Description
AggregatedDataStateChange

The AggregatedDataStateChange event is fired asynchronously when all datastateChanges within the actual stack are done.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

change

The change event is fired, when the model data are changed. The optional reason parameter of the event provides a hint where the change came from.

Note: Subclasses might add additional parameters to the event object.

dataReceived

The dataReceived event is fired, when data was received from a backend.

This event may also be fired when an error occurred.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

dataRequested

The dataRequested event is fired, when data was requested from a backend.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

DataStateChange

The DataStateChange event is fired when the DataState of the binding has changed.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

AggregatedDataStateChange

The AggregatedDataStateChange event is fired asynchronously when all datastateChanges within the actual stack are done.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

Param Type Description
oEvent sap.ui.base.Event

The event object

getSource sap.ui.base.EventProvider

The object on which the event initially occurred

getParameters object

Object containing all event parameters

dataState sap.ui.model.DataState

The DataState object of the binding

change

The change event is fired, when the model data are changed. The optional reason parameter of the event provides a hint where the change came from.

Note: Subclasses might add additional parameters to the event object.

Param Type Description
oEvent sap.ui.base.Event

The event object

getSource sap.ui.base.EventProvider

The object on which the event initially occurred

getParameters object

Object containing all event parameters

reason string

A string stating the reason for the data change; some change reasons can be found in sap.ui.model.ChangeReason, but there may be additional reasons specified by a specific model implementation

dataReceived

The dataReceived event is fired, when data was received from a backend.

This event may also be fired when an error occurred.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

Param Type Description
oEvent sap.ui.base.Event

The event object

getSource sap.ui.base.EventProvider

The object on which the event initially occurred

getParameters object

Object containing all event parameters

data string

The data received; is undefined in error cases

dataRequested

The dataRequested event is fired, when data was requested from a backend.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

Param Type Description
oEvent sap.ui.base.Event

The event object

getSource sap.ui.base.EventProvider

The object on which the event initially occurred

getParameters object

Object containing all event parameters

DataStateChange

The DataStateChange event is fired when the DataState of the binding has changed.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

Param Type Description
oEvent sap.ui.base.Event

The event object

getSource sap.ui.base.EventProvider

The object on which the event initially occurred

getParameters object

Object containing all event parameters

dataState sap.ui.model.DataState

The DataState object of the binding


Methods Overview

Method Description
attachAggregatedDataStateChange

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

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.Binding itself.

attachChange

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

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.Binding itself.

attachDataReceived

Attaches event handler fnFunction to the dataReceived event of this sap.ui.model.Binding.

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.Binding itself.

attachDataRequested

Attaches event handler fnFunction to the dataRequested event of this sap.ui.model.Binding.

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.Binding itself.

attachDataStateChange

Attaches the fnFunction event handler to the DataStateChange event of thi sap.ui.model.Binding.

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.Binding itself.

attachEvents

Attach multiple events.

attachRefresh

Attaches event handler fnFunction to the refresh event of this sap.ui.model.Binding.

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.Binding itself.

destroy

Removes all control messages for this binding from the MessageManager in addition to the standard clean-up tasks.

References:

  • sap.ui.base.EventProvider#destroy

detachAggregatedDataStateChange

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

detachChange

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

detachDataReceived

Detaches event handler fnFunction from the dataReceived event of this sap.ui.model.Binding.

detachDataRequested

Detaches event handler fnFunction from the dataRequested event of this sap.ui.model.Binding.

detachDataStateChange

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

detachEvents

Detach multiple events.

detachRefresh

Detaches event handler fnFunction from the refresh event of this sap.ui.model.Binding.

sap.ui.model.Binding.extend

Creates a new subclass of class sap.ui.model.Binding 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.base.EventProvider.extend.

fireDataReceived

Fires event dataReceived to attached listeners.

This event may also be fired when an error occurred.

fireDataRequested

Fires event dataRequested to attached listeners.

getContext

Returns the model context in which this binding will be resolved.

If the binding path is absolute, the context is not relevant.

getIgnoreMessages

Whether this binding does not propagate model messages to the control. By default, all bindings propagate messages. If a binding wants to support this feature, it has to override #supportsIgnoreMessages, which returns true.

For example, a binding for a currency code is used in a composite binding for rendering the proper number of decimals, but the currency code is not displayed in the attached control. In that case, messages for the currency code shall not be displayed at that control, only messages for the amount.

sap.ui.model.Binding.getMetadata

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

getModel

Returns the model to which this binding belongs.

getPath

Returns the model path to which this binding binds.

Might be a relative or absolute path. If it is relative, it will be resolved relative to the context as returned by #getContext.

getResolvedPath

Provides the resolved path for this binding's path and context and returns it, or undefined if the binding is not resolved or has no model.

initialize

Initialize the binding. The message should be called when creating a binding. The default implementation calls checkUpdate(true).

isInitial

Returns whether the binding is initial, which means it did not get an initial value yet.

isRelative

Returns whether the binding is relative, which means its path does not start with a slash.

isResolved

Returns whether the binding is resolved, which means the binding's path is absolute or the binding has a model context.

References:

  • #getContext
  • #getPath
  • #isRelative

isSuspended

Returns true if the binding is suspended or false if not.

refresh

Refreshes the binding, check whether the model data has been changed and fire change event if this is the case. For server side models this should refetch the data from the server. To update a control, even if no data has been changed, e.g. to reset a control after failed validation, please use the parameter bForceUpdate.

resume

Resumes the binding update. Change events will be fired again.

When the binding is resumed, a change event will be fired immediately if the data has changed while the binding was suspended. For server-side models, a request to the server will be triggered if a refresh was requested while the binding was suspended.

setIgnoreMessages

Sets the indicator whether this binding does not propagate model messages to the control.

References:

  • #getIgnoreMessages
  • #supportsIgnoreMessages

supportsIgnoreMessages

Whether this binding supports the feature of not propagating model messages to the control. The default implementation returns false.

References:

  • #getIgnoreMessages
  • #setIgnoreMessages

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 binding should be updated by comparing the current model against a specified model.

attachAggregatedDataStateChange

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

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.Binding itself.

Param Type DefaultValue Description
fnFunction function

The function to be called when the event occurs

oListener object

Context object to call the event handler with; defaults to this sap.ui.model.Binding itself

attachChange

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

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.Binding itself.

Param Type DefaultValue Description
fnFunction function

The function to be called when the event occurs

oListener object

Context object to call the event handler with; defaults to this sap.ui.model.Binding itself

attachDataReceived

Attaches event handler fnFunction to the dataReceived event of this sap.ui.model.Binding.

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.Binding itself.

Param Type DefaultValue Description
fnFunction function

Function to be called when the event occurs

oListener object

Context object to call the event handler with; defaults to this sap.ui.model.Binding itself

attachDataRequested

Attaches event handler fnFunction to the dataRequested event of this sap.ui.model.Binding.

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.Binding itself.

Param Type DefaultValue Description
fnFunction function

The function to be called when the event occurs

oListener object

Context object to call the event handler with; defaults to this sap.ui.model.Binding itself

attachDataStateChange

Attaches the fnFunction event handler to the DataStateChange event of thi sap.ui.model.Binding.

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.Binding itself.

Param Type DefaultValue Description
fnFunction function

Function to be called when the event occurs

oListener object

Context object to call the event handler with; defaults to this sap.ui.model.Binding itself

attachEvents

Attach multiple events.

Param Type DefaultValue Description
oEvents Object<string,function>

Events to attach to this binding

attachRefresh

Attaches event handler fnFunction to the refresh event of this sap.ui.model.Binding.

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.Binding itself.

Param Type DefaultValue Description
fnFunction function

The function to be called when the event occurs

oListener object

Context object to call the event handler with; defaults to this sap.ui.model.Binding itself

destroy

Removes all control messages for this binding from the MessageManager in addition to the standard clean-up tasks.

References:

detachAggregatedDataStateChange

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

Param Type DefaultValue Description
fnFunction function

The function to be called when the event occurs

oListener object

Context object on which the given function had to be called

detachChange

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

Param Type DefaultValue Description
fnFunction function

Function to be called when the event occurs

oListener object

Context object on which the given function had to be called

detachDataReceived

Detaches event handler fnFunction from the dataReceived event of this sap.ui.model.Binding.

Param Type DefaultValue Description
fnFunction function

Function to be called when the event occurs

oListener object

Context object on which the given function had to be called

detachDataRequested

Detaches event handler fnFunction from the dataRequested event of this sap.ui.model.Binding.

Param Type DefaultValue Description
fnFunction function

The function to be called when the event occurs

oListener object

Context object on which the given function had to be called

detachDataStateChange

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

Param Type DefaultValue Description
fnFunction function

The function to be called when the event occurs

oListener object

Context object on which the given function had to be called

detachEvents

Detach multiple events.

Param Type DefaultValue Description
oEvents Object<string,function>

Events to detach from this binding

detachRefresh

Detaches event handler fnFunction from the refresh event of this sap.ui.model.Binding.

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.Binding.extend

Creates a new subclass of class sap.ui.model.Binding 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.base.EventProvider.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

fireDataReceived

Fires event dataReceived to attached listeners.

This event may also be fired when an error occurred.

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

data object

Data received; on error cases it will be undefined

fireDataRequested

Fires event dataRequested to attached listeners.

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

getContext

Returns the model context in which this binding will be resolved.

If the binding path is absolute, the context is not relevant.

getIgnoreMessages

Whether this binding does not propagate model messages to the control. By default, all bindings propagate messages. If a binding wants to support this feature, it has to override #supportsIgnoreMessages, which returns true.

For example, a binding for a currency code is used in a composite binding for rendering the proper number of decimals, but the currency code is not displayed in the attached control. In that case, messages for the currency code shall not be displayed at that control, only messages for the amount.

sap.ui.model.Binding.getMetadata

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

getModel

Returns the model to which this binding belongs.

getPath

Returns the model path to which this binding binds.

Might be a relative or absolute path. If it is relative, it will be resolved relative to the context as returned by #getContext.

getResolvedPath

Provides the resolved path for this binding's path and context and returns it, or undefined if the binding is not resolved or has no model.

initialize

Initialize the binding. The message should be called when creating a binding. The default implementation calls checkUpdate(true).

isInitial

Returns whether the binding is initial, which means it did not get an initial value yet.

isRelative

Returns whether the binding is relative, which means its path does not start with a slash.

isResolved

Returns whether the binding is resolved, which means the binding's path is absolute or the binding has a model context.

References:

isSuspended

Returns true if the binding is suspended or false if not.

refresh

Refreshes the binding, check whether the model data has been changed and fire change event if this is the case. For server side models this should refetch the data from the server. To update a control, even if no data has been changed, e.g. to reset a control after failed validation, please use the parameter bForceUpdate.

Param Type DefaultValue Description
bForceUpdate boolean

Update the bound control even if no data has been changed

resume

Resumes the binding update. Change events will be fired again.

When the binding is resumed, a change event will be fired immediately if the data has changed while the binding was suspended. For server-side models, a request to the server will be triggered if a refresh was requested while the binding was suspended.

setIgnoreMessages

Sets the indicator whether this binding does not propagate model messages to the control.

References:

Param Type DefaultValue Description
bIgnoreMessages boolean

Whether this binding does not propagate model messages to the control

supportsIgnoreMessages

Whether this binding supports the feature of not propagating model messages to the control. The default implementation returns false.

References:

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 binding should be updated by comparing the current model against a specified model.

Param Type DefaultValue Description
oModel object

The model instance to compare against