class sap.ui.model.odata.v4.ODataListBinding

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

List binding for an OData V4 model. An event handler can only be attached to this binding for the following events: 'AggregatedDataStateChange', 'change', 'createCompleted', 'createSent', 'dataReceived', 'dataRequested', 'DataStateChange', 'patchCompleted', 'patchSent', and 'refresh'. For other events, an error is thrown.


Constructor


Events Overview

Event Description
change

The 'change' event is fired when new contexts are created or removed, or the binding's parent context is changed. Controls use the event to get notified about changes to the binding contexts of this list binding. Registered event handlers are called with the reason and detailed reason as parameters.

Since: 1.37.0.

createCompleted

The 'createCompleted' event is fired when the back end has responded to a POST request triggered for a #create on this binding. For each 'createSent' event, a 'createCompleted' event is fired.

Since: 1.66.0.

createSent

The 'createSent' event is fired when a POST request triggered for a #create on this binding is sent to the back end. For each 'createSent' event, a 'createCompleted' event is fired.

Since: 1.66.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 the binding's contexts via oEvent.getSource().getCurrentContexts() 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.

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.

Since: 1.59.0.

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.

Since: 1.59.0.

refresh

The 'refresh' event is fired when the binding is initialized (since 1.67.0), or its parent context is changed or one of the methods #changeParameters, #filter, #refresh, #resume, #setAggregation or #sort is called. Controls use the event to get notified about a refresh of the binding contexts of this list binding. Registered event handlers are called with the change reason as parameter.

Since: 1.37.0.

change

The 'change' event is fired when new contexts are created or removed, or the binding's parent context is changed. Controls use the event to get notified about changes to the binding contexts of this list binding. Registered event handlers are called with the reason and detailed reason as parameters.

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 is

  • Add when a new context is created,
  • Remove when a context is removed,
  • Context when the parent context is changed,
  • Change for other changes.
Additionally each 'refresh' event is followed by a 'change' event repeating the change reason when the requested data is available.

detailedReason string

During automatic determination of $expand and $select, a "virtual" context is first added with detailed reason "AddVirtualContext" and then removed with detailed reason "RemoveVirtualContext" (since 1.69.0); undefined is used in all other cases

createCompleted

The 'createCompleted' event is fired when the back end has responded to a POST request triggered for a #create on this binding. For each 'createSent' event, a 'createCompleted' event is fired.

Since: 1.66.0.

Param Type Description
oEvent sap.ui.base.Event

The event object

getSource() sap.ui.model.odata.v4.ODataListBinding

This binding

getParameters() object

Object containing all event parameters

context sap.ui.model.odata.v4.Context

The context for the created entity

success boolean

Whether the POST was successfully processed; in case of an error, the error is already reported to the sap.ui.core.message.MessageManager

createSent

The 'createSent' event is fired when a POST request triggered for a #create on this binding is sent to the back end. For each 'createSent' event, a 'createCompleted' event is fired.

Since: 1.66.0.

Param Type Description
oEvent sap.ui.base.Event

The event object

getSource() sap.ui.model.odata.v4.ODataListBinding

This binding

getParameters() object

Object containing all event parameters

context sap.ui.model.odata.v4.Context

The context for the created entity

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 the binding's contexts via oEvent.getSource().getCurrentContexts() 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

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.

Since: 1.59.0.

Param Type Description
oEvent sap.ui.base.Event

The event object

getSource() sap.ui.model.odata.v4.ODataListBinding

This binding

getParameters() object

Object containing all event parameters

success boolean

Whether all PATCHes are successfully processed

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.

Since: 1.59.0.

Param Type Description
oEvent sap.ui.base.Event

The event object

getSource() sap.ui.model.odata.v4.ODataListBinding

This binding

refresh

The 'refresh' event is fired when the binding is initialized (since 1.67.0), or its parent context is changed or one of the methods #changeParameters, #filter, #refresh, #resume, #setAggregation or #sort is called. Controls use the event to get notified about a refresh of the binding contexts of this list 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 'refresh' event could be

#changeParameters leads to Filter if one of the parameters '$filter' and '$search' is changed, otherwise it leads to Sort if the parameter '$orderby' is changed; in other cases, it leads to Change.
If APIs that would normally fire change events have been called while the binding is suspended, #resume leads to the "strongest" change reason in the order Filter, Sort, Refresh, Change.


Methods Overview

Method Description
attachCreateCompleted

Attach event handler fnFunction to the 'createCompleted' event of this binding.

attachCreateSent

Attach event handler fnFunction to the 'createSent' event of this binding.

attachEvent

See sap.ui.base.EventProvider#attachEvent

References:

  • sap.ui.base.EventProvider#attachEvent

attachPatchCompleted

Attach event handler fnFunction to the 'patchCompleted' event of this binding.

attachPatchSent

Attach event handler fnFunction to the 'patchSent' event of this binding.

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 undefined value are removed, the other parameters are set, and missing parameters remain unchanged.

create

Creates a new entity and inserts it at the start or the end of the list.

For creating the new entity, the binding's update group ID is used, see #getUpdateGroupId.

You can call sap.ui.model.odata.v4.Context#delete to delete the created context again. As long as the context is transient (see sap.ui.model.odata.v4.Context#isTransient), #resetChanges and a call to sap.ui.model.odata.v4.ODataModel#resetChanges with the update group ID as parameter also delete the created context together with other changes.

If the creation of the entity on the server failed, the creation is repeated automatically. If the binding's update group ID has sap.ui.model.odata.v4.SubmitMode.API, it is repeated with the next call of sap.ui.model.odata.v4.ODataModel#submitBatch. Otherwise it is repeated with the next update for the entity. Since 1.67.0, sap.ui.model.odata.v4.ODataModel#submitBatch can also be used for group IDs with sap.ui.model.odata.v4.SubmitMode.Auto in order to repeat the creation even if there is no update for the entity.

Each time the data for the created entity is sent to the server, a #event:createSent event is fired and each time the client receives a response for the creation, a #event:createCompleted event is fired, independent of whether the creation was successful or not.

The initial data for the created entity can be supplied via the parameter oInitialData and modified via property bindings. Properties that are not part of the initial data show the default value from the service metadata on the UI, but they are not sent to the server. If there is no default value, null is used instead, even if the property is not Nullable. The initial data may contain instance annotations.

Note: If a server requires a property in the request, you must supply this property in the initial data, for example if the server requires a unit for an amount. This also applies if this property has a default value.

Note: After creation, the created entity is refreshed to ensure that the data specified in this list binding's $expand is available. This refresh is done via the group ID of the binding, unless the group ID has sap.ui.model.odata.v4.SubmitMode.API, in which case '$auto' is used. To skip this refresh, set bSkipRefresh to true. To avoid errors you must skip this refresh when using sap.ui.model.odata.v4.Context#requestSideEffects in the same $batch to refresh the complete collection containing the newly created entity.

Note: A deep create is not supported. The dependent entity has to be created using a second list binding. Note that it is not supported to bind relative to a transient context.

Note: Creating at the end is only allowed if the final length of the binding is known (see #isLengthFinal), so that there is a clear position to place this entity at. This is the case if the complete collection has been read or if the system query option $count is true and the binding has processed at least one request.

destroy

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

References:

  • sap.ui.model.Binding#destroy

detachCreateCompleted

Detach event handler fnFunction from the 'createCompleted' event of this binding.

detachCreateSent

Detach event handler fnFunction from the 'createSent' event of this binding.

detachPatchCompleted

Detach event handler fnFunction from the 'patchCompleted' event of this binding.

detachPatchSent

Detach event handler fnFunction from the 'patchSent' event of this binding.

sap.ui.model.odata.v4.ODataListBinding.extend

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

filter

Filters the list with the given filters.

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 #filter.

Filters are case sensitive unless the property caseSensitive is set to false. This property has to be set on each filter, it is not inherited from a multi-filter.

Application and Control Filters

Each list binding maintains two separate lists of filters, one for filters defined by the control that owns the binding, and another list for filters that an application can define in addition. When executing the filter operation, both sets of filters are combined.

By using the sFilterType parameter of the filter method, the caller can control which set of filters is modified.

Auto-Grouping of Filters

Filters are first grouped according to their binding path. All filters belonging to the same path are ORed, and after that the results of all paths are ANDed. Usually this means that all filters applied to the same property are ORed, while filters on different properties are ANDed. Please use either the automatic grouping of filters (where applicable) or explicit AND/OR filters, as a mixture of both is not supported.

References:

  • sap.ui.model.ListBinding#filter
  • #setAggregation

getContexts

Returns already created binding contexts for all entities in this list binding for the range determined by the given start index iStart and iLength. If at least one of the entities in the given range has not yet been loaded, fires a #event:change event on this list binding once these entities have been loaded asynchronously. A further call to this method in the 'change' event handler with the same index range then yields the updated array of contexts.

getCount

Returns the count of elements.

If known, the value represents the sum of the element count of the collection on the server and the number of transient entities created on the client. Otherwise, it is undefined. The value is a number of type Edm.Int64. Since 1.91.0, in case of data aggregation with group levels, the count is the leaf count on the server; it is only determined if the $count system query option is given.

The count is known to the binding in the following situations:

  • The server-side count has been requested via the $count system query option.
  • A "short read" in a paged collection (the server delivered less elements than requested) indicated that the server has no more unread elements.
  • It has been read completely in one request, for example an embedded collection via $expand.

The $count is unknown if the binding is relative but has no context.

The count is bindable via the header context (see #getHeaderContext) and path $count.

Use getHeaderContext().requestProperty("$count") if you want to wait for the value.

getCurrentContexts

Returns the contexts that were requested by a control last time. Does not trigger a data request. In the time between the #event:dataRequested event and the #event:dataReceived event, the resulting array contains undefined at those indexes where the data is not yet available.

References:

  • sap.ui.model.ListBinding#getCurrentContexts

getDistinctValues

Method not supported

References:

  • sap.ui.model.ListBinding#getDistinctValues

getDownloadUrl

Returns a URL by which the complete content of the list can be downloaded in JSON format. The request delivers all entities considering the binding's query options (such as filters or sorters).

The returned URL does not specify $skip and $top and leaves it up to the server how many rows it delivers. Many servers tend to choose a small limit without $skip and $top, so it might be wise to add an appropriate value for $top at least.

Additionally, you must be aware of server-driven paging and be ready to send a follow-up request if the response contains @odata.nextlink.

References:

  • #requestDownloadUrl

getFilterInfo

Returns the filter information as an abstract syntax tree. Consumers must not rely on the origin information to be available, future filter implementations will not provide this information.

If the system query option $filter is present, it will be added to the AST as a node with the following structure:

  • expression: the value of the system query option $filter
  • syntax: the OData version of this bindings model, e.g. "OData 4.0"
  • type: "Custom"

getGroupId

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

getHeaderContext

Returns the header context which allows binding to $count.

References:

  • #getCount

getLength

Returns the number of entries in the list. As long as the client does not know the size on the server, an estimated length is returned.

References:

  • sap.ui.model.ListBinding#getLength

sap.ui.model.odata.v4.ODataListBinding.getMetadata

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

getQueryOptions

Returns the query options of the 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 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.

initialize

Initializes the OData list binding: Fires an event in case the binding has a resolved path and its root binding is not suspended. If the model's parameter autoExpandSelect is used (see sap.ui.model.odata.v4.ODataModel#constructor), it fires a 'change' event, else it fires a 'refresh' event (since 1.67.0).

References:

  • #getRootBinding

isInitial

Method not supported

isLengthFinal

Returns true if the length has been determined by the data returned from server. If the length is a client side estimation false is returned.

References:

  • sap.ui.model.ListBinding#isLengthFinal

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

requestContexts

Requests the entities for the given index range of the binding's collection and resolves with the corresponding contexts.

requestDownloadUrl

Returns a URL by which the complete content of the list can be downloaded in JSON format. The request delivers all entities considering the binding's query options (such as filters or sorters).

The returned URL does not specify $skip and $top and leaves it up to the server how many rows it delivers. Many servers tend to choose a small limit without $skip and $top, so it might be wise to add an appropriate value for $top at least.

Additionally, you must be aware of server-driven paging and be ready to send a follow-up request if the response contains @odata.nextlink.

References:

  • #getDownloadUrl

requestFilterForMessages

Requests a sap.ui.model.Filter object which can be used to filter the list binding by entries with model messages. With the filter callback, you can define if a message is considered when creating the filter for entries with messages.

The resulting filter does not consider application or control filters specified for this list binding in its constructor or in its #filter method; add filters which you want to keep with the "and" conjunction to the resulting filter before calling #filter.

References:

  • sap.ui.model.ListBinding#requestFilterForMessages

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.

References:

setAggregation

Sets a new data aggregation object and derives the system query option $apply implicitly from it.

sort

Sort the entries represented by this list binding according to the given sorters. The sorters are stored at this list binding and they are used for each following data request.

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 #sort.

References:

  • sap.ui.model.ListBinding#sort

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.

References:

  • Suspend and Resume
  • sap.ui.model.Binding#suspend
  • sap.ui.model.odata.v4.ODataContextBinding#hasPendingChanges
  • sap.ui.model.odata.v4.ODataListBinding#hasPendingChanges
  • #resume

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 '|'.

updateAnalyticalInfo

Updates the binding's system query option $apply based on the given data aggregation information. Its value is "groupby((<dimension_1,...,dimension_N,unit_or_text_1,...,unit_or_text_K>), aggregate(<measure> with <method> as <alias>, ...))" where the "aggregate" part is only present if measures are given and both "with" and "as" are optional. Since 1.93.0, a previous "search before data aggregation" is considered (see the oAggregation.search parameter of #setAggregation).

References:

  • sap.ui.model.analytics.AnalyticalBinding#updateAnalyticalInfo
  • #changeParameters
  • #setAggregation

attachCreateCompleted

Attach event handler fnFunction to the 'createCompleted' 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

attachCreateSent

Attach event handler fnFunction to the 'createSent' 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

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

attachPatchCompleted

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

attachPatchSent

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

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 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

create

Creates a new entity and inserts it at the start or the end of the list.

For creating the new entity, the binding's update group ID is used, see #getUpdateGroupId.

You can call sap.ui.model.odata.v4.Context#delete to delete the created context again. As long as the context is transient (see sap.ui.model.odata.v4.Context#isTransient), #resetChanges and a call to sap.ui.model.odata.v4.ODataModel#resetChanges with the update group ID as parameter also delete the created context together with other changes.

If the creation of the entity on the server failed, the creation is repeated automatically. If the binding's update group ID has sap.ui.model.odata.v4.SubmitMode.API, it is repeated with the next call of sap.ui.model.odata.v4.ODataModel#submitBatch. Otherwise it is repeated with the next update for the entity. Since 1.67.0, sap.ui.model.odata.v4.ODataModel#submitBatch can also be used for group IDs with sap.ui.model.odata.v4.SubmitMode.Auto in order to repeat the creation even if there is no update for the entity.

Each time the data for the created entity is sent to the server, a #event:createSent event is fired and each time the client receives a response for the creation, a #event:createCompleted event is fired, independent of whether the creation was successful or not.

The initial data for the created entity can be supplied via the parameter oInitialData and modified via property bindings. Properties that are not part of the initial data show the default value from the service metadata on the UI, but they are not sent to the server. If there is no default value, null is used instead, even if the property is not Nullable. The initial data may contain instance annotations.

Note: If a server requires a property in the request, you must supply this property in the initial data, for example if the server requires a unit for an amount. This also applies if this property has a default value.

Note: After creation, the created entity is refreshed to ensure that the data specified in this list binding's $expand is available. This refresh is done via the group ID of the binding, unless the group ID has sap.ui.model.odata.v4.SubmitMode.API, in which case '$auto' is used. To skip this refresh, set bSkipRefresh to true. To avoid errors you must skip this refresh when using sap.ui.model.odata.v4.Context#requestSideEffects in the same $batch to refresh the complete collection containing the newly created entity.

Note: A deep create is not supported. The dependent entity has to be created using a second list binding. Note that it is not supported to bind relative to a transient context.

Note: Creating at the end is only allowed if the final length of the binding is known (see #isLengthFinal), so that there is a clear position to place this entity at. This is the case if the complete collection has been read or if the system query option $count is true and the binding has processed at least one request.

Param Type DefaultValue Description
oInitialData object {}

The initial data for the created entity

bSkipRefresh boolean

Whether an automatic refresh of the created entity will be skipped

bAtEnd boolean

Whether the entity is inserted at the end of the list. When creating multiple entities, this parameter must have the same value for each entity. Supported since 1.66.0

destroy

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

References:

detachCreateCompleted

Detach event handler fnFunction from the 'createCompleted' 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

detachCreateSent

Detach event handler fnFunction from the 'createSent' 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

detachPatchCompleted

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

detachPatchSent

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

sap.ui.model.odata.v4.ODataListBinding.extend

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

filter

Filters the list with the given filters.

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 #filter.

Filters are case sensitive unless the property caseSensitive is set to false. This property has to be set on each filter, it is not inherited from a multi-filter.

Application and Control Filters

Each list binding maintains two separate lists of filters, one for filters defined by the control that owns the binding, and another list for filters that an application can define in addition. When executing the filter operation, both sets of filters are combined.

By using the sFilterType parameter of the filter method, the caller can control which set of filters is modified.

Auto-Grouping of Filters

Filters are first grouped according to their binding path. All filters belonging to the same path are ORed, and after that the results of all paths are ANDed. Usually this means that all filters applied to the same property are ORed, while filters on different properties are ANDed. Please use either the automatic grouping of filters (where applicable) or explicit AND/OR filters, as a mixture of both is not supported.

References:

Param Type DefaultValue Description
vFilters sap.ui.model.Filter sap.ui.model.Filter[]

The dynamic filters to be used; replaces the dynamic filters given in sap.ui.model.odata.v4.ODataModel#bindList. The filter executed on the list is created from the following parts, which are combined with a logical 'and':

sFilterType sap.ui.model.FilterType sap.ui.model.FilterType.Application

The filter type to be used

getContexts

Returns already created binding contexts for all entities in this list binding for the range determined by the given start index iStart and iLength. If at least one of the entities in the given range has not yet been loaded, fires a #event:change event on this list binding once these entities have been loaded asynchronously. A further call to this method in the 'change' event handler with the same index range then yields the updated array of contexts.

Param Type DefaultValue Description
iStart number 0

The index where to start the retrieval of contexts

iLength number

The number of contexts to retrieve beginning from the start index; defaults to the model's size limit, see sap.ui.model.Model#setSizeLimit; Infinity may be used since 1.53.0 to retrieve all data

iMaximumPrefetchSize number 0

The maximum number of contexts to read before and after the given range; with this, controls can prefetch data that is likely to be needed soon, e.g. when scrolling down in a table. Negative values will be treated as 0. Supported since 1.39.0; Infinity may be used since 1.53.0 to prefetch all data and thus disable paging.

bKeepCurrent boolean

Whether this call keeps the result of #getCurrentContexts untouched; since 1.86.0.

getCount

Returns the count of elements.

If known, the value represents the sum of the element count of the collection on the server and the number of transient entities created on the client. Otherwise, it is undefined. The value is a number of type Edm.Int64. Since 1.91.0, in case of data aggregation with group levels, the count is the leaf count on the server; it is only determined if the $count system query option is given.

The count is known to the binding in the following situations:

The $count is unknown if the binding is relative but has no context.

The count is bindable via the header context (see #getHeaderContext) and path $count.

Use getHeaderContext().requestProperty("$count") if you want to wait for the value.

getCurrentContexts

Returns the contexts that were requested by a control last time. Does not trigger a data request. In the time between the #event:dataRequested event and the #event:dataReceived event, the resulting array contains undefined at those indexes where the data is not yet available.

References:

getDistinctValues

Method not supported

References:

Param Type DefaultValue Description
_sPath string

getDownloadUrl

Returns a URL by which the complete content of the list can be downloaded in JSON format. The request delivers all entities considering the binding's query options (such as filters or sorters).

The returned URL does not specify $skip and $top and leaves it up to the server how many rows it delivers. Many servers tend to choose a small limit without $skip and $top, so it might be wise to add an appropriate value for $top at least.

Additionally, you must be aware of server-driven paging and be ready to send a follow-up request if the response contains @odata.nextlink.

References:

getFilterInfo

Returns the filter information as an abstract syntax tree. Consumers must not rely on the origin information to be available, future filter implementations will not provide this information.

If the system query option $filter is present, it will be added to the AST as a node with the following structure:

Param Type DefaultValue Description
bIncludeOrigin boolean

whether to include information about the filter objects from which the tree has been created

getGroupId

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

getHeaderContext

Returns the header context which allows binding to $count.

References:

getLength

Returns the number of entries in the list. As long as the client does not know the size on the server, an estimated length is returned.

References:

sap.ui.model.odata.v4.ODataListBinding.getMetadata

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

getQueryOptions

Returns the query options of the binding.

Param Type DefaultValue Description
bWithSystemQueryOptions boolean

Whether system query options should be returned as well. The parameter value true is not supported.

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

initialize

Initializes the OData list binding: Fires an event in case the binding has a resolved path and its root binding is not suspended. If the model's parameter autoExpandSelect is used (see sap.ui.model.odata.v4.ODataModel#constructor), it fires a 'change' event, else it fires a 'refresh' event (since 1.67.0).

References:

isInitial

Method not supported

isLengthFinal

Returns true if the length has been determined by the data returned from server. If the length is a client side estimation false is returned.

References:

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.

requestContexts

Requests the entities for the given index range of the binding's collection and resolves with the corresponding contexts.

Param Type DefaultValue Description
iStart number 0

The index where to start the retrieval of contexts; must be greater than or equal to 0

iLength number

The number of contexts to retrieve beginning from the start index; defaults to the model's size limit, see sap.ui.model.Model#setSizeLimit; must be greater than 0, Infinity may be used to retrieve all data

sGroupId string

The group ID to be used for the request; if not specified, the group ID for this binding is used, see #getGroupId. Valid values are undefined, '$auto', '$auto.*', '$direct' or application group IDs as specified in sap.ui.model.odata.v4.ODataModel.

requestDownloadUrl

Returns a URL by which the complete content of the list can be downloaded in JSON format. The request delivers all entities considering the binding's query options (such as filters or sorters).

The returned URL does not specify $skip and $top and leaves it up to the server how many rows it delivers. Many servers tend to choose a small limit without $skip and $top, so it might be wise to add an appropriate value for $top at least.

Additionally, you must be aware of server-driven paging and be ready to send a follow-up request if the response contains @odata.nextlink.

References:

requestFilterForMessages

Requests a sap.ui.model.Filter object which can be used to filter the list binding by entries with model messages. With the filter callback, you can define if a message is considered when creating the filter for entries with messages.

The resulting filter does not consider application or control filters specified for this list binding in its constructor or in its #filter method; add filters which you want to keep with the "and" conjunction to the resulting filter before calling #filter.

References:

Param Type DefaultValue Description
fnFilter function(sap.ui.core.message.Message) : boolean

A callback function to filter only relevant messages. The callback returns whether the given sap.ui.core.message.Message is considered. If no callback function is given, all messages are considered.

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

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.

References:

setAggregation

Sets a new data aggregation object and derives the system query option $apply implicitly from it.

Param Type DefaultValue Description
oAggregation object

An object holding the information needed for data aggregation; see also OData Extension for Data Aggregation Version 4.0. Since 1.76.0, undefined can be used to remove the data aggregation object, which allows to set $apply explicitly afterwards. null is not supported.
Since 1.89.0, the deprecated property "grandTotal like 1.84" : true can be used to turn on the handling of grand totals like in 1.84.0, using aggregates of aggregates and thus allowing to filter by aggregated properties while grand totals are needed. Beware that methods like "average" or "countdistinct" are not compatible with this approach, and it cannot be combined with group levels.

aggregate object

A map from aggregatable property names or aliases to objects containing the following details:

  • grandTotal: An optional boolean that tells whether a grand total for this aggregatable property is needed (since 1.59.0); filtering by any aggregatable property is not supported in this case (since 1.89.0) as is "$search" (since 1.93.0)
  • subtotals: An optional boolean that tells whether subtotals for this aggregatable property are needed
  • with: An optional string that provides the name of the method (for example "sum") used for aggregation of this aggregatable property; see "3.1.2 Keyword with".
  • name: An optional string that provides the original aggregatable property name in case a different alias is chosen as the name of the dynamic property used for aggregation of this aggregatable property; see "3.1.1 Keyword as"
  • unit: An optional string that provides the name of the custom aggregate for a currency or unit of measure corresponding to this aggregatable property (since 1.86.0). The custom aggregate must return the single value of that unit in case there is only one, or null otherwise ("multi-unit situation"). (SQL suggestion: CASE WHEN MIN(Unit) = MAX(Unit) THEN MIN(Unit) END)

grandTotalAtBottomOnly boolean

Tells whether the grand totals for aggregatable properties are displayed at the bottom only (since 1.86.0); true for bottom only, false for top and bottom, the default is top only

group object

A map from groupable property names to objects containing the following details:

  • additionally: An optional list of strings that provides the paths to properties (like texts or attributes) related to this groupable property in a 1:1 relation (since 1.87.0). They are requested additionally via groupby and must not change the actual grouping; a unit for an aggregatable property must not be repeated here.

groupLevels string[]

A list of groupable property names used to determine group levels. They may, but don't need to, be repeated in oAggregation.group. Group levels cannot be combined with filtering for aggregated properties or (since 1.93.0) with "$search".

search string

Like the "5.1.7 System Query Option $search", but applied before data aggregation (since 1.93.0). Note that certain content will break the syntax of the system query option $apply and result in an invalid request. If the OData service supports the proposal ODATA-1452, then ODataUtils.formatLiteral(sSearch, "Edm.String"); should be used to encapsulate the whole search string beforehand (see sap.ui.model.odata.v4.ODataUtils.formatLiteral).

subtotalsAtBottomOnly boolean

Tells whether subtotals for aggregatable properties are displayed at the bottom only, as a separate row after all children, when a group level node is expanded (since 1.86.0); true for bottom only, false for top and bottom, the default is top only (that is, as part of the group level node)

sort

Sort the entries represented by this list binding according to the given sorters. The sorters are stored at this list binding and they are used for each following data request.

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 #sort.

References:

Param Type DefaultValue Description
vSorters sap.ui.model.Sorter sap.ui.model.Sorter[]

The dynamic sorters to be used; they replace the dynamic sorters given in sap.ui.model.odata.v4.ODataModel#bindList. Static sorters, as defined in the '$orderby' binding parameter, are always executed after the dynamic sorters.

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.

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 '|'.

updateAnalyticalInfo

Updates the binding's system query option $apply based on the given data aggregation information. Its value is "groupby((<dimension_1,...,dimension_N,unit_or_text_1,...,unit_or_text_K>), aggregate(<measure> with <method> as <alias>, ...))" where the "aggregate" part is only present if measures are given and both "with" and "as" are optional. Since 1.93.0, a previous "search before data aggregation" is considered (see the oAggregation.search parameter of #setAggregation).

References:

Param Type DefaultValue Description
aAggregation object[]

An array with objects holding the information needed for data aggregation; see also OData Extension for Data Aggregation Version 4.0

name string

The name of an OData property. A property which is neither a dimension nor a measure, but for instance a text property or in some cases a unit property, has no further details.

grouped boolean

Its presence is used to detect a dimension; the dimension is ignored unless at least one of inResult and visible is true

inResult boolean

Dimensions only: see above

visible boolean

Dimensions only: see above

total boolean

Its presence is used to detect a measure

max boolean

Measures only: Whether the maximum value (ignoring currencies or units of measure) for this measure is needed (since 1.55.0); filtering and sorting is supported in this case (since 1.58.0)

min boolean

Measures only: Whether the minimum value (ignoring currencies or units of measure) for this measure is needed (since 1.55.0); filtering and sorting is supported in this case (since 1.58.0)

with string

Measures only: The name of the method (for example "sum") used for aggregation of this measure; see "3.1.2 Keyword with" (since 1.55.0)

as string

Measures only: The alias, that is the name of the dynamic property used for aggregation of this measure; see "3.1.1 Keyword as" (since 1.55.0)