class sap.ui.model.odata.v4.ODataPropertyBinding

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

Property binding for an OData V4 model. An event handler can only be attached to this binding for the following events: 'AggregatedDataStateChange', 'change', 'dataReceived', 'dataRequested' and 'DataStateChange'. For unsupported events, an error is thrown.


Constructor


Events Overview

Event Description
change

The 'change' event is fired when the binding is initialized or refreshed or its type is changed or its parent context is changed. It is to be used by controls to get notified about changes to the value of this property binding. Registered event handlers are called with the change reason as parameter.

Since: 1.37.0.

dataReceived

The 'dataReceived' event is fired after the back-end data has been processed and the registered 'change' event listeners have been notified. It is only fired for GET requests. The 'dataReceived' event is to be used by applications for example to switch off a busy indicator or to process an error.

If back-end requests are successful, the event has almost no parameters. For compatibility with sap.ui.model.Binding#event:dataReceived, an event parameter data : {} is provided: "In error cases it will be undefined", but otherwise it is not. Use oEvent.getSource().getValue() to access the response data. Note that controls bound to this data may not yet have been updated, meaning it is not safe for registered event handlers to access data via control APIs.

If a back-end request fails, the 'dataReceived' event provides an Error in the 'error' event parameter.

Since: 1.37.0.

dataRequested

The 'dataRequested' event is fired directly after data has been requested from a back end. It is only fired for GET requests. The 'dataRequested' event is to be used by applications for example to switch on a busy indicator. Registered event handlers are called without parameters.

Since: 1.37.0.

change

The 'change' event is fired when the binding is initialized or refreshed or its type is changed or its parent context is changed. It is to be used by controls to get notified about changes to the value of this property binding. Registered event handlers are called with the change reason as parameter.

Since: 1.37.0.

Param Type Description
oEvent sap.ui.base.Event
getParameters() object
reason sap.ui.model.ChangeReason

The reason for the 'change' event could be

dataReceived

The 'dataReceived' event is fired after the back-end data has been processed and the registered 'change' event listeners have been notified. It is only fired for GET requests. The 'dataReceived' event is to be used by applications for example to switch off a busy indicator or to process an error.

If back-end requests are successful, the event has almost no parameters. For compatibility with sap.ui.model.Binding#event:dataReceived, an event parameter data : {} is provided: "In error cases it will be undefined", but otherwise it is not. Use oEvent.getSource().getValue() to access the response data. Note that controls bound to this data may not yet have been updated, meaning it is not safe for registered event handlers to access data via control APIs.

If a back-end request fails, the 'dataReceived' event provides an Error in the 'error' event parameter.

Since: 1.37.0.

Param Type Description
oEvent sap.ui.base.Event
getParameters() object
data object

An empty data object if a back-end request succeeds

error Error

The error object if a back-end request failed. If there are multiple failed back-end requests, the error of the first one is provided.

dataRequested

The 'dataRequested' event is fired directly after data has been requested from a back end. It is only fired for GET requests. The 'dataRequested' event is to be used by applications for example to switch on a busy indicator. Registered event handlers are called without parameters.

Since: 1.37.0.

Param Type Description
oEvent sap.ui.base.Event

Methods Overview

Method Description
attachEvent

See sap.ui.base.EventProvider#attachEvent

References:

  • sap.ui.base.EventProvider#attachEvent

destroy

Destroys the object. The object must not be used anymore after this function was called.

References:

  • sap.ui.model.Binding#destroy

sap.ui.model.odata.v4.ODataPropertyBinding.extend

Creates a new subclass of class sap.ui.model.odata.v4.ODataPropertyBinding 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.

getGroupId

Returns the group ID of the binding that is used for read requests. The group ID of the binding is alternatively defined by

sap.ui.model.odata.v4.ODataPropertyBinding.getMetadata

Returns a metadata object for class sap.ui.model.odata.v4.ODataPropertyBinding.

getRootBinding

Returns the root binding of this binding's hierarchy, see binding Initialization and Read Requests.

getUpdateGroupId

Returns the group ID of the binding that is used for update requests. The update group ID of the binding is alternatively defined by

getValue

Returns the current value.

References:

  • sap.ui.model.PropertyBinding#getValue

getValueListType

Determines which type of value list exists for this property.

hasPendingChanges

Returns true if this binding or its dependent bindings have pending property changes or created entities which have not been sent successfully to the server. This function does not take into account the deletion of entities (see sap.ui.model.odata.v4.Context#delete) and the execution of OData operations (see sap.ui.model.odata.v4.ODataContextBinding#execute).

Note: If this binding is relative, its data is cached separately for each parent context path. This method returns true if there are pending changes for the current parent context path of this binding. If this binding is unresolved (see sap.ui.model.Binding#isResolved), it returns false.

isInitial

Method not supported

refresh

Refreshes the binding. Prompts the model to retrieve data from the server using the given group ID and notifies the control that new data is available.

Refresh is supported for bindings which are not relative to a sap.ui.model.odata.v4.Context.

Note: When calling #refresh multiple times, the result of the request triggered by the last call determines the binding's data; it is independent of the order of calls to sap.ui.model.odata.v4.ODataModel#submitBatch with the given group ID.

If there are pending changes, an error is thrown. Use #hasPendingChanges to check if there are pending changes. If there are changes, call sap.ui.model.odata.v4.ODataModel#submitBatch to submit the changes or sap.ui.model.odata.v4.ODataModel#resetChanges to reset the changes before calling #refresh.

Use #requestRefresh if you want to wait for the refresh.

References:

  • sap.ui.model.Binding#refresh
  • #getRootBinding
  • #suspend

requestRefresh

Refreshes the binding and returns a promise to wait for it. See #refresh for details. Use #refresh if you do not need the promise.

requestValue

Requests the value of the property binding.

requestValueListInfo

Requests information to retrieve a value list for this property.

requestValueListType

Determines which type of value list exists for this property.

resetChanges

Resets all pending changes of this binding, see #hasPendingChanges. Resets also invalid user input.

resume

Method not supported

References:

  • sap.ui.model.Binding#resume

setType

Sets the optional type and internal type for this binding; used for formatting and parsing. Fires a change event if the type has changed.

References:

  • sap.ui.model.PropertyBinding#setType

setValue

Sets the new current value and updates the cache. If the value cannot be accepted or cannot be updated on the server, an error is logged to the console and added to the message manager as a technical message.

References:

  • sap.ui.model.PropertyBinding#setValue

supportsIgnoreMessages

Returns true, as this binding supports the feature of not propagating model messages to the control.

References:

  • sap.ui.model.Binding#getIgnoreMessages
  • sap.ui.model.Binding#setIgnoreMessages

suspend

Method not supported

References:

  • sap.ui.model.Binding#suspend

toString

Returns a string representation of this object including the binding path. If the binding is relative, the parent path is also given, separated by a '|'.

attachEvent

See sap.ui.base.EventProvider#attachEvent

References:

Param Type DefaultValue Description
sEventId string

The identifier of the event to listen for

_oData object
_fnFunction function
_oListener object

destroy

Destroys the object. The object must not be used anymore after this function was called.

References:

sap.ui.model.odata.v4.ODataPropertyBinding.extend

Creates a new subclass of class sap.ui.model.odata.v4.ODataPropertyBinding 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

getGroupId

Returns the group ID of the binding that is used for read requests. The group ID of the binding is alternatively defined by

sap.ui.model.odata.v4.ODataPropertyBinding.getMetadata

Returns a metadata object for class sap.ui.model.odata.v4.ODataPropertyBinding.

getRootBinding

Returns the root binding of this binding's hierarchy, see binding Initialization and Read Requests.

getUpdateGroupId

Returns the group ID of the binding that is used for update requests. The update group ID of the binding is alternatively defined by

getValue

Returns the current value.

References:

getValueListType

Determines which type of value list exists for this property.

hasPendingChanges

Returns true if this binding or its dependent bindings have pending property changes or created entities which have not been sent successfully to the server. This function does not take into account the deletion of entities (see sap.ui.model.odata.v4.Context#delete) and the execution of OData operations (see sap.ui.model.odata.v4.ODataContextBinding#execute).

Note: If this binding is relative, its data is cached separately for each parent context path. This method returns true if there are pending changes for the current parent context path of this binding. If this binding is unresolved (see sap.ui.model.Binding#isResolved), it returns false.

isInitial

Method not supported

refresh

Refreshes the binding. Prompts the model to retrieve data from the server using the given group ID and notifies the control that new data is available.

Refresh is supported for bindings which are not relative to a sap.ui.model.odata.v4.Context.

Note: When calling #refresh multiple times, the result of the request triggered by the last call determines the binding's data; it is independent of the order of calls to sap.ui.model.odata.v4.ODataModel#submitBatch with the given group ID.

If there are pending changes, an error is thrown. Use #hasPendingChanges to check if there are pending changes. If there are changes, call sap.ui.model.odata.v4.ODataModel#submitBatch to submit the changes or sap.ui.model.odata.v4.ODataModel#resetChanges to reset the changes before calling #refresh.

Use #requestRefresh if you want to wait for the refresh.

References:

Param Type DefaultValue Description
sGroupId string boolean

The group ID to be used for refresh; if not specified, the binding's group ID is used, see #getGroupId. For suspended bindings, only the binding's group ID is supported because #resume uses the binding's group ID. A value of type boolean is not accepted and an error will be thrown (a forced refresh is not supported).

Valid values are undefined, '$auto', '$auto.*', '$direct' or application group IDs as specified in sap.ui.model.odata.v4.ODataModel.

requestRefresh

Refreshes the binding and returns a promise to wait for it. See #refresh for details. Use #refresh if you do not need the promise.

Param Type DefaultValue Description
sGroupId string

The group ID to be used

requestValue

Requests the value of the property binding.

requestValueListInfo

Requests information to retrieve a value list for this property.

Param Type DefaultValue Description
bAutoExpandSelect boolean

The value of the parameter autoExpandSelect for value list models created by this method. If the value list model is this binding's model, this flag has no effect. Supported since 1.68.0

requestValueListType

Determines which type of value list exists for this property.

resetChanges

Resets all pending changes of this binding, see #hasPendingChanges. Resets also invalid user input.

resume

Method not supported

References:

setType

Sets the optional type and internal type for this binding; used for formatting and parsing. Fires a change event if the type has changed.

References:

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

The type for this binding

_sInternalType string

The internal type of the element property which owns this binding, for example "any", "boolean", "float", "int", "string"; see sap.ui.model.odata.type for more information

setValue

Sets the new current value and updates the cache. If the value cannot be accepted or cannot be updated on the server, an error is logged to the console and added to the message manager as a technical message.

References:

Param Type DefaultValue Description
vValue any

The new value which must be primitive

sGroupId string

The group ID to be used for this update call; if not specified, the update group ID for this binding (or its relevant parent binding) is used, see #getUpdateGroupId. Valid values are undefined, '$auto', '$auto.*', '$direct' or application group IDs as specified in sap.ui.model.odata.v4.ODataModel.

supportsIgnoreMessages

Returns true, as this binding supports the feature of not propagating model messages to the control.

References:

suspend

Method not supported

References:

toString

Returns a string representation of this object including the binding path. If the binding is relative, the parent path is also given, separated by a '|'.