abstract class sap.ui.model.ListBinding

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

ListBinding is a specific binding for lists in the model, which can be used to populate Tables or ItemLists.


Constructor

Constructor for ListBinding.

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

Model instance that this binding belongs to

sPath string

Binding path for this binding; a relative path will be resolved relative to a given context

oContext sap.ui.model.Context

Context to be used to resolve a relative path

aSorters? sap.ui.model.Sorter sap.ui.model.Sorter[]

Initial sort order (can be either a sorter or an array of sorters)

aFilters? sap.ui.model.Filter sap.ui.model.Filter[]

Predefined filter/s (can be either a filter or an array of filters)

mParameters? object

Additional, implementation-specific parameters that should be used by the new list binding; this base class doesn't define any parameters, check the API reference for the concrete model implementations to learn about their supported parameters (if any)


Events Overview

Event Description
filter

The filter event is fired when the list binding is filtered.

sort

The sort event is fired when the list binding is sorted.

filter

The filter event is fired when the list binding is filtered.

use the <code>change</code> event. It now contains a parameter <code>(reason : "filter")</code> when a filter event is fired.
Param Type Description
oEvent sap.ui.base.Event

sort

The sort event is fired when the list binding is sorted.

use the <code>change</code> event. It now contains a parameter <code>(reason : "sort")</code> when a sorter event is fired.
Param Type Description
oEvent sap.ui.base.Event

Methods Overview

Method Description
attachFilter

Attaches event handler fnFunction to the filter event of this sap.ui.model.ListBinding.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.model.ListBinding itself.

Since 1.11 use the <code>change</code> event. It now contains a parameter <code>(reason : "filter")</code> when a filter event is fired.
attachSort

Attaches event handler fnFunction to the sort event of this sap.ui.model.ListBinding.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.model.ListBinding itself.

Since 1.11 use the <code>change</code> event. It now contains a parameter <code>(reason : "sort")</code> when a sorter event is fired.
detachFilter

Detaches event handler fnFunction from the filter event of this sap.ui.model.ListBinding.

Since 1.11 use the <code>change</code> event.
detachSort

Detaches event handler fnFunction from the sort event of this sap.ui.model.ListBinding.

Since 1.11 use the <code>change</code> event.
diffData

Calculates delta of specified old data array and new data array.

For more information, see module:sap/base/util/array/diff.

enableExtendedChangeDetection

Enable extended change detection. When extended change detection is enabled, the list binding provides detailed information about changes, for example which entries have been removed or inserted. This can be utilized by a control for fine-grained update of its elements. Please see sap.ui.model.ListBinding.prototype.getContexts for more information.

For models that do not have a unique key on each entry by default, a key property or function can be set which is used to identify entries.

sap.ui.model.ListBinding.extend

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

filter

Applies a new set of filters to the list represented by this binding.

Depending on the nature of the model (client or server), the operation might be executed locally or on a server and it might execute asynchronously.

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. If no type is given, then the behavior depends on the model implementation and should be documented in the API reference for that model.

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 an array of binding contexts for the bound target list.

Extended Change Detection

If extended change detection is enabled using sap.ui.model.ListBinding.prototype.enableExtendedChangeDetection, the context array may carry an additional property named diff, which contains an array of actual changes on the context array compared to the last call of getContexts(). In case no diff property is available on the context array, the list is completely different and needs to be recreated. In case the diff property contains an empty array, there have been no changes on the list.

Sample diff array: [{index: 1, type: "delete"}, {index: 4, type: "insert}]

Note:The public usage of this method is deprecated, as calls from outside of controls will lead to unexpected side effects. To avoid these side effect, use sap.ui.model.ListBinding.prototype.getCurrentContexts instead.

getCount

Returns the count of entries in the list, or undefined if it is unknown. The count is by default identical to the list length if it is final. Concrete subclasses may, however, override the method, for example:

  • for server-side models where lists are not completely read by the client,
  • for lists representing hierarchical data.


References:
  • #getLength
  • #isLengthFinal

getCurrentContexts

Returns an array of currently used binding contexts of the bound control.

This method does not trigger any data requests from the back end or a delta calculation, but just returns the context array as last requested by the control. This can be used by the application to get access to the data currently displayed by a list control.

getDistinctValues

Returns list of distinct values for the given relative binding path.

getFilterInfo

Return the filter information as an AST. The default implementation checks for this.oCombinedFilter. Models not using this member may override the method. Consumers must not rely on the origin information to be available as future filter implementations will not provide this information.

getFilters

Returns the filters set via the constructor or via #filter for the given sap.ui.model.FilterType.

getGroup

Gets the group for the given context. Must only be called if isGrouped() returns that grouping is enabled for this binding. The grouping will be performed using the first sorter (in case multiple sorters are defined).

References:

  • sap.ui.model.Sorter#getGroup

getLength

Returns the number of entries in the list.

This might be an estimated or preliminary length, in case the full length is not known yet, see method #isLengthFinal.

sap.ui.model.ListBinding.getMetadata

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

isGrouped

Indicates whether grouping is enabled for the binding. Grouping is enabled for a list binding if at least one sorter exists on the binding and the first sorter is a grouping sorter.

isLengthFinal

Returns whether the length which can be retrieved using getLength() is a known, final length, or a preliminary or estimated length which may change if further data is requested.

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.

The implementation of this method is optional for model specific implementations of sap.ui.model.ListBinding. Check for existence of this function before calling it.

sort

Sorts the list according to the sorter object.

Instead of a single sorter also an array of sorters can be passed to the sort method. In this case they are processed in the sequence in which they are contained in the array.

Grouping

Sorting and grouping are closely related. In case a list should be grouped, it must be sorted by the property to group with. Grouping is enabled by setting the group property on the sorter object. If it is enabled, you can get the current group of an item using sap.ui.model.ListBinding.prototype.getGroup. In case multiple sorters are provided, grouping can only be done on the first sorter, nested grouping is not supported.

attachFilter

Attaches event handler fnFunction to the filter event of this sap.ui.model.ListBinding.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.model.ListBinding itself.

Since 1.11 use the <code>change</code> event. It now contains a parameter <code>(reason : "filter")</code> when a filter event is fired.
Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Context object to call the event handler with; defaults to this ListBinding itself

attachSort

Attaches event handler fnFunction to the sort event of this sap.ui.model.ListBinding.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.model.ListBinding itself.

Since 1.11 use the <code>change</code> event. It now contains a parameter <code>(reason : "sort")</code> when a sorter event is fired.
Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Context object to call the event handler with; defaults to this ListBinding itself

detachFilter

Detaches event handler fnFunction from the filter event of this sap.ui.model.ListBinding.

Since 1.11 use the <code>change</code> event.
Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

On which object the given function had to be called

detachSort

Detaches event handler fnFunction from the sort event of this sap.ui.model.ListBinding.

Since 1.11 use the <code>change</code> event.
Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

diffData

Calculates delta of specified old data array and new data array.

For more information, see module:sap/base/util/array/diff.

Param Type DefaultValue Description
aOld Array

Old data array

aNew Array

New data array

enableExtendedChangeDetection

Enable extended change detection. When extended change detection is enabled, the list binding provides detailed information about changes, for example which entries have been removed or inserted. This can be utilized by a control for fine-grained update of its elements. Please see sap.ui.model.ListBinding.prototype.getContexts for more information.

For models that do not have a unique key on each entry by default, a key property or function can be set which is used to identify entries.

Param Type DefaultValue Description
bDetectUpdates boolean

Whether changes within the same entity should cause a delete and insert command

vKey function string

The path of the property containing the key or a function getting the context as only parameter to calculate a key to identify an entry

oExtendedChangeDetectionConfig object

The configuration for the change detection

sap.ui.model.ListBinding.extend

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

Applies a new set of filters to the list represented by this binding.

Depending on the nature of the model (client or server), the operation might be executed locally or on a server and it might execute asynchronously.

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. If no type is given, then the behavior depends on the model implementation and should be documented in the API reference for that model.

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.

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

Single filter object or an array of filter objects

sFilterType sap.ui.model.FilterType

Type of the filter which should be adjusted; if no type is given, the behavior depends on the model implementation

getContexts

Returns an array of binding contexts for the bound target list.

Extended Change Detection

If extended change detection is enabled using sap.ui.model.ListBinding.prototype.enableExtendedChangeDetection, the context array may carry an additional property named diff, which contains an array of actual changes on the context array compared to the last call of getContexts(). In case no diff property is available on the context array, the list is completely different and needs to be recreated. In case the diff property contains an empty array, there have been no changes on the list.

Sample diff array: [{index: 1, type: "delete"}, {index: 4, type: "insert}]

Note:The public usage of this method is deprecated, as calls from outside of controls will lead to unexpected side effects. To avoid these side effect, use sap.ui.model.ListBinding.prototype.getCurrentContexts instead.

Param Type DefaultValue Description
iStartIndex int 0

The startIndex where to start the retrieval of contexts

iLength int length of the list

Determines how many contexts to retrieve beginning from the start index.

iMaximumPrefetchSize int

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; this parameter is model-specific and not implemented by all models

bKeepCurrent boolean

Whether this call keeps the result of #getCurrentContexts untouched; since 1.86.0. This parameter is model-specific and not implemented by all models

getCount

Returns the count of entries in the list, or undefined if it is unknown. The count is by default identical to the list length if it is final. Concrete subclasses may, however, override the method, for example:



References:

getCurrentContexts

Returns an array of currently used binding contexts of the bound control.

This method does not trigger any data requests from the back end or a delta calculation, but just returns the context array as last requested by the control. This can be used by the application to get access to the data currently displayed by a list control.

getDistinctValues

Returns list of distinct values for the given relative binding path.

Param Type DefaultValue Description
sPath string

Relative binding path

getFilterInfo

Return the filter information as an AST. The default implementation checks for this.oCombinedFilter. Models not using this member may override the method. Consumers must not rely on the origin information to be available as future filter implementations will not provide this information.

Param Type DefaultValue Description
bIncludeOrigin boolean

Include information about the filter objects the tree has been created from

getFilters

Returns the filters set via the constructor or via #filter for the given sap.ui.model.FilterType.

Param Type DefaultValue Description
sFilterType sap.ui.model.FilterType

The FilterType

getGroup

Gets the group for the given context. Must only be called if isGrouped() returns that grouping is enabled for this binding. The grouping will be performed using the first sorter (in case multiple sorters are defined).

References:

Param Type DefaultValue Description
oContext sap.ui.model.Context

The binding context

getLength

Returns the number of entries in the list.

This might be an estimated or preliminary length, in case the full length is not known yet, see method #isLengthFinal.

sap.ui.model.ListBinding.getMetadata

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

isGrouped

Indicates whether grouping is enabled for the binding. Grouping is enabled for a list binding if at least one sorter exists on the binding and the first sorter is a grouping sorter.

isLengthFinal

Returns whether the length which can be retrieved using getLength() is a known, final length, or a preliminary or estimated length which may change if further data is requested.

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.

The implementation of this method is optional for model specific implementations of sap.ui.model.ListBinding. Check for existence of this function before calling it.

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.

sort

Sorts the list according to the sorter object.

Instead of a single sorter also an array of sorters can be passed to the sort method. In this case they are processed in the sequence in which they are contained in the array.

Grouping

Sorting and grouping are closely related. In case a list should be grouped, it must be sorted by the property to group with. Grouping is enabled by setting the group property on the sorter object. If it is enabled, you can get the current group of an item using sap.ui.model.ListBinding.prototype.getGroup. In case multiple sorters are provided, grouping can only be done on the first sorter, nested grouping is not supported.

Param Type DefaultValue Description
aSorters sap.ui.model.Sorter Array

The Sorter object or an array of sorters which defines the sort order