ListBinding is a specific binding for lists in the model, which can be used to populate Tables or ItemLists.
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) |
Method | Description |
---|---|
attachFilter |
Attaches event handler When called, the context of the event handler (its
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 When called, the context of the event handler (its
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
Since 1.11 use the <code>change</code> event.
|
detachSort |
Detaches event handler
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
|
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 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 FiltersFilters 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 Sample diff array: 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
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. |
getFilterInfo |
Return the filter information as an AST. The default implementation checks for |
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
|
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 |
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 |
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.
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 |
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.
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 |
Detaches event handler fnFunction
from the filter event of this sap.ui.model.ListBinding
.
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 |
Detaches event handler fnFunction
from the sort event of this sap.ui.model.ListBinding
.
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 |
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 |
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 |
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 |
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.
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.
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 |
Returns an array of binding contexts for the bound target list.
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 |
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:
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.
Returns list of distinct values for the given relative binding path.
Param | Type | DefaultValue | Description |
---|---|---|---|
sPath | string |
Relative binding path |
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 |
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 |
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 |
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.
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.
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.
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. |
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.
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 |