class sap.ui.model.analytics.AnalyticalBinding

Visiblity: protected
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/model/analytics/AnalyticalBinding
Application Component: CA-UI5-COR

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.


Constructor

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.
If the select parameter is given, it has to contain all properties that are contained in the analytical information (see sap.ui.model.analytics.AnalyticalBinding#updateAnalyticalInfo). It must not contain additional dimensions or measures or associated properties for additional dimensions or measures. But it may contain additional properties like a text property of a dimension that is also selected.
All properties of the select parameter are also considered in sap.ui.model.analytics.AnalyticalBinding#getDownloadUrl.
The select parameter must not contain any duplicate entry.
If the select parameter does not fit to the analytical information or if the select parameter contains duplicates, a warning is logged and the select parameter is ignored.


Methods Overview

Method Description
sap.ui.model.analytics.AnalyticalBinding.extend

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.

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 undefined if this is unknown.

References:

  • sap.ui.model.odata.v4.ODataListBinding#getCount

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

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

getSortablePropertyNames

Gets the names of the sortable properties in the bound OData entity set.

getTotalSize

Gets the total number of leaves or -1 if this is unknown.

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 name of the bound property and in addition:

  1. A column bound to a dimension property has further boolean properties:
    • grouped: dimension is used for building groups
    • inResult: if the column is not visible, but declared to be part of the result, values for the related property are also fetched from the OData service
    • visible: if the column is visible, values for the related property are fetched from the OData service
  2. A column bound to a measure property has further boolean properties:
    • inResult: if the column is not visible, but declared to be part of the result, values for the related property are also fetched from the OData service
    • total: totals and sub-totals are provided for the measure at all aggregation levels
    • visible: if the column is visible, values for the related property are fetched from the OData service
  3. A column bound to a hierarchy property has further properties:
    • grouped: boolean value; indicates whether the hierarchy is used for building groups
    • level: integer value; the hierarchy level is mandatory for at least one of those columns that represent the same hierarchy

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.

sap.ui.model.analytics.AnalyticalBinding.extend

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

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.

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.

getAnalyticalInfoForColumn

Gets the analytical information for a column with a given name.

Param Type DefaultValue Description
sColumnName string

the column name.

getAnalyticalQueryResult

Gets analytical metadata for the bound OData entity set.

getCount

Gets the total number of leaves or undefined if this is unknown.

References:

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.

Param Type DefaultValue Description
sFormat string

Value for the $format Parameter

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.

Param Type DefaultValue Description
bIncludeOrigin boolean false

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

getGroupName

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)

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.

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)

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.

Param Type DefaultValue Description
mParameters object

specifying the aggregation level for which contexts shall be fetched. Supported parameters are:

  • oContext: parent context identifying the requested group of child contexts
  • level: level number for oContext, because it might occur at multiple levels; context with group ID "/" has level 0
  • numberOfExpandedLevels: number of child levels that shall be fetched automatically
  • startIndex: index of first child entry to return from the parent context (zero-based)
  • length: number of entries to return; counting begins at the given start index
  • threshold: number of additional entries that shall be locally available in the binding for subsequent accesses to child entries of the given parent context.

getProperty

Gets the metadata of a property with a given name.

Param Type DefaultValue Description
sPropertyName string

The property name.

getPropertyHeading

Gets the label of a property with a given name.

Param Type DefaultValue Description
sPropertyName string

The property name.

getPropertyLabel

Gets the label of a property with a given name.

Param Type DefaultValue Description
sPropertyName string

The property name.

getPropertyQuickInfo

Gets the quick info of a property with a given name.

Param Type DefaultValue Description
sPropertyName string

The property 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 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 startIndex as described in this parameter list. In this case, the function parameters iLength, iNumberOfExpandedLevels and iThreshold become mandatory.

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 "/" (zero-based)

threshold int

Number of additional entries that shall be locally available in the binding for subsequent accesses to contexts of parent group ID "/" or below, if auto-expanding is selected

iLength int

See documentation of the length parameter in the parameter list of mParameters

iNumberOfExpandedLevels int 0

See documentation of the numberOfExpandedLevels parameter in the parameter list of mParameters

iThreshold int 0

See documentation of the threshold parameter in the parameter list of mParameters

getSortablePropertyNames

Gets the names of the sortable properties in the bound OData entity set.

getTotalSize

Gets the total number of leaves or -1 if this is unknown.

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.

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

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.

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 as the level number of oContext (because the context might occur at multiple levels)

level int 1

The aggregation level number

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

Param Type DefaultValue Description
sPropertyName string

The property name.

loadGroups

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.

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.

Param Type DefaultValue Description
bForceUpdate boolean

Update the bound control even if no data has been changed

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.

Param Type DefaultValue Description
aSorter sap.ui.model.Sorter array

a sorter object or an array of sorter objects which define the sort order.

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 name of the bound property and in addition:

  1. A column bound to a dimension property has further boolean properties:
    • grouped: dimension is used for building groups
    • inResult: if the column is not visible, but declared to be part of the result, values for the related property are also fetched from the OData service
    • visible: if the column is visible, values for the related property are fetched from the OData service
  2. A column bound to a measure property has further boolean properties:
    • inResult: if the column is not visible, but declared to be part of the result, values for the related property are also fetched from the OData service
    • total: totals and sub-totals are provided for the measure at all aggregation levels
    • visible: if the column is visible, values for the related property are fetched from the OData service
  3. A column bound to a hierarchy property has further properties:
    • grouped: boolean value; indicates whether the hierarchy is used for building groups
    • level: integer value; the hierarchy level is mandatory for at least one of those columns that represent the same hierarchy

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