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.
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. |
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. |
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. |
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 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. |
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. |
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. |
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
|
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); |
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 |
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 |
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. |
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 |
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 |
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 |
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
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. |
Method | Description |
---|---|
attachCreateCompleted |
Attach event handler |
attachCreateSent |
Attach event handler |
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 |
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 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 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 |
destroy |
Destroys the object. The object must not be used anymore after this function was called.
|
detachCreateCompleted |
Detach event handler |
detachCreateSent |
Detach event handler |
detachPatchCompleted |
Detach event handler |
detachPatchSent |
Detach event handler |
sap.ui.model.odata.v4.ODataListBinding.extend |
Creates a new subclass of class sap.ui.model.odata.v4.ODataListBinding with name
|
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 Application and Control FiltersEach 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 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.
|
getContexts |
Returns already created binding contexts for all entities in this list binding for the range determined by the given start index |
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 The count is known to the binding in the following situations:
The The count is bindable via the header context (see #getHeaderContext) and path Use |
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
|
getDistinctValues |
Method not supported
|
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 Additionally, you must be aware of server-driven paging and be ready to send a follow-up request if the response contains
|
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
|
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
|
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.
|
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 Note: If this binding is relative, its data is cached separately for each parent context path. This method returns |
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
|
isInitial |
Method not supported |
isLengthFinal |
Returns
|
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.
|
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 Additionally, you must be aware of server-driven paging and be ready to send a follow-up request if the response contains
|
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.
|
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.
|
setAggregation |
Sets a new data aggregation object and derives the system query option |
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.
|
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 '|'. |
updateAnalyticalInfo |
Updates the binding's system query option
|
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 |
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 |
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 |
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 |
Destroys the object. The object must not be used anymore after this function was called.
References:
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 |
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 |
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 |
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 |
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.
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.
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 |
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; |
|
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; |
bKeepCurrent | boolean |
Whether this call keeps the result of #getCurrentContexts untouched; since 1.86.0. |
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:
$count
system query option. $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.
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:
Method not supported
References:
Param | Type | DefaultValue | Description |
---|---|---|---|
_sPath | string |
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:
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" Param | Type | DefaultValue | Description |
---|---|---|---|
bIncludeOrigin | boolean |
whether to include information about the filter objects from which the tree has been created |
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 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:
Returns a metadata object for class sap.ui.model.odata.v4.ODataListBinding.
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 |
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 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:
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:
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 |
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, |
|
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 |
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:
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. |
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 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, |
|
aggregate | object |
A map from aggregatable property names or aliases to objects containing the following details:
|
|
grandTotalAtBottomOnly | boolean |
Tells whether the grand totals for aggregatable properties are displayed at the bottom only (since 1.86.0); |
|
group | object |
A map from groupable property names to objects containing the following details:
|
|
groupLevels | string[] |
A list of groupable property names used to determine group levels. They may, but don't need to, be repeated in |
|
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 |
|
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); |
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. |
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:
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 '|'.
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 | 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) |