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 filter area can be hidden 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 available for desktop use only.
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; on phones, right before the filters. The Filters dialog is then called Adapt Filters dialog.

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

Details

FilterItem and FilterGroupItem

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. You can define which filter is visible in the filter bar and whether a filter is shown in the current variant at all. You 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, you can select the Add to Filter Bar checkbox to make the filter visible in the filter bar.

Note This function is available for desktop use only.

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. You can assign filters other than the ones from the basic filter group by selecting the following for a specific group:

More Filters

Shows all filters of the relevant group that have not been assigned yet.
Change Filters

Displayed if all filters of the relevant group have already been assigned.

This takes you to the Select Filters dialog where you can define which filters are included in the current variant. This dialog displays all the 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`

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 and 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 you to create and store variants in the VENDOR layer of the layered repository.

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

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.

FAQ

Question

How can I use SAPUI5 flexibility services in the FilterBar control?

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 you select 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 you select Cancel or Restore in the Filters dialog of the filter bar.

Related Information

Smart Filter Bar

Smart Variant Management