Visual Filter Setup

An intuitive way of choosing filter values from an associated measure value.This setup supports line, bar, and donut charts.

SelectionFields annotation for which a visual filter is defined.

Note

The ALP ignores the UI.Hidden fields when you select filters if the IN mapping points to a field marked with UI.Hidden in the valuelist entity set. For example, the Status_ID from the main entity set points to StatusCode in the value help entity set (of the visual filter). If the StatusCode is marked as UI.Hidden, then the incoming value is ignored.

Configuring the sap:value-list=fixed-values property in the annotation.xml file lets you display visual filter values in a dropdown list. This allows users to select or deselect values that are not displayed in the chart. If the dropdown list is enabled, ensure that the records available in the collection path entity set of the visual filter and compact filter are the same for a smooth sync between the visual filter and the compact filter.

The visual filter includes only the first measure and dimension from the first chart annotation within the specified PresentationVariantQualifier. Make sure that the dimension you specify in the chart and the ValueListProperty of the OUT parameter is the same. You can also define a SortOrder property in the PresentationVariant annotation to control the sort order based on a sort field.

Note

Sorting in visual filters is based on this logic:

For bar and donut chart types, sorting is always based on the measure displayed (the default is descending order). To change the sort order property, define the SortOrder property in the PresentationVariant annotation.
For line charts with time-based dimensions, sorting is always based on the dimension displayed in ascending order, however, only the last six time periods are displayed.
The sorting by the annotation is ignored for time-based dimensions for line-charts in the visual filter.
For line charts with non time-based dimensions, sorting is always based on the dimension (the default is ascending order). To change the sort order, define the SortOrder property in the PresentationVariant annotation.

This image is interactive. Hover over each area for a description. Click highlighted areas for more information

Hover over each action for a description. Click the action for more information.

ValueList Annotation

This is an example of a code snippet for a value list annotation. You use it to configure visual filters. For more information, see Defining ValueList Annotations.

Sample Code

ValueList Annotation Sample

<Annotations xmlns="http://docs.oasis-open.org/odata/ns/edm" Target="SEPMRA_ALP_SO_ANA_SRV.SEPMRA_C_ALP_SlsOrdItemCubeALPResult/SalesOrderOverallStatus">
   <Annotation Term="Common.ValueList" Qualifier="VisualFilter">
      <Record>
         <PropertyValue Property="Label" String="Overall Status" />
         <PropertyValue Property="CollectionPath" String="SEPMRA_C_ALP_SlsOrdItemCubeALPResults" />
         <PropertyValue Property="SearchSupported" Bool="false" />
         <PropertyValue Property="PresentationVariantQualifier" String="FilterNumberOfSalesOrdersByStatus" />
         <PropertyValue Property="SelectionVariantQualifier" String="SVForStatus" />
         <PropertyValue Property="Parameters">
            <Collection>
               <Record Type="Common.ValueListParameterInOut">
                  <PropertyValue Property="LocalDataProperty" PropertyPath="SalesOrderOverallStatus" />
                  <PropertyValue Property="ValueListProperty" String="SalesOrderOverallStatus" />
               </Record>
               <Record Type="Common.ValueListParameterInOut">
                  <PropertyValue Property="LocalDataProperty" PropertyPath="MainProductCategory" />
                  <PropertyValue Property="ValueListProperty" String="MainProductCategory" />
               </Record>
               <Record Type="Common.ValueListParameterInOut">
                  <PropertyValue Property="LocalDataProperty" PropertyPath="ProductCategory" />
                  <PropertyValue Property="ValueListProperty" String="ProductCategory" />
               </Record>
            </Collection>
         </PropertyValue>
      </Record>
   </Annotation>
</Annotations>

Note

See the Defining ValueList Annotations section for information about the IN/OUT mapping of visual filters.

PresentationVariantQualifier

The PresentationVariant qualifier provides chart definitions for visual filters. The visual filter picks up the first chart annotation in the PresentationVariant annotation to render the chart. If the chart type is not supported, the ALP renders a bar chart (default chart type).

<Annotation Term="UI.PresentationVariant" Qualifier="FilterNumberOfSalesOrdersByStatus">
   <Record>
      <PropertyValue Property="Text" String="Filter: Number of Sales Order by Status" />
      <PropertyValue Property="SortOrder">
         <Collection>
            <Record Type="Common.SortOrderType">
               <PropertyValue Property="Property" PropertyPath="NumberOfSalesOrders" />
               <PropertyValue Property="Descending" Bool="true" />
            </Record>
         </Collection>
      </PropertyValue>
      <PropertyValue Property="Visualizations">
         <Collection>
            <AnnotationPath>@UI.Chart#FilterNumberOfSalesOrdersByStatus</AnnotationPath>
         </Collection>
      </PropertyValue>
   </Record>
</Annotation>

Chart Annotation

<Annotation Term="UI.Chart" Qualifier="FilterNumberOfSalesOrdersByStatus">
   <Record Type="UI.ChartDefinitionType">
      <PropertyValue Property="Title" String="Sales Orders by Status" />
      <PropertyValue Property="Description" String="Number of Sales Orders by Status" />
      <PropertyValue Property="ChartType" EnumMember="UI.ChartType/Donut" />
      <PropertyValue Property="Dimensions">
         <Collection>
            <PropertyPath>SalesOrderOverallStatus</PropertyPath>
         </Collection>
      </PropertyValue>
      <PropertyValue Property="DimensionAttributes">
         <Collection>
            <Record Type="UI.ChartDimensionAttributeType">
               <PropertyValue Property="Dimension" PropertyPath="SalesOrderOverallStatus" />
               <PropertyValue Property="Role" EnumMember="UI.ChartDimensionRoleType/Category" />
            </Record>
         </Collection>
      </PropertyValue>
      <PropertyValue Property="Measures">
         <Collection>
            <PropertyPath>NumberOfSalesOrders</PropertyPath>
         </Collection>
      </PropertyValue>
      <PropertyValue Property="MeasureAttributes">
         <Collection>
            <Record Type="UI.ChartMeasureAttributeType">
               <PropertyValue Property="Measure" PropertyPath="NumberOfSalesOrders" />
               <PropertyValue Property="Role" EnumMember="UI.ChartMeasureRoleType/Axis1" />
               <PropertyValue Property="DataPoint" AnnotationPath="@UI.DataPoint#NumberOfSalesOrders" />
            </Record>
         </Collection>
      </PropertyValue>
   </Record>
</Annotation>

Chart Type

You can select chart data points and segments in a chart. These selections influence the other chart filters depending on the configuration of the value list annotation.

The Chart Type…	Displays…
Bar	Top or bottom three records
Line	First or last six data points
Donut	Top or bottom two records

You can enable the visual filter (donut chart type) to display an overlay message if there are measures with negative values. Set the Analytics.AccumulativeMeasure annotation to false as shown in the example. By default, the value of the Analytics.AccumulativeMeasure annotation is true.

<Annotations Target="SEPMRA_ALP_SO_ANA_SRV.Z_SEPMRA_C_ALP_QUARTERVHType/DifferenceAmount">
    <Annotation Term="Analytics.Measure" Bool="true" />
    <Annotation Term="Analytics.AccumulativeMeasure" Bool="false" />
</Annotations>

Chart Title

ALP displays chart titles in the following order: <Measure Name> by <Dimension Name> in <Scale factor> <UoM>

<Measure Name> indicates the measure associated with the chart. Use sap:label()
<Dimension Name> indicates the dimension associated with the chart. Use sap:label()
<Scale Factor> indicates the scale as specified using the ScaleFactor property of the DataPoint annotation associated with the measure displayed in the chart.

Note

The scale factor in the chart and chart title are of the same scale.

Annotation: SelectionFields

Define the SelectionFields annotation for sorting the order of the fields displayed in the visual filters. If there are any mandatory filter fields that are not specified in the SelectionFields, then these fields appear first, followed by the other entries in the SelectionFields.

<Annotation Term="UI.SelectionFields">
  <Collection>
    <PropertyPath>DeliveryCalendarYear</PropertyPath>
    <PropertyPath>SoldToParty</PropertyPath>
    <PropertyPath>Product</PropertyPath>
    <PropertyPath>MainProductCategory</PropertyPath>
    <PropertyPath>DeliveryCalendarQuarter</PropertyPath>
  </Collection>
</Annotation>

Annotation: SelectionVariant

<Annotation Term="UI.SelectionVariant" Qualifier="SVForStatus">
   <Record>
      <PropertyValue Property="Parameters">
         <Collection>
            <Record Type="UI.Parameter">
               <PropertyValue Property="PropertyName" PropertyPath="CompanyCurrency" />
               <PropertyValue Property="PropertyValue" String="EUR" />
            </Record>
         </Collection>
      </PropertyValue>
      <PropertyValue Property="SelectOptions">
         <Collection>
            <Record Type="UI.SelectOptionType">
               <PropertyValue Property="PropertyName" PropertyPath="SalesOrderOverallStatus" />
               <PropertyValue Property="Ranges">
                  <Collection>
                     <Record Type="UI.SelectionRangeType">
                        <PropertyValue EnumMember="UI.SelectionRangeSignType/E" Property="Sign" />
                        <PropertyValue EnumMember="UI.SelectionRangeOptionType/EQ" Property="Option" />
                        <PropertyValue Property="Low" String="D" />
                     </Record>
                  </Collection>
               </PropertyValue>
            </Record>
            <Record Type="UI.SelectOptionType">
               <PropertyValue Property="PropertyName" PropertyPath="Product" />
               <PropertyValue Property="Ranges">
                  <Collection>
                     <Record Type="UI.SelectionRangeType">
                        <PropertyValue EnumMember="UI.SelectionRangeSignType/E" Property="Sign" />
                        <PropertyValue EnumMember="UI.SelectionRangeOptionType/EQ" Property="Option" />
                        <PropertyValue Property="Low" String="HT-1502" />
                     </Record>
                  </Collection>
               </PropertyValue>
            </Record>
         </Collection>
      </PropertyValue>
   </Record>
</Annotation>

Note

You can also define visual filters for parameters.

Text Arrangement

You can now change the formatting of the text that appears on the visual filter chart axis labels, legends, chart tooltips, and within the selected link (if a chart context is selected). The default view of the visual filter bar is based on the filter fields defined in the TextArrangement annotation and its type in the main entity set to change the text behavior like this:

Text Arrangement Type	Description
TextFirst	Use the visual filter to combine measures or item counts with filter values. The ChartDefault type that has the sap:text first, followed by the ID in brackets, for example, "Notebook (001)"
TextLast	ID followed by the sap:text in brackets, for example, "001 (Notebook)".
TextOnly	Shows only the sap:text, for example, "Notebook"
TextSeparate	Shows only the ID, for example, "002"

Sample Code

Text Arrangement Annotation

<Annotations Target="ProductType"> //Main EntitySet
  <Annotation Term="com.sap.vocabularies.UI.v1.TextArrangement" EnumMember="com.sap.vocabularies.UI.v1.TextArrangementType/TextFirst"/> 
</Annotations>

Display of Empty Values

The empty dimension value is displayed as Not Assigned in the visual filter chart. Note that this impacts the display only of visual filters but not of the value help, drop down, or compact filters. For the value help, drop down, or compact filter, it is displayed as <empty>.

Lazy Loading of Visual Filters

You enable lazy loading of visual filters by configuring the lazyLoadVisualFilter setting in the descriptor file. It is disabled by default.

If you enable lazy loading, then the batch call for loading of visual filters is deferred until the user switches to the visual filter bar.

Sample Code

Descriptor setting

"settings": {
              "qualifier": "MainContent",
              "defaultContentView": "charttable",
              "smartVariantManagement": true,
              "showGoButtonOnFilterBar": true,
              "multiSelect": true,
              "lazyLoadVisualFilter":true,

              "tableType": "AnalyticalTable",
              ....
}

Fixed Values on Visual Filters

To display default records on the visual filter chart, configure the SelectionVariant annotation with filter values (SelectOptions property) and link it with the ValueList annotation.

The in/out parameter values take precedence over the SelectionVariant value set, if the property is an in/out parameter and has a select option value without a chart dimension.

Scenario	Description
Scenario 1: Annotation configuration Chart dimension = “Status”, Select Option in SV = [(“Status”, Values = “In Progress”, “New”), (“Project”, Values=”List Report”)]	"Project" is not a chart dimension, it is an in/out parameter for the status The chart displays records relating to `In Progress` and `New` status values for the project `List Report`.
Scenario 2: Overriding annotation configuration from filter bar Change the project value from `List Report` to `Analytical List Page` on the filter bar	Specifying `Analytical List Page` as a value for the project in the filter bar, re-renders charts to display records for In Progress and New status values of the Analytical List Page project. Note The in/out parameter mapping values set for the other properties in the `SelectionVariant` annotation that are not part of the project field is considered as it is.

Scenario

Description

Scenario 1: Annotation configuration

Chart dimension = “Status”, Select Option in SV = [(“Status”, Values = “In Progress”, “New”), (“Project”, Values=”List Report”)]

"Project" is not a chart dimension, it is an in/out parameter for the status
The chart displays records relating to In Progress and New status values for the project List Report.

Scenario 2: Overriding annotation configuration from filter bar

Change the project value from List Report to Analytical List Page on the filter bar

Specifying Analytical List Page as a value for the project in the filter bar, re-renders charts to display records for In Progress and New status values of the Analytical List Page project.

Note

The in/out parameter mapping values set for the other properties in the SelectionVariant annotation that are not part of the project field is considered as it is.

To render the visual filter with a parametrized entity set as the collection path, you need to provide parameters in the SelectionVariant annotation. Any values added in the smart filter bar take priority over the SelectionVariant annotation values.

Scenario	Description
Scenario 1: Annotation configuration Parameter in SelectionVariant = [(“P_DisplayCurrency”, Value=”USD”)]	The chart renders records with the currency unit USD.
Scenario 2: Overriding annotation configurations on the filter bar Change USD to EUR on the filter bar	If you specify EUR as a value for `P_DisplayCurrency` in the filter bar, the chart re-renders with records that have the currency unit EUR

Scenario

Description

Scenario 1: Annotation configuration

Parameter in SelectionVariant = [(“P_DisplayCurrency”, Value=”USD”)]

The chart renders records with the currency unit USD.

Scenario 2: Overriding annotation configurations on the filter bar

Change USD to EUR on the filter bar

If you specify EUR as a value for P_DisplayCurrency in the filter bar, the chart re-renders with records that have the currency unit EUR

Date Selection

Visual filters now support date-based, single selection fields in the Universal Time Coordinated (UTC) format. The date selection field appears on the visual filter if the annotations in the metadata file contain:

Edm.DateTime and sap:display-format="Date"
Edm.String and sap:semantics="yearmonthday"
Edm.String and sap:semantics="yearmonth"
Edm.String and sap:semantics="year"

Note

Displaying the value in the visual filter and its tooltip is impacted. Value help or the dropdown for selecting the values remains the same if sap:semantics="yearmonth" is set.

Note

You can see the date selection button on the visual filter for fields annotated with sap:filter-restriction=”single-value". For fields annotated with sap:filter-restriction=”multiple", you see the value help selection button.

Sample Code

Sample Metadata

<Property Name="StartDate" Type="Edm.DateTime" sap:display-format="Date" 
sap:aggregation-role="dimension" sap:label="Date" sap:filter-restriction="single-value"/>

<Property Name="StartDate" Type="Edm.String" sap:semantics="yearmonthday" 
sap:aggregation-role="dimension" sap:label="Date" sap:filter-restriction="single-value"/>

Unit of Measure with Multiple Units of Measure

Visual filter charts do not show up if the back end returns data with multiple units of measure (UoM). To achieve a single UoM, set the required UoM in the filter bar or change all the UoMs into one UoM in the back end.

For currency-based visual filter values, the currency value could come from another filter field in the main entity set (mapped to the value help currency field based entity set through the standard IN mapping). If this kind of mapping exists with an empty filter field in the main entity set, ALP uses the value set maintained in the DisplayCurrency field in the incoming navigation context for filtering the value help entity set to render the visual filter chart.

If there's a parameter in the main entity set with the exact technical name P_DisplayCurrency, the value is derived from the incoming DisplayCurrency field of the incoming navigation context.

Note

User preference for display currency type is stored in the SAP Fiori launchpad user settings. Applications pass this value to filters using the DisplayCurrency field.

Number Formatting

NumberOfFractionalDigits information can be provided in com.sap.vocabularies.UI.v1.DataPoint term, using the ValueFormat property. The NumberOfFractionalDigits property is used to determine the number of fraction digits. These are the rules:

Decimals are not shown by default.
You can specify 1 or 2 decimal places using theNumberOfFractionalDigits property in Annotations. If a value of more than 2 is provided, it is also included.

In the following example, the price property number of fractional digits provided in the OData metadata, 3 is overridden by the value 1 as provided in the com.sap.vocabularies.UI.v1.DataPoint ValueFormat property

Sample Code

<Annotation Term="com.sap.vocabularies.UI.v1.DataPoint" Qualifier="Price">
    <Record Type="com.sap.vocabularies.UI.v1.DataPointType">
        <PropertyValue Property="Value" Path="Price"/>
        <PropertyValue Property="ValueFormat">
            <Record Type="com.sap.vocabularies.UI.v1.NumberFormat">
                <PropertyValue Property="NumberOfFractionalDigits" int="1"/>
            </Record>
        </PropertyValue>
    </Record>
</Annotation>

Semantic Coloring for Visual Filter Measure Values

Semantic coloring is based on the defined:

Criticality in DataPoint annotations. The specified value, or the value returned from a path, determines the color
CriticalityCalculation in DataPoint annotations, along with the improvement direction and various threshold values. This applies only when the criticality is not defined.

Note

No color is applied to the chart measure when

A neutral value is returned
Not enough threshold values are defined or when the improvement direction is missing

Semantic Coloring for Visual Filter Dimension Values

Semantic coloring is based on the defined criticality in the ValueCriticality annotations for dimensions. The value returned from the path determines the color.

Note

No color is applied to the chart dimension when a neutral value is returned.
Chart measure semantic coloring takes precendence over dimension semantic coloring.

Grouping Visual Filter Calls (Optional)

Add a groupId for a set of visual filters to consolidate all group calls into one batch call. This helps you group fast-loading visual filters in one batch and group all the other slow loading visual filters into a separate batch call. This improves rendering of the fast-loading visual filters over the slow-loading visual filters.

Define the onBeforeRebindVisualFilterExtension extension controller method in the controller file. Ensure that the groupId is one of the keys in the oContext object which is passed to the extension as a parameter. Provide a valid string value as shown here:

Sample Code

onBeforeRebindVisualFilterExtension: function(sEntityType, sDimension, sMeasure, oContext){
    'use strict';
    var Log = sap.ui.require("sap/base/Log");
    if (sDimension === "Product") {
        oContext.groupId = "Group1";
    }
    if (sDimension === "DeliveryCalendarMonth" || sDimension === "DeliveryCalendarQuarter") {
        oContext.groupId = "Group2";
    }
    Log.info("onBeforeRebindVisualFilterExtension called!");
}

Note

The visual filter calls without a groupId are all combined in one batch.
Visual filter calls assigned to a groupId reach the back end in one batch.

Guidelines

Show the filter dimension with one measure in the visual filter not with multiple measures.

Filter dimensions in the compact filters (filter bar) have exactly one representation in the visual filter bar.

Do not show the same filter dimension with two or more different measures at the same time in the visual filter bar. The example shows the filter Dimension Year with two different measures Revenue and Quantity. Showing the filter dimensionYear twice is not in sync with the compact filter, where it is shown only once. Furthermore, matching between the two filter types won't work.

If the use case requires you to show a dimension with different measures, consider using an overview page instead.

Do	Don't

For each dimension, display exactly one representation in the visual filter bar.	Do not use the same filter dimension with different measures.

Related information

Configuring the Filter Area

Visual Filter Setup

Visual Filter Setup

Hover over each action for a description. Click the action for more information.

ValueList Annotation

PresentationVariantQualifier

Chart Annotation

Annotation: SelectionFields

Annotation: SelectionVariant

Text Arrangement

Display of Empty Values

Lazy Loading of Visual Filters

Fixed Values on Visual Filters

Date Selection

Unit of Measure with Multiple Units of Measure

Number Formatting

Semantic Coloring for Visual Filter Measure Values

Semantic Coloring for Visual Filter Dimension Values

Grouping Visual Filter Calls (Optional)

Guidelines

In this section:

Related information