The sap.ui.comp.filterbar.FilterBar control is used to provide a user-friendly interface for queries.
For more information about this control, see the API Reference in the Demo Kit and the sample in the Explored app in the Demo Kit.
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.
The toolbar includes the VariantManagement control and contains the following buttons:
Hides or displays the filter area.
Lists the filters available and, if selected, displays the filter dialog.
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.
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.
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.
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.
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:
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.
Clears all filters by raising the Clear event.
The showClearButton property is set to False by default and determines whether the button is visible.
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.
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.
Reverts all changes made by the user since the dialog was opened and closes the 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.
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:
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:
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:
|
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:
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.
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.
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:
#!js
sap.ui.comp.filterbar.FilterBar.extend(“my.ui5flex.FilterBar”) {..}#!js
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();
}
};
#!js
my.ui5flex.FilterBar.prototype._createVariantManagement = function() {
this._oSmartVM = new sap.ui.comp.smartvariants.SmartVariantManagement({
showExecuteOnSelection: true,
showShare: true
});
return this._oSmartVM;
};
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.