Filter Bar

The sap.ui.comp.filterbar.FilterBar control is used to provide a user-friendly interface for queries.

Overview

The FilterBar control has been implemented as a toolbar with a collapsible filter area. Whereas the toolbar is always visible, the user can hide the filter area to reduce the space required.

Note This applies to desktop use only. On tablets, the filter area is always hidden and cannot be made visible by the user.

The toolbar includes the VariantManagement control and contains the following buttons:

Hide Filter Bar /Show Filter Bar
Hides/displays the filter area.

Note This function is only available for desktop use.
Filters
Lists the filters available and, if selected, displays the filter dialog.
Go
Executes the query.

A Search event is raised, and the embedding control must respond to it. The property showGoButton is set to True by default and determines whether the button is visible.

Note The FilterBar control can be used on its own. However, it is strongly recommended to use it in combination with the SmartFilterBar control.

FilterItems and FilterGroupItems

Filters are similar to query parameters. A filter is represented either by a FilterItem element or its specialization, the FilterGroupItem element. They are populated via the FilterItems or FilterGroupItems aggregations. The main difference is that the FilterGroupItem has the group attribute. The FilterItem is internally processed as a FilterGroupItem that belongs to the Basic group.

The embedding component of the FilterBar control determines if a filter is mandatory and visible, defines its label, and whether the filter is visible in the filter area.

Note The user interface control, upon which the filter is based, can have its own width. It is recommended to set the filter either to or 100%. In both cases, the control will then set the control width to 12rem to present a easier to read user interface.

Filter Dialog

The Filters dialog provides all the functions that are available with the FilterBar control. The user can define which filter is visible in the filter bar and whether a filter is shown in the current variant at all. The user can also clear and restore values by selecting Clear and Restore and trigger the query execution.

Note Some of the buttons are hidden and must be enabled first.

The information in this dialog is row-based. The first element is the VariantManagement control, followed by the filters. The filters are organized in groups, each starting with a group title. For each filter, the user can select the Add to Filter Bar checkbox to make the filter visible in the filter bar.

Note This function is only available for desktop use.

The filters of the Basic group are always included in the current variant. All other group filters are initially not assigned to the current variant. The user can assign a filter that is different from the basic filter group by selecting More Filters (all filters that have not yet been assigned and belong to this group) or Change Filters, if all filters of the current group have already been added to the current variant. This takes the user to the Select Filters for Variant dialog where the user can define which filters are included in the current variant. This dialog displays all filters of a group.

Note The Select Filters for Variant dialog is available on its own and can be used in other scenarios, for example, in the value help dialog.

Once filters have been included in the current variant, they can also be added to the filter bar. A filter can only be removed from the current variant if it is not visible in the filter bar.

Mandatory filters can only be removed from the filter bar if they have a value. As long as a mandatory filter does not have a value, it will be treated as added to the filter bar.

The buttons in the dialog offer the following functions:

Save
Represents the Save function for the VariantManagement control on the user interface.

It either saves the current variant or provides the Save dialog for variant management if a Save As function is required.
Clear
Clears all filters by raising the Clear event.

The showClearButton property is set to False by default and determines whether the button is visible.
Restore
Reverts all changes of the current variant by raising the Reset event and applies the current variant again.

The showRestoreButton property is set to True by default and determines whether the button is visible.
Go
Executes the query.

The function of the button is the same as for the one in the filter bar. However, here the button is always visible.
Close
Closes the dialog and transfers all settings and values to the filter bar.

Filter Bar in the Value Help Dialog

The filter bar is also used in the Value Help dialog scenarios. The filter bar property advancedMode must be set to true to enable this function.

The embedding component has to provide a search field using the FilterItems aggregation and an advanced search using the FilterGroupItems aggregation. For the search, the Search event is raised.

Integration of Smart Variant Management

A variant represents a set of filters. Variants are handled and represented on the user interface by the VariantManagement control that is included in the toolbar of the FilterBar control.

Variants are stored in a backend system and also retrieved from there.

For more information about the SmartVariantManagement control itself, refer to the corresponding documentation.

For the variants, the following two services are available:

UI2 service for personalization
UI5 service for flexibility

They can be accessed using the SmartVariantManagement control.

The consuming control that is using the SmartVariantManagement control has to provide the following dedicated methods:

applyVariant (oVariantContent)
var oVariantContent = fetchVariant ()

The fetchVariant has to return a JSON object. This is the information that is stored along with some administrative information, such as the name of the variant and the ID. Once the variant has been retrieved from the backend system and transferred to the consuming control, the applyVariant is executed. During execution, the consuming control must know the format of oVariantContent, since the control must also provide the method and react to it.

The SmartFilterBar control uses the SmartVariantManagement control. The FilterBar control uses the SmartVariantManagementUI2 control.

UI2 Personalization Service

The UI2 personalization is handled internally by the FilterBar control. The basic variant handling is implemented by the SmartVariantManagementUI2 control. It extends the VariantManagement control. The UI2 personalization only supports end user personalization.

The consuming control of the FilterBar has to provide two methods, one for fetching the data that must be stored as the content of the variant, and one for applying this data, if the variant is set. Both methods have to be registered using the corresponding methods of the FilterBar:

registerApplyData (fApplyData) – interface: fApplyData (oVariantContent)
registerFetchData (fFetchData) – interface: oVariantContent = fFetchData ()

A persistence key setPersistencyKey (sKey) must be provided as well. This key identifies the storage area and saves/retrieves the variants currently used.

To trigger the retrieval of the variants, the consuming control must register to the Initialise event of the FilterBar and call the method fireInitialise() in the FilterBar.

Note The retrieval of the initial variants is done asynchronously. If the retrieval has been completed, the SmartVariantManagementUI2 control will be populated with the variant information, and the event handler for the Initialise event will be called.

UI5 Flexibility Service

The UI5 flexibility is handled internally by the SmartFilterBar control. The basic variant handling is implemented by the SmartVariantManagement control. It extends the VariantManagement control. UI5 flexibility supports end user personalization and also allows to create and store SAP- and vendor-specific variants.

Use Case: How to Use UI5 Flexibility in FilterBar

Basically, the FilterBar control supports the UI2 personalization service. The following steps describe how to enable the FilterBar control to use the UI5 flexibility service provided the FilterBar is already used and the consuming control supports the UI2 service via the FilterBar. If this is not the case, refer to section "UI2 Personalization Service“ first.

Extend the FilterBar to create a new FilterBar control.

pcode:

sap.ui.comp.filterbar.FilterBar.extend(“my.ui5flex.FilterBar”) {..}

Overwrite the internal _initializeVariantManagement function of the FilterBar.

pcode:

my.ui5flex.FilterBar.prototype._initializeVariantManagement = function() {
      	if (this._oSmartVM && this.getPersistencyKey()) {
            var oPersInfo = new sap.ui.comp.smartvariants.PersonalizableInfo({
		     type: "filterBar",
		     keyName: "persistencyKey"		
             });
	     oPersInfo.addControl(this);

	     oSmartVM.addPersonalizableControl(oPersInfo);					        
             sap.ui.comp.filterbar.FilterBar.prototype._initializeVariantManagement.apply(this, arguments);

	 } else {
		this.fireInitialise();
 }
    };

Overwrite the internal _createVariantManagement function of the FilterBar.

pcode:

my.ui5flex.FilterBar.prototype._createVariantManagement = function() {
         this._oSmartVM = new sap.ui.comp.smartvariants.SmartVariantManagement({
                	showExecuteOnSelection: true,
                	showShare: true
           	   });
                return this._oSmartVM;
};

Further Communication between (Smart)FilterBar and Consuming Control

Before a variant is saved, the (Smart)FilterBar triggers the beforeVariantSave event. This allows the consuming control to prepare for the fetchData call, if required. Right after this event is raised, the (Smart)FilterBar calls the method provided by the registerFetchData method. If a user selects a variant from the (Smart)VariantManagement control and after the (Smart)FilterBar calls the method provided by the registerApplyData method, the afterVariantLoad event will be raised.

Note The afterVariantLoad event is also raised internally when the user selects Cancel or Reset in the Filters dialog of the filter bar.