Tree binding implementation for OData entity sets with aggregate semantics.
Note on the handling of different count modes: The AnalyticalBinding always uses the OData $inlinecount system query option to determine the total count of matching entities. It ignores the default count mode set in the ODataModel instance and the count mode specified in the binding parameters. If the default count mode is None
, a warning is added to the log to remind the application that OData requests generated by the AnalyticalBinding will include a $inlinecount. If a count mode has been specified in the binding parameters, an error message is logged if it is None
, because the binding still adds the $inlinecount to OData requests. If a binding count mode is set to Request
or Both
, a warning is logged to remind the application that the OData requests generated by the AnalyticalBinding include a $inlinecount.
new sap.ui.model.analytics.AnalyticalBinding(oModel, sPath, oContext?, aSorter?, aFilters?, mParameters?)
Param | Type | Default Value | Description |
---|---|---|---|
oModel | sap.ui.model.Model | The OData model |
|
sPath | string | The path pointing to the tree / array that should be bound |
|
oContext? | object | The context object for this data binding |
|
aSorter? | array | An array of predefined sorters |
|
aFilters? | array | An array of predefined filters |
|
mParameters? | object | A map containing additional binding parameters |
|
autoExpandMode? | sap.ui.model.TreeAutoExpandMode | sap.ui.model.TreeAutoExpandMode.Bundled | The auto expand mode; applying sorters to groups is only possible in auto expand mode sap.ui.model.TreeAutoExpandMode.Sequential |
entitySet? | undefined | The entity set addressed by the last segment of the given binding path |
|
useBatchRequests? | undefined | false | Whether multiple OData requests are wrapped into a single $batch request wherever possible |
provideGrandTotals? | undefined | true | Whether grand total values are provided for all bound measure properties |
provideTotalResultSize? | undefined | true | Whether the total number of matching entries in the bound OData entity set is provided |
reloadSingleUnitMeasures? | undefined | true | Whether the binding checks aggregated entries with multi-unit occurrences, if some measure properties have a unique unit and will trigger separate OData requests to fetch them |
select? | string | A comma-separated list of property names that need to be selected. |
Method | Description |
---|---|
sap.ui.model.analytics.AnalyticalBinding.extend |
Creates a new subclass of class sap.ui.model.analytics.AnalyticalBinding with name
|
filter |
Sets filters for matching only a subset of the entities in the bound OData entity set. Invoking this function resets the state of the binding. Subsequent data requests such as calls to getNodeContexts() will need to trigger OData requests in order to fetch the data that are in line with these filters. |
getAnalyticalInfoForColumn |
Gets the analytical information for a column with a given name. |
getAnalyticalQueryResult |
Gets analytical metadata for the bound OData entity set. |
getCount |
Gets the total number of leaves or
|
getDimensionDetails |
Gets details about the dimension properties included in the bound OData entity set. |
getDownloadUrl |
Get a download URL with the specified format considering the sort/filter/custom parameters. The download URL also takes into account the selected dimensions and measures, depending on the given column definitions of the AnalyticalTable. This is based on the visible/inResult flags of the columns, as well as integrity dependencies, e.g. for mandatory Unit properties. |
getFilterablePropertyNames |
Gets the names of the filterable properties in the bound OData entity set. |
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. |
getGroupName |
Gets a printable name for a group. The printable name follows the pattern is Whenever a formatter function has been defined for a column displaying the key or text of this dimension, the return value of this function is applied for the group name instead of the respective key or text value. |
getGroupSize |
Gets the total number of contexts contained in a group, if known. For a given group, be aware that the group size might vary over time. In principle, this can happen if the bound set of OData entities includes measure properties with amount or quantity values. The AnalyticalBinding recognizes situations where the OData service returns multiple entries for a single group entry due to the fact that a measure property cannot be aggregated properly, because an amount exists in multiple currencies or a quantity exists in multiple units. In such situations, the AnalyticalBinding substitutes these entries by a single representative, and the group size gets reduced by the count of duplicate entries. Finally, since the Binding does not always fetch all children of a group at once, but only a page with a certain range, such size changes might happen after every page access. |
getMeasureDetails |
Gets details about the measure properties included in the bound OData entity set. |
sap.ui.model.analytics.AnalyticalBinding.getMetadata |
Returns a metadata object for class sap.ui.model.analytics.AnalyticalBinding. |
getNodeContexts |
Gets child contexts for a specified parent context. Contexts are returned in a stable order imposed by the dimension property that defines this aggregation level beneath the parent context: Either a sort order has been specified for this property, or the entries are returned in ascending order of the values of this dimension property by default. If any of the requested data is missing, an OData request will be triggered to load it. |
getProperty |
Gets the metadata of a property with a given name. |
getPropertyHeading |
Gets the label of a property with a given name. |
getPropertyLabel |
Gets the label of a property with a given name. |
getPropertyQuickInfo |
Gets the quick info of a property with a given name. |
getRootContexts |
Gets the context for the root aggregation level representing the grand total for all bound measure properties. The context is assigned to parent group ID This function must be called whenever the bound set of OData entities changes, e.g., by changing selected dimensions, modifying filter conditions, etc. |
getSortablePropertyNames |
Gets the names of the sortable properties in the bound OData entity set. |
getTotalSize |
Gets the total number of leaves or
Since 1.92 use {@link #getCount} instead
|
hasAvailableNodeContexts |
Determines if the binding has the entries of a given aggregation level locally available. If so, no further OData request is required to fetch any of them. |
hasChildren |
Determines if the contexts in a specified group have further children. If so, any of these group contexts can be a parent context of a nested sub-group in a subsequent aggregation level. |
hasMeasures |
Determines if any of the properties included in the bound OData entity set is a measure property. |
isMeasure |
Determines if a given name refers to a measure property |
loadGroups |
Loads child contexts of multiple groups. |
providesGrandTotal |
Determines if the binding has been configured to provide a grand total for the selected measure properties. |
refresh |
Refreshes the binding, check whether the model data has been changed and fire change event if this is the case. For service side models this should refetch the data from the service. To update a control, even if no data has been changed, e.g. to reset a control after failed validation, please use the parameter bForceUpdate. |
sort |
Sets sorters for retrieving the entities in the bound OData entity set in a specific order. Invoking this function resets the state of the binding. Subsequent data requests such as calls to getNodeContexts() will need to trigger OData requests in order to fetch the data that are in line with these sorters. |
updateAnalyticalInfo |
Updates the binding's structure with new analytical information. Analytical information is the mapping of UI columns to properties in the bound OData entity set. Every column object contains the
Invoking this function resets the state of the binding and subsequent data requests such as calls to getNodeContexts() trigger OData requests in order to fetch the data that are in line with this analytical information. Be aware that a call of this function might lead to additional back-end requests, as well as a control re-rendering later on. Whenever possible use the API of the analytical control, instead of relying on the binding. |
Creates a new subclass of class sap.ui.model.analytics.AnalyticalBinding 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.TreeBinding.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 |
Sets filters for matching only a subset of the entities in the bound OData entity set.
Invoking this function resets the state of the binding. Subsequent data requests such as calls to getNodeContexts() will need to trigger OData requests in order to fetch the data that are in line with these filters.
Param | Type | DefaultValue | Description |
---|---|---|---|
aFilter | sap.ui.model.Filter[] sap.ui.model.Filter |
an Array of sap.ui.model.Filter objects or a single Filter instance. |
|
sFilterType | sap.ui.model.FilterType | sap.ui.model.FilterType.Control |
Type of the filter which should be adjusted. |
Gets the analytical information for a column with a given name.
Param | Type | DefaultValue | Description |
---|---|---|---|
sColumnName | string |
the column name. |
Gets the total number of leaves or undefined
if this is unknown.
References:
Gets details about the dimension properties included in the bound OData entity set.
Get a download URL with the specified format considering the sort/filter/custom parameters.
The download URL also takes into account the selected dimensions and measures, depending on the given column definitions of the AnalyticalTable. This is based on the visible/inResult flags of the columns, as well as integrity dependencies, e.g. for mandatory Unit properties.
Param | Type | DefaultValue | Description |
---|---|---|---|
sFormat | string |
Value for the $format Parameter |
Gets the names of the filterable properties in the bound OData entity set.
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.
Param | Type | DefaultValue | Description |
---|---|---|---|
bIncludeOrigin | boolean | false |
whether to include information about the filter objects from which the tree has been created |
Gets a printable name for a group.
The printable name follows the pattern is <label>:<key-value>[-<text-value>]
, where label
is the label of the dimension property used at the aggregation level for the group, key-value
is the key value of that dimension for the group, and text-value
is the value of the associated text property, if it is also used in the binding.
Whenever a formatter function has been defined for a column displaying the key or text of this dimension, the return value of this function is applied for the group name instead of the respective key or text value.
Param | Type | DefaultValue | Description |
---|---|---|---|
oContext | sap.ui.model.Context |
the parent context identifying the requested group. |
|
iLevel | int |
the level number of oContext (because the context might occur at multiple levels) |
Gets the total number of contexts contained in a group, if known.
For a given group, be aware that the group size might vary over time. In principle, this can happen if the bound set of OData entities includes measure properties with amount or quantity values. The AnalyticalBinding recognizes situations where the OData service returns multiple entries for a single group entry due to the fact that a measure property cannot be aggregated properly, because an amount exists in multiple currencies or a quantity exists in multiple units. In such situations, the AnalyticalBinding substitutes these entries by a single representative, and the group size gets reduced by the count of duplicate entries. Finally, since the Binding does not always fetch all children of a group at once, but only a page with a certain range, such size changes might happen after every page access.
Param | Type | DefaultValue | Description |
---|---|---|---|
oContext | sap.ui.model.Context |
the parent context identifying the requested group of child contexts. |
|
iLevel | int |
the level number of oContext (because the context might occur at multiple levels) |
Returns a metadata object for class sap.ui.model.analytics.AnalyticalBinding.
Gets child contexts for a specified parent context.
Contexts are returned in a stable order imposed by the dimension property that defines this aggregation level beneath the parent context: Either a sort order has been specified for this property, or the entries are returned in ascending order of the values of this dimension property by default.
If any of the requested data is missing, an OData request will be triggered to load it.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
specifying the aggregation level for which contexts shall be fetched. Supported parameters are:
|
Gets the metadata of a property with a given name.
Param | Type | DefaultValue | Description |
---|---|---|---|
sPropertyName | string |
The property name. |
Gets the label of a property with a given name.
Param | Type | DefaultValue | Description |
---|---|---|---|
sPropertyName | string |
The property name. |
Gets the label of a property with a given name.
Param | Type | DefaultValue | Description |
---|---|---|---|
sPropertyName | string |
The property name. |
Gets the quick info of a property with a given name.
Param | Type | DefaultValue | Description |
---|---|---|---|
sPropertyName | string |
The property name. |
Gets the context for the root aggregation level representing the grand total for all bound measure properties.
The context is assigned to parent group ID null
. If the binding is configured not to provide a grand total, this context is empty. If data for this context is not locally available yet, an OData request will be triggered to load it.
This function must be called whenever the bound set of OData entities changes, e.g., by changing selected dimensions, modifying filter conditions, etc.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object int |
Parameter map specifying how the topmost aggregation level shall be fetched. If this parameter map is set, the optional function parameters are ignored. Optionally, instead of a parameter map an integer value can be set to define the parameter |
|
length | int |
Number of entries to return at and after the given start index; defaults to the model's size limit, see sap.ui.model.Model#setSizeLimit |
|
numberOfExpandedLevels | int |
Number of child levels that shall be fetched automatically |
|
startIndex | int |
Index of first entry to return from parent group ID |
|
threshold | int |
Number of additional entries that shall be locally available in the binding for subsequent accesses to contexts of parent group ID |
|
iLength | int |
See documentation of the |
|
iNumberOfExpandedLevels | int | 0 |
See documentation of the |
iThreshold | int | 0 |
See documentation of the |
Gets the total number of leaves or -1
if this is unknown.
Determines if the binding has the entries of a given aggregation level locally available.
If so, no further OData request is required to fetch any of them.
Param | Type | DefaultValue | Description |
---|---|---|---|
oContext | sap.ui.model.Context |
the parent context identifying the aggregation level. |
|
iLevel | int |
the level number of oContext (because the context might occur at multiple levels). |
Determines if the contexts in a specified group have further children. If so, any of these group contexts can be a parent context of a nested sub-group in a subsequent aggregation level.
Param | Type | DefaultValue | Description |
---|---|---|---|
oContext | sap.ui.model.Context |
The parent context identifying the requested group of child contexts |
|
mParameters | object |
The only supported parameter is |
|
level | int | 1 |
The aggregation level number |
Determines if any of the properties included in the bound OData entity set is a measure property.
Determines if a given name refers to a measure property
Param | Type | DefaultValue | Description |
---|---|---|---|
sPropertyName | string |
The property name. |
Loads child contexts of multiple groups.
Param | Type | DefaultValue | Description |
---|---|---|---|
mGroupIdRanges | Object<string,array> |
specifies index ranges of child contexts to be loaded for multiple groups identified by their ID. A group index range is given by an object consisting of startIndex, length, threshold. For every group ID, the map holds an array of such range objects. |
Determines if the binding has been configured to provide a grand total for the selected measure properties.
Refreshes the binding, check whether the model data has been changed and fire change event if this is the case. For service side models this should refetch the data from the service. To update a control, even if no data has been changed, e.g. to reset a control after failed validation, please use the parameter bForceUpdate.
Param | Type | DefaultValue | Description |
---|---|---|---|
bForceUpdate | boolean |
Update the bound control even if no data has been changed |
Sets sorters for retrieving the entities in the bound OData entity set in a specific order.
Invoking this function resets the state of the binding. Subsequent data requests such as calls to getNodeContexts() will need to trigger OData requests in order to fetch the data that are in line with these sorters.
Param | Type | DefaultValue | Description |
---|---|---|---|
aSorter | sap.ui.model.Sorter array |
a sorter object or an array of sorter objects which define the sort order. |
Updates the binding's structure with new analytical information.
Analytical information is the mapping of UI columns to properties in the bound OData entity set. Every column object contains the name
of the bound property and in addition:
Invoking this function resets the state of the binding and subsequent data requests such as calls to getNodeContexts() trigger OData requests in order to fetch the data that are in line with this analytical information.
Be aware that a call of this function might lead to additional back-end requests, as well as a control re-rendering later on. Whenever possible use the API of the analytical control, instead of relying on the binding.
Param | Type | DefaultValue | Description |
---|---|---|---|
aColumns | object[] |
An array with objects holding the analytical information for every column |
|
bForceChange | boolean |
Whether to fire a change event asynchronously even if columns didn't change |