Intro

information

This article is intended as an aid to designers and developers who want to explore the detail configuration options available for the smart filter bar.

The smart filter bar uses annotations to create a filter bar. It’s a wrapper that analyzes a given OData service and renders a filter bar based on the content defined by the service. For example, the OData service determines whether a field is visible on the filter bar, and whether it supports type-ahead and value help. To configure more settings or overwrite the settings from the OData service, the developer can set additional annotations in an external document (metadata.xml).

The developer can use annotation properties in the classes [internal_only]ControlConfiguration[/internal_only][external_only]ControlConfiguration[/external_only] and [internal_only]GroupConfiguration[/internal_only][external_only]GroupConfiguration[/external_only] to adapt the filter bar for the purposes of the app.

These annotations let you:

Determine the type of control (for example, whether a field is shown as a multi-input field or as a date picker)
Enable the autocomplete suggestions feature
Enable the value help dialog
Overwrite settings from the OData service
Set custom filter groups
Add custom fields
Access all settings for the underlying filter bar

You can also use all the configuration options described here in the smart filter bar for the list report SAP Fiori element.

warning

Most of the attributes/properties are not dynamic and cannot be changed once the control has been initialized.

Usage

Use the smart filter bar if:

An OData service is available.
You want to develop quickly and efficiently.

Do not use the smart filter bar if:

You need to make extensive changes to the filter bar.

Components

You can use the [internal_only]annotation properties[/internal_only][external_only]annotation properties[/external_only] listed below to influence how filters are rendered in the expanded filter bar and in the filter dialog.

Expanded Filter Bar

Properties of the expanded filter bar

Properties of the expanded filter bar

1 enableBasicSearch
Defines whether the filter bar includes a basic search. By default, the basic search is not included.

2 FilterRestrictions/NonFilterableProperties
Defines whether a property is available as a filter criterion.

3 FilterRestrictions/RequiredProperties
Defines the filter field as a mandatory filter. Mandatory filters are marked by an asterisk (*).

4 ValueList
Contains annotations that provide information for rendering a value help list that has been set for a property.

5 FilterExpressionType/MultiValue
Defines whether multiple values can be used in a single filter.

6 FilterExpressionType/SingleValue
Restricts the filter to allow only one value entry.

7 LineItem/Label
A short, human-readable text for the filter name.

8 DynamicDateRange
The dynamic date range supports different operators, such as “Today -X / +Y days”. X and Y also support negative values (thus ranges in the past of future can be selected).

8 insertDefaultFilterValue
Inserts a default filter value into the aggregation defaultFilterValues.

9 liveMode
Defines whether the expanded filter bar is shown in live mode (no Go button) or in manual mode. By default, the filter bar is shown in manual mode.

Filter Dialog

Properties of the filter dialog

Properties of the filter dialog

1 FilterRestrictions/RequiredProperties
Defines the filter field as a mandatory filter. Mandatory filters are marked by an asterisk (*).

2 FieldControlType/Hidden
Defines whether the filter is initially visible on the expanded filter bar.

3 SelectionFields Defines whether a filter belongs to the basic group. All filters in the basic group are initially visible on the expanded filter bar.

4 FieldGroup
Defines whether a filter field is initially shown on the filter dialog, and which group it belongs to.

5 FilterRestrictions/NonFilterableProperties
Defines whether a property is available as a filter criterion.

6 LineItem/Label
A short, human-readable text for the filter name.

Fiscal Annotations

As an example, the smart filter bar supports fiscal annotations, like i.e. for fiscal period / data / time information. Such annotations guarantee the correct rendering of such values.

Smart filter bar with filters based on fiscal annotations

Smart filter bar with filters based on fiscal annotations

Recently Used Values

The smart filter bar provides a history of the most recent values entered in smart filter fields.

When the user focuses on a field, the app can display a small number of recently used values. They are shown below the recommended items, which can appear at the same time.
When the dropdown list is opened, all values are shown. When the user starts to type, the recently used values are filtered accordingly.

IN / OUT Parameter

In the smart filter bar, a dropdown or suggestion list can only contain a sub-set of items in case a dependent filter is set (IN parameter). It is also possible that selecting a value in a dropdown or suggestion list fills the current plus additional filter fields (OUT parameter).

Data Types

The smart filter bar analyzes and interprets the metadata provided by the OData service. This allows you to create complex UI entities, and to automatically add fields offered by the OData service to the filter bar as editable input fields. (Note that only fields marked with sap:filterable are added automatically.)

The tables below tell you which input controls are used for the key data types. [internal_only]For a complete list of data types, see the OData metadata wiki.[/internal_only]

General Data Types

<div> <div>DataType</div> <div>ODataMetadata</div> <div>Additional Configuration</div> <div>Edit type</div> <div>Display type</div> <div>Notes</div> </div> <div> <div>*</div> <div>*</div> <div></div> <div><a href="https%3A%2F%2Fwww.sap.com%2Finternal%2Ffiori-design-web%2Fv1-80%2Fsmart-template-list-report%2F">Input</a></div> <div>Text</div> <div></div> </div> <div> <div>DateTime</div> <div>–</div> <div>sap:display-format=”Date”</div> <div><a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fv1-80%2Fui-elements%2Fvalue-help-dialog%2F">DatePicker</a></div> <div>Text</div> <div></div> </div> <div> <div>Decimal</div> <div>–</div> <div>Precision=”3″ Scale=”0″</div> <div><a href="https%3A%2F%2Fsapui5.hana.ondemand.com%2F">Input</a></div> <div>Text</div> <div></div> </div> <div> <div>All</div> <div>–</div> <div></div> <div><a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fv1-80%2Fui-elements%2Finput-field%2F">Input</a> (with <a href="https%3A%2F%2Fsapui5nightly.int.sap.eu2.hana.ondemand.com%2F">VHD</a>)</div> <div>Text</div> <div>If a matching ValueList annotation is found, the ValueHelp for the Input is enabled.<br>A ValueHelp Dialog is created automatically, based on the data in the ValueList annotation.</div> </div> <div> <div>All</div> <div>–</div> <div>sap:semantics=”fixed-values” on the ValueList entity</div> <div><a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fv1-80%2Fui-elements%2Fmultiinput%2F">ComboBox</a></div> <div>Text</div> <div>If a matching ValueList annotation is found, and the ValueList entity has the semantics=”fixed-values”, a dropdown list is shown.</div> </div>

Filter Bar-Specific Data Types

<div> <div>Input Type</div> <div>sap:filter-restriction</div> <div>display-format</div> <div>hasValueHelpDialog</div> <div>controlType</div> <div>Resulting Control Type</div> </div> <div> <div>*</div> <div>*</div> <div></div> <div>controlType/filterType is specified</div> <div></div> <div>As specified in additional configuration</div> </div> <div> <div>DateTime</div> <div>“interval”</div> <div>“Date”</div> <div>NA</div> <div></div> <div><a href="https%3A%2F%2Fwww.sap.com%2Finternal%2Ffiori-design-web%2Fv1-80%2Fui-components%2Fdate-range-selection%2F">Date Range Selection</a></div> </div> <div> <div>DateTime</div> <div>“anything other than interval” or empty</div> <div>“Date”</div> <div>NA</div> <div></div> <div><a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fv1-80%2Fui-elements%2Fvalue-help-dialog%2F">Date Picker</a></div> </div> <div> <div>String</div> <div>“single-value”</div> <div></div> <div>“true” / none</div> <div></div> <div>Input Field With <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fv1-80%2Fui-elements%2Fdate-picker%2F">Value Help Dialog</a><br>(with typeAhead according to hasTypeAhead flag)</div> </div> <div> <div>String</div> <div>“single-value”</div> <div></div> <div>“false”</div> <div>not specified/input</div> <div><a href="https%3A%2F%2Fsapui5nightly.int.sap.eu2.hana.ondemand.com%2Fsapui5-sdk-internal%2F">Input Field</a><br>(with typeAhead according to hasTypeAhead flag)</div> </div> <div> <div>String</div> <div>“single-value”</div> <div></div> <div>“false”</div> <div>dropDownList; hasTypeAhead is not considered here</div> <div><a href="https%3A%2F%2Fsapui5nightly.int.sap.eu2.hana.ondemand.com%2F">ComboBox</a></div> </div> <div> <div>*</div> <div>“single-value”</div> <div></div> <div></div> <div></div> <div><a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fv1-80%2Fui-elements%2Finput-field%2F">Input Field</a></div> </div> <div> <div>String</div> <div>empty or no filter-restriction</div> <div></div> <div>“true” / none</div> <div></div> <div><a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fv1-80%2Fui-elements%2Fvalue-help-dialog%2F">Multi Input Field</a> with <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fv1-80%2Fui-elements%2Fmultiinput%2F">Value Help Dialog</a></div> </div> <div> <div>String</div> <div>“multi-value”</div> <div></div> <div>“true” / none</div> <div></div> <div>If no VL Annotation is found – only show the range selection part</div> </div> <div> <div>String</div> <div>“multi-value” / empty</div> <div></div> <div>“false”</div> <div></div> <div>If no VL Annotation is found – hide the ValueHelpDialog icon</div> </div> <div> <div>String</div> <div>“multi-value” / empty</div> <div></div> <div>“false”</div> <div>dropDownList</div> <div><a href="https%3A%2F%2Fsapui5nightly.int.sap.eu2.hana.ondemand.com%2F">MultiComboBox</a></div> </div> <div> <div>*</div> <div>“multi-value”</div> <div></div> <div></div> <div></div> <div><a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fv1-80%2Fui-elements%2Finput-field%2F">Input Field</a></div> </div> <div> <div>*</div> <div>“interval”</div> <div></div> <div>NA</div> <div></div> <div>A single <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fv1-80%2Fui-elements%2Finput-field%2F">Input Field</a> that allows the “-” shortcut notation for intervals</div> </div>

Guidelines

Reduced set of table columns for the tabular suggestion

You have the option to define different columns in the table of the Value Help Dialog and the suggestion list of the Smart Filter Bar.

In the [internal_only]ValueList annotation[/internal_only][external_only]value list annotation[/external_only], each parameter can be statically annotated as important using the <code>Importance</code> annotation with EnumMember set to High:

<Annotation Term="com.sap.vocabularies.UI.v1.Importance"                     EnumMember="com.sap.vocabularies.UI.v1.ImportanceType/High" />

In the suggestion list only the important parameters are displayed as columns, while in the table of the Value Help Dialog all of the parameters are displayed.

The Importance annotation is optional – if omitted all of the parameters are displayed in both table of the Value Help Dialog and the suggestion list of the Smart Filter Bar.

Formatting option for negative numbers

The OData type “NumericText” together with display-format=”NonNegative” interprets and displays all values containing only “0” (e.g. “0”, “000”) as empty.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Filter Bar (guidelines)

Implementation

Smart Filter Bar (SAPUI5 samples)
Smart Filter Bar (SAPUI5 API reference)
Smart Filter Bar Annotations (SAPUI5 API reference)
Filter Bar (SAPUI5 samples)
Filter Bar (SAPUI5 API reference)
[internal_only]OData Annotations for Smart Filter Bar[/internal_only]
UI Development Toolkit (SAPUI5 samples)

Visual Design

[internal_only]Filter Bar (visual design specification)[/internal_only]
[external_only]No links.[/external_only]