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. On tablets, the filter area is always collapsed but can be expanded by the user. On phones, the filter area is not displayed at all. You can access the filters through the Filters dialog.

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

Hide Filter Bar /Show Filter Bar
Hides or 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 consuming control must respond to it. The showGoButton property is set to True by default and determines whether the button is visible.

Note You can also deactivate the toolbar using the useToolbar=false property setting. In this case the filter bar buttons are rendered in the filter area right behind the filters. The Filters dialog is then called Adapt Filters dialog.

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

Details

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.

Filters 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 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 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.
Cancel
Reverts all changes made by the user since the dialog was opened and closes the dialog.

Integration with 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 with 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 variants, the following services are available:

Shell service for personalization
SAPUI5 flexibility services

They can be accessed using the SmartVariantManagement or SmartVariantManagementUI2 control.

For more information about the shell services, see the API Reference in the Demo Kit.

For more information about flexibility services, see SAPUI5 Flexibility Services.

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

The following table shows which controls are used by the filter bar controls to handle variants:

Table 1: Controls for Variant Management Integration
Control	Uses
`FilterBar`	`SmartVariantManagementUI2`
`SmartFilterBar`	`SmartVariantManagement`

Note You can also hide VariantManagement if no persistencyKey is provided. Also, you can separate the VariantManagement control from the FilterBar control by using the page variant of the SmartVariantManagement control.

Shell Service for Personalization

The shell service for personalization is handled internally by the FilterBar control. The basic variant handling is implemented by the SmartVariantManagementUI2 control. It extends the VariantManagement control. The shell service for 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 control:

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 fireInitialise() method in the FilterBar control.

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.

SAPUI5 Flexibility Services

Flexibility services are handled internally by the SmartFilterBar control. The basic variant handling is implemented by the SmartVariantManagement control. It extends the VariantManagement control. Flexibility services support end user personalization and also allow to create and store VENDOR-specific variants.

Note We recommend that you always use the SAPUI5 flexibility services rather than the shell service.

FAQ

Question

How can I use SAPUI5 flexibility services in FilterBar?

Answer

In general, the FilterBar control supports the shell service for personalization. The following steps describe how to enable the FilterBar control to use the flexibility services provided the FilterBar is already used, and the consuming control supports the shell service via the FilterBar control. If this is not the case, make sure the shell service is used as described above before you start.

After that, here is what you need to do:

Extend the FilterBar to create a new FilterBar control.

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

Overwrite the internal _initializeVariantManagement function of the FilterBar control.

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

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

Further Communication between FilterBar, SmartFilterBar, and Consuming Control

The following is also valid for the SmartFilterBar control: Before a variant is saved, the FilterBar control triggers the beforeVariantSave event. This allows the consuming control to prepare for the fetchData call, if required. Right after this event is raised, the FilterBar control calls the method provided by the registerFetchData method. If a user selects a variant from the VariantManagement control or the SmartVariantManagement respectively after the FilterBar has called the method provided by the registerApplyData method, the afterVariantLoad event is raised.

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

Related Information

Smart Filter Bar

Smart Variant Management