Context binding for an OData V4 model. An event handler can only be attached to this binding for the following events: 'AggregatedDataStateChange', 'change', 'dataReceived', 'dataRequested', 'DataStateChange', 'patchCompleted', and 'patchSent'. For other events, an error is thrown.
A context binding can also be used as an operation binding to support bound actions, action imports, bound functions and function imports. If you want to control the execution time of an operation, for example a function import named "GetNumberOfAvailableItems", create a context binding for the path "/GetNumberOfAvailableItems(...)" (as specified here, including the three dots). Such an operation binding is deferred, meaning that it does not request automatically, but only when you call #execute. #refresh is always ignored for actions and action imports. For bound functions and function imports, it is ignored if #execute has not yet been called. Afterwards it results in another call of the function with the parameter values of the last execute.
The binding parameter for bound actions or bound functions may be given in the binding path, for example "/SalesOrderList('42')/name.space.SalesOrder_Confirm". This can be used if the exact entity for the binding parameter is known in advance. If you use a relative binding instead, the operation path is a concatenation of the parent context's canonical path and the deferred binding's path.
Example: You have a table with a list binding to "/SalesOrderList". In each row you have a button to confirm the sales order, with the relative binding "name.space.SalesOrder_Confirm(...)". Then the parent context for such a button refers to an entity in "SalesOrderList", so its canonical path is "/SalesOrderList('SalesOrderID')" and the resulting path for the action is "/SalesOrderList('SalesOrderID')/name.space.SalesOrder_Confirm".
This also works if the relative path of the deferred operation binding starts with a navigation property. Then this navigation property will be part of the operation's resource path, which is still valid.
A deferred operation binding is not allowed to have another deferred operation binding as parent.
Event | Description |
---|---|
change |
The 'change' event is fired when the binding is initialized or its parent context is changed. It is to be used by controls to get notified about changes to the bound context of this context binding. Registered event handlers are called with the change reason as parameter. |
dataReceived |
The 'dataReceived' event is fired after the back-end data has been processed. 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. In case of a deferred operation binding, 'dataReceived' is not fired: Whatever should happen in the event handler attached to that event, can instead be done once the If back-end requests are successful, the event has almost no parameters. For compatibility with sap.ui.model.Binding#event:dataReceived, an event parameter If a back-end request fails, the 'dataReceived' event provides an |
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. In case of a deferred operation binding, 'dataRequested' is not fired: Whatever should happen in the event handler attached to that event, can instead be done before calling #execute. |
patchCompleted |
The 'patchCompleted' event is fired when the back end has responded to the last PATCH request for this binding. If there is more than one PATCH request in a $batch, the event is fired only once. Only bindings using an own data service request fire a 'patchCompleted' event. For each 'patchSent' event, a 'patchCompleted' event is fired. |
patchSent |
The 'patchSent' event is fired when the first PATCH request for this binding is sent to the back end. If there is more than one PATCH request in a $batch, the event is fired only once. Only bindings using an own data service request fire a 'patchSent' event. For each 'patchSent' event, a 'patchCompleted' event is fired. |
The 'change' event is fired when the binding is initialized or its parent context is changed. It is to be used by controls to get notified about changes to the bound context of this context 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
|
The 'dataReceived' event is fired after the back-end data has been processed. 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. In case of a deferred operation binding, 'dataReceived' is not fired: Whatever should happen in the event handler attached to that event, can instead be done once the oPromise
returned by #execute fulfills or rejects (using oPromise.then(function () {...}, function () {...})
).
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 the binding's bound context via oEvent.getSource().getBoundContext() 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. |
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. In case of a deferred operation binding, 'dataRequested' is not fired: Whatever should happen in the event handler attached to that event, can instead be done before calling #execute.
Since: 1.37.0.
Param | Type | Description |
---|---|---|
oEvent | sap.ui.base.Event |
The 'patchCompleted' event is fired when the back end has responded to the last PATCH request for this binding. If there is more than one PATCH request in a $batch, the event is fired only once. Only bindings using an own data service request fire a 'patchCompleted' event. For each 'patchSent' event, a 'patchCompleted' event is fired.
Since: 1.59.0.
Param | Type | Description |
---|---|---|
oEvent | sap.ui.base.Event |
The event object |
getSource() | sap.ui.model.odata.v4.ODataContextBinding |
This binding |
getParameters() | object |
Object containing all event parameters |
success | boolean |
Whether all PATCHes are successfully processed |
The 'patchSent' event is fired when the first PATCH request for this binding is sent to the back end. If there is more than one PATCH request in a $batch, the event is fired only once. Only bindings using an own data service request fire a 'patchSent' event. For each 'patchSent' event, a 'patchCompleted' event is fired.
Since: 1.59.0.
Param | Type | Description |
---|---|---|
oEvent | sap.ui.base.Event |
The event object |
getSource() | sap.ui.model.odata.v4.ODataContextBinding |
This binding |
Method | Description |
---|---|
attachEvent |
See sap.ui.base.EventProvider#attachEvent
|
attachPatchCompleted |
Attach event handler |
attachPatchSent |
Attach event handler |
changeParameters |
Changes this binding's parameters and refreshes the binding. 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 #changeParameters. The parameters are changed according to the given map of parameters: Parameters with an |
destroy |
Destroys the object. The object must not be used anymore after this function was called.
|
detachPatchCompleted |
Detach event handler |
detachPatchSent |
Detach event handler |
execute |
Calls the OData operation that corresponds to this operation binding. Parameters for the operation must be set via #setParameter beforehand. The value of this binding is the result of the operation. To access a result of primitive type, bind a control to the path "value", for example |
sap.ui.model.odata.v4.ODataContextBinding.extend |
Creates a new subclass of class sap.ui.model.odata.v4.ODataContextBinding with name
|
getBoundContext |
Returns the bound context. |
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.ODataContextBinding.getMetadata |
Returns a metadata object for class sap.ui.model.odata.v4.ODataContextBinding. |
getParameterContext |
Returns the context pointing to the parameters of a deferred operation binding. |
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
|
hasPendingChanges |
Returns Note: If this binding is relative, its data is cached separately for each parent context path. This method returns |
initialize |
Initializes the OData context binding: Fires a 'change' event in case the binding has a resolved path and its root binding is not suspended.
|
isInitial |
Method not supported |
moveEntityTo |
Moves the bound entity into the given list binding. This binding loses its data. The method may only be called when this binding has finished loading. You can verify this by calling |
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.
|
requestObject |
Returns a promise on the value for the given path relative to this binding. The function allows access to the complete data the binding points to (if If you want #requestObject to read fresh data, call
|
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. |
resetChanges |
Resets all pending changes of this binding, see #hasPendingChanges. Resets also invalid user input. |
resume |
Resumes this binding. The binding can then again fire change events and trigger data service requests. Before 1.53.0, this method was not supported and threw an error.
|
setParameter |
Sets a parameter for an operation call. |
suspend |
Suspends this binding. A suspended binding does not fire change events nor does it trigger data service requests. Call #resume to resume the binding. Before 1.53.0, this method was not supported and threw an error.
|
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 '|'. |
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 |
Attach event handler fnFunction
to the 'patchCompleted' event of this binding.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
The function to call when the event occurs |
|
oListener | object |
Object on which to call the given function |
Attach event handler fnFunction
to the 'patchSent' event of this binding.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
The function to call when the event occurs |
|
oListener | object |
Object on which to call the given function |
Changes this binding's parameters and refreshes the binding.
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 #changeParameters.
The parameters are changed according to the given map of parameters: Parameters with an undefined
value are removed, the other parameters are set, and missing parameters remain unchanged.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Map of binding parameters, see sap.ui.model.odata.v4.ODataModel#bindList and sap.ui.model.odata.v4.ODataModel#bindContext |
Destroys the object. The object must not be used anymore after this function was called.
References:
Detach event handler fnFunction
from the 'patchCompleted' event of this binding.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
The function to call when the event occurs |
|
oListener | object |
Object on which to call the given function |
Detach event handler fnFunction
from the 'patchSent' event of this binding.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
The function to call when the event occurs |
|
oListener | object |
Object on which to call the given function |
Calls the OData operation that corresponds to this operation binding.
Parameters for the operation must be set via #setParameter beforehand.
The value of this binding is the result of the operation. To access a result of primitive type, bind a control to the path "value", for example <Text text="{value}"/>
. If the result has a complex or entity type, you can bind properties as usual, for example <Text text="{street}"/>
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sGroupId | string |
The group ID to be used for the request; if not specified, the group ID for this binding is used, see sap.ui.model.odata.v4.ODataContextBinding#constructor and #getGroupId. To use the update group ID, see #getUpdateGroupId, it needs to be specified explicitly. Valid values are |
|
bIgnoreETag | boolean |
Whether the entity's ETag should be actively ignored (If-Match:*); supported for bound actions only, since 1.90.0. Ignored if there is no ETag (since 1.93.0). |
|
fnOnStrictHandlingFailed | function |
If this callback is given for an action, the preference "handling=strict" is applied. If the service responds with the HTTP status code 412 and a "Preference-applied: handling=strict" header, the details from the OData error response are extracted and passed to the callback as an array of sap.ui.core.message.Message items. The callback has to return a |
Creates a new subclass of class sap.ui.model.odata.v4.ODataContextBinding 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.ContextBinding.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 |
Returns the group ID of the binding that is used for read requests. The group ID of the binding is alternatively defined by
groupId
parameter of the OData model; see sap.ui.model.odata.v4.ODataModel#constructor, $$groupId
binding parameter; see sap.ui.model.odata.v4.ODataModel#bindList and sap.ui.model.odata.v4.ODataModel#bindContext. Returns a metadata object for class sap.ui.model.odata.v4.ODataContextBinding.
Returns the root binding of this binding's hierarchy, see binding Initialization and Read Requests.
Returns the group ID of the binding that is used for update requests. The update group ID of the binding is alternatively defined by
updateGroupId
parameter of the OData model; see sap.ui.model.odata.v4.ODataModel#constructor, $$updateGroupId
binding parameter; see sap.ui.model.odata.v4.ODataModel#bindList and sap.ui.model.odata.v4.ODataModel#bindContext. 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
.
Initializes the OData context binding: Fires a 'change' event in case the binding has a resolved path and its root binding is not suspended.
References:
Moves the bound entity into the given list binding. This binding loses its data. The method may only be called when this binding has finished loading. You can verify this by calling oBinding.getBoundContext().requestObject()
. If that promise resolves, the binding has finished loading.
Param | Type | DefaultValue | Description |
---|---|---|---|
oListBinding | sap.ui.model.odata.v4.ODataListBinding |
The list binding to take the entity |
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 |
Returns a promise on the value for the given path relative to this binding. The function allows access to the complete data the binding points to (if sPath
is "") or any part thereof. The data is a JSON structure as described in "OData JSON Format Version 4.0". Note that the function clones the result. Modify values via sap.ui.model.odata.v4.Context#setProperty.
If you want #requestObject to read fresh data, call oBinding.refresh()
first.
References:
Param | Type | DefaultValue | Description |
---|---|---|---|
sPath | string | "" |
A path relative to this context binding |
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 |
Resets all pending changes of this binding, see #hasPendingChanges. Resets also invalid user input.
Resumes this binding. The binding can then again fire change events and trigger data service requests. Before 1.53.0, this method was not supported and threw an error.
References:
Sets a parameter for an operation call.
Param | Type | DefaultValue | Description |
---|---|---|---|
sParameterName | string |
The parameter name |
|
vValue | any |
The parameter value |
Suspends this binding. A suspended binding does not fire change events nor does it trigger data service requests. Call #resume to resume the binding. Before 1.53.0, this method was not supported and threw an error.
References: