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

Developers can use annotation properties in the classes [internal_only]ControlConfiguration[/internal_only][external_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 Elements).

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 annotation properties listed below to influence how filters are rendered in the expanded filter bar and in the filter dialog.

Expanded Filter Bar

Smart filter bar - Properties for the expanded filter bar

Smart filter bar - Properties for the expanded filter bar [internal_only]1 enableBasicSearch[/internal_only] [external_only]1 enableBasicSearch[/external_only]

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

[internal_only]2 FilterRestrictions/NonFilterableProperties[/internal_only] [external_only]2 FilterRestrictions/NonFilterableProperties[/external_only]

Defines whether a property is available as a filter criterion.

[internal_only]3 FilterRestrictions/RequiredProperties[/internal_only] [external_only]3 FilterRestrictions/RequiredProperties[/external_only]

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

[internal_only]4 ValueList[/internal_only] [external_only]4 ValueList[/external_only]

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

[internal_only]5 FilterExpressionType/MultiValue[/internal_only] [external_only]5 FilterExpressionType/MultiValue[/external_only]

Defines whether multiple values can be used in a single filter.

[internal_only]6 [/internal_only]FilterExpressionType/SingleValue [external_only]6 FilterExpressionType/SingleValue[/external_only]

Restricts the filter to allow only one value entry.

[internal_only]7 LineItem/Label[/internal_only] [external_only]7 LineItem/Label[/external_only]

A short, human-readable text for the filter name.

[internal_only]8 FilterExpressionType/SingleInterval[/internal_only] [external_only]8 FilterExpressionType/SingleInterval[/external_only]

Restricts the filter to a specified interval, such as a date interval.

[internal_only]8 insertDefaultFilterValue[/internal_only] [external_only]8 insertDefaultFilterValue[/external_only]

Inserts a default filter value into the aggregation defaultFilterValues.

[internal_only]9[/internal_only] liveMode [external_only]9 liveMode[/external_only]

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

[internal_only]1 FilterRestrictions/RequiredProperties[/internal_only]

[external_only]1 FilterRestrictions/RequiredProperties[/external_only]

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

[internal_only]2 FieldControlType/Hidden[/internal_only]

[external_only]2 FieldControlType/Hidden[/external_only]

Defines whether the filter is initially visible on the expanded filter bar.

[internal_only]3 SelectionFields[/internal_only]

[external_only]3 SelectionFields[/external_only]

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

[internal_only]4 FieldGroup[/internal_only]

[external_only]4 FieldGroup[/external_only]

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

[internal_only]5 FilterRestrictions/NonFilterableProperties[/internal_only]

[external_only]5 FilterRestrictions/NonFilterableProperties[/external_only]

Defines whether a property is available as a filter criterion.

[internal_only]6 LineItem/Label[/internal_only]

[external_only]6 LineItem/Label[/external_only]

A short, human-readable text for the filter name.

SmartFilterBar Properties on the Filter Dialog

SmartFilterBar Properties on the Filter Dialog

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%2Fdesign-system%2Ffiori-design-web%2Fv1-32%2Fui-elements%2Finput-field%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-32%2Fui-elements%2Fdate-picker%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%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fv1-32%2Fui-elements%2Finput-field%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-32%2Fui-elements%2Finput-field%2F">Input</a> (with <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fv1-32%2Fui-elements%2Fvalue-help-dialog%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%2Finternal%2Ffiori-design-web%2Fv1-32%2Fui-components%2Fcombo-box%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-32%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-32%2Fui-elements%2Fdate-picker%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-32%2Fui-elements%2Fvalue-help-dialog%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%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fv1-32%2Fui-elements%2Finput-field%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%2Fwww.sap.com%2Finternal%2Ffiori-design-web%2Fv1-32%2Fui-components%2Fcombo-box%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-32%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-32%2Fui-elements%2Fmultiinput%2F">Multi Input Field</a> with <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Ffiori-design-web%2Fv1-32%2Fui-elements%2Fvalue-help-dialog%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%2Fwww.sap.com%2Finternal%2Ffiori-design-web%2Fv1-32%2Fui-components%2Fmulti-combobox%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-32%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-32%2Fui-elements%2Finput-field%2F">Input Field</a> that allows the “-” shortcut notation for intervals</div> </div>

Properties

FilterBar

Filter Bar Properties

persistencyKey[external_only]persistencyKey[/external_only]
Data type: string
Key used to access personalization data.

[internal_only]advancedMode[/internal_only][external_only]advancedMode[/external_only]
Data type: boolean
The advanced mode overwrites the standard behavior and is used in the value help scenario.
Default value is false.

expandAdvancedArea[external_only]expandAdvancedArea[/external_only]
Data type: boolean
Defines whether the advanced area is expanded when the filter bar is used within the value help dialog.
Default value is false.

searchEnabled[external_only]searchEnabled[/external_only]
Data type: boolean
Enables/disables the Search button in advanced mode.
Default value is true.

filterBarExpanded[external_only]filterBarExpanded[/external_only]
Data type: boolean
Shows/hides the expanded filter bar.
Default value is true.

considerGroupTitle[external_only]considerGroupTitle[/external_only]
Data type: boolean
If this property is set, the label for filters is prefixed with the group title.
Default value is false.

showClearButton[external_only]showClearButton[/external_only]
Data type: boolean
Handles visibility of the Clear button on the Filters dialog.
Default value is false.

showRestoreButton[external_only]showRestoreButton[/external_only]
Data type: boolean
Handles visibility of the Restore button on the Filters dialog.
Default value is true.

showGoOnFB[external_only]showGoOnFB[/external_only]
Data type: boolean
Handles visibility of the Go button on the filter bar.
Default value is true.

[internal_only]showRestoreOnFB[/internal_only][external_only]showRestoreOnFB[/external_only]Data type: boolean
Handles visibility of the Restore button on the filter bar.
Default value is false.

[internal_only]showClearOnFB[/internal_only][external_only]showClearOnFB[/external_only]Data type: boolean
Handles visibility of the Clear button on the filter bar.
Default value is false.

showGoButton[external_only]showGoButton[/external_only]Data type: boolean
Handles visibility of the Go button on the filter bar.

[internal_only]deltaVariantMode[/internal_only][external_only]deltaVariantMode[/external_only]Data type: boolean
Stores the delta as compared to the standard variant.
Default value is true.

[internal_only]filterContainerWidth[/internal_only][external_only]filterContainerWidth[/external_only]
Data type: string
Sets the width of the filter container.
Default value is 12rem.

[internal_only]useToolbar[/internal_only][external_only]useToolbar[/external_only]Data type: boolean
Determines what design should be used. Default is the design with the toolbar. In mobile scenarios this property is ignored – the design with the toolbar is always used.
Default value is true.

[internal_only]header[/internal_only][external_only]header[/external_only]Data type: string
Specifies the header text that is shown in the toolbar on the first position. This property is ignored, when useToolbar is set to false.

[internal_only]showFilterConfiguration[/internal_only][external_only]showFilterConfiguration[/external_only]Data type: boolean
Handles visibility of the Filters button on the filter bar.
Default value is true.

Smart Filter Bar

Smart Filter Bar Properties

[internal_only]entitySet[/internal_only][external_only]entitySet[/external_only]
Data type: string
The OData entity set whose metadata is used to create the SmartFilterBar. Note: Changing this value after the SmartFilterBar is initialized (initialize event was fired) has no effect.

[internal_only]basicSearchFieldName[/internal_only][external_only]basicSearchFieldName[/external_only]
Data type: string
Name of the field that has to be the focus of the basic search. This is only relevant for SmartFilterBar in combination with ValueHelpDialog.

[internal_only]enableBasicSearch[/internal_only][external_only]enableBasicSearch[/external_only]
Data type: boolean
Enables the basic search field in the SmartFilterBar control. This must only be enabled for entities that support such search behavior.
Default value is false.

[internal_only]liveMode[/internal_only][external_only]liveMode[/external_only]
Data type: boolean
Defines the live mode. The live mode only operates on non-phone scenarios.
Default value is false.

[internal_only]showMessages[/internal_only][external_only]showMessages[/external_only]
Data type: boolean
If set to false, any errors that occur during the search will not be displayed in a message box.
Default value is true.

[internal_only]considerAnalyticalParameters[/internal_only][external_only]considerAnalyticalParameters[/external_only]
Data type: boolean
Indicates if the analytical parameters (SelectionVariant) must be taken into consideration.
Default value is false.

Smart Filter Bar Annotations

FilterRestrictions/NonFilterableProperties[external_only]FilterRestrictions/NonFilterableProperties[/external_only] Defines whether a Property can be used for filtering data.

[internal_only]FieldGroup[/internal_only][external_only]FieldGroup[/external_only]
Defines a group for a filter field.

[internal_only]TextArrangement[/internal_only][external_only]TextArrangement[/external_only]
Describes the arrangement of a code value and its text.

[internal_only]FieldControlType/Hidden[/internal_only][external_only]FieldControlType/Hidden[/external_only]
Defines whether the filter is visible.

[internal_only]ValueList[/internal_only][external_only]ValueList[/external_only]
Contains annotations that provide information for rendering a ValueHelpList that has been set for a Property.

[internal_only]Label[/internal_only][external_only]Label[/external_only]
A short, human-readable text for the filter name.

[internal_only]LineItem/Label[/internal_only][external_only]LineItem/Label[/external_only]
A short, human-readable text suitable for the filter name.

[internal_only]FilterRestrictions/RequiredProperties[/internal_only][external_only]FilterRestrictions/RequiredProperties[/external_only]
Defines the filter field as mandatory filter.

[internal_only]FilterExpressionType/MultiValue[/internal_only][external_only]FilterExpressionType/MultiValue[/external_only]
Defines whether multiple values can be used in a single filter.

[internal_only]FilterExpressionType/SingleValue[/internal_only][external_only]FilterExpressionType/SingleValue[/external_only]
Restricts the filter to allow only one value entry.

[internal_only]FilterExpressionType/SingleInterval[/internal_only][external_only]FilterExpressionType/SingleInterval[/external_only]
Restricts the filter to a specified interval, such as a date interval.

[internal_only]SelectionFields[/internal_only][external_only]SelectionFields[/external_only]
Defines whether certain fields should be initially visible in the SmartFilterBar control.

Control Configuration

Control Configuration Properties

[internal_only]key[/internal_only][external_only]key[/external_only]
The key property corresponds to the field name from the OData service metadata document.
Default value is string

[internal_only]groupId[/internal_only][external_only]groupId[/external_only]
The groupId can be used to move a field from one group to another. The groupId corresponds to the EntityName from the OData metadata. It is also possible to move a field from the advanced area to the basic area by specifying the groupId _BASIC.
Default value is string

[internal_only]label[/internal_only][external_only]label[/external_only]
You can use this property to overwrite the label of a filter field in the SmartFilterBar.
Default value is string

[internal_only]visible[/internal_only][external_only]visible[/external_only]
Data type: boolean
You can use this flag to hide fields from the OData metadata.
Default value is true

[internal_only]hasValueHelpDialog[/internal_only][external_only]hasValueHelpDialog[/external_only]
Data type: boolean
Specifies whether a value help dialog is available or not.
Default value is true

[internal_only]controlType[/internal_only][external_only]controlType[/external_only]
Data type: sap.ui.comp.smartfilterbar.ControlType
The SmartFilterBar calculates which kind of control will be used for a filter field, based on multiple OData attributes and annotations. You can use this property to overwrite the OData metadata.
Default value is auto

[internal_only]filterType[/internal_only][external_only]filterType[/external_only]
Data type: sap.ui.comp.smartfilterbar.FilterType
The filter type specifies whether the filter field is for a single value, multiple values, or an interval. The filter type calculated by the SmartFilterBar is based on the OData metadata. You can use this property to configure the filter type manually.
Default value is auto

[internal_only]index[/internal_only][external_only]index[/external_only]
Data type: int
You can use the zero-based index to specify the initial order of fields (without any variants).
Default value is -1

Control Configuration Properties

[internal_only]hasTypeAhead[/internal_only][external_only]hasTypeAhead[/external_only]
Data type: boolean
You can use this property to enable the TypeAhead service. Note that TypeAhead does not work with all controls (for example, it is not supported for the DropDownListbox).
Default value is true

[internal_only]mandatory[/internal_only][external_only]mandatory[/external_only]
Data type: sap.ui.comp.smartfilterbar.MandatoryType
You can use this property to overwrite the mandatory state of a filter field. This property can only be set during initialization. Changes at runtime will be ignored.
Default value is auto

[internal_only]width[/internal_only][external_only]width[/external_only]
Default value is string
The width of the filter field in a CSS compatible format. The width can be set only once during initialization. Changes at runtime will not be reflected. The width is not applied to custom controls.

[internal_only]visibleInAdvancedArea[/internal_only][external_only]visibleInAdvancedArea[/external_only]
Data type: boolean
If set to true, this field will be added to the advanced area (aka. Dynamic Selection) by default.
Default value is false

[internal_only]preventInitialDataFetchInValueHelpDialog[/internal_only][external_only]preventInitialDataFetchInValueHelpDialog[/external_only]
Data type: boolean
If value help annotations are available for this filter field, you can prevent the the table in the value help dialog for this field from being filled with the initial data fetch.
Default value is true

[internal_only]displayBehaviour[/internal_only][external_only]displayBehaviour[/external_only]
Data type: sap.ui.comp.smartfilterbar.DisplayBehaviour
The displayBehaviour specifies how to display the content on certain controls. For example: DescriptionOnly for Combobox (DropDown text), Description and ID for MultiInput (token text)
Default value is auto

[internal_only]conditionType[/internal_only][external_only]conditionType[/external_only]
Data type: any
The condition Type class name to use for this filter item. Implementation should derive from sap.ui.comp.config.condition.Type.

Group Configuration

Group Configuration Properties

[internal_only]key[/internal_only][external_only]key[/external_only]
Data type: string
The key property shall correspond to the name EntityTypeName from the OData service $metadata document.

[internal_only]index[/internal_only][external_only]index[/external_only]
Data type: any
Zero-based integer index. The index can be used to specify the order of groups. If no index is specified, the order defined by the OData metadata will be used.
Default value is undefined

[internal_only]label[/internal_only][external_only]label[/external_only]
Data type: any
You can use this property to overwrite the label of a group in the advanced area of the SmartFilterBar.
Default value is undefined

[internal_only]Find more information about OData data types for smart controls here.[/internal_only]

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/ Smart Filter Bar (guidelines)

Implementation

Smart Filter Bar (SAPUI5 samples)
Smart Filter Bar (SAPUI5 API reference)
UI Development Toolkit (SAPUI5 samples)

Visual Design

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