Class sap.m.FacetFilterModule: sap/m/FacetFilter

extends Control
implements IShrinkable

Provides filtering functionality with multiple parameters.

Overview

The FacetFilter control is used to provide filtering functionality with multiple parameters and supports the users in finding the information they need from potentially very large data sets.

Your app can have dependencies between facets where selection of filter items in one facet list limits the list of valid filters in another facet list.

The FacetFilter uses FacetFilterList and FacetFilterItem to model facets and their associated filters.

Note: FacetFilterList is a subclass of sap.m.List and supports growing enablement feature via the property growing. When you use this feature, be aware that it only works with one-way data binding. Having growing feature enabled when the items aggregation is bound to a model with two-way data binding, may lead to unexpected and/or inconsistent behavior across browsers, such as unexpected closing of the list.

Usage

Use the FacetFilter if your app displays a large list of items that can be grouped by multiple parameters, for example products by category and supplier. With the FacetFilter, you allow the users to dynamically filter the list so it only displays products from the categories and suppliers they want to see.

While the sap.m.FacetFilterList popup is opened (when the user selects a button corresponding to the list's name), any other activities leading to focus change will close it. For example, when the popup is opened and the app developer loads a sap.m.BusyDialog or any other dialog that obtains the focus, the popup will be closed.

Responsive behavior

The FacetFilter supports the following two types, which can be configured using the control's type property:

  • Simple type (default) - only available for desktop and tablet screen sizes. The active facets are displayed as individually selectable buttons on the toolbar.
  • Light type - automatically enabled on smart phone sized devices, but also available for desktop and tablets. The active facets and selected filter items are displayed in the summary bar. When the user selects the summary bar, a navigable dialog list of all facets is displayed. When the user selects a facet, the dialog scrolls to show the list of filters that are available for the selected facet.

Additional Information

For more information, go to Developer Guide section in the Demo Kit and navigate to More About Controls > sap.m > Facet Filter

Constructor Summary
new sap.m.FacetFilter(sId?, mSettings?)Constructor for a new FacetFilter.
Event Summary
confirm(oControlEvent)Fired when the user confirms filter selection.
reset(oControlEvent)Fired when the Reset button is pressed to inform that all FacetFilterLists need to be reset.
Events borrowed from class sap.ui.core.Control
Method Summary
sap.m.FacetFilter.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.m.FacetFilter with name sClassName and enriches it with the information contained in oClassInfo.
sap.m.FacetFilter.getMetadata()Returns a metadata object for class sap.m.FacetFilter.
addList(oList)Adds some list to the aggregation lists.
attachConfirm(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the confirm event of this sap.m.FacetFilter.
attachReset(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the reset event of this sap.m.FacetFilter.
destroyLists()Destroys all the lists in the aggregation lists.
detachConfirm(fnFunction, oListener)Detaches event handler fnFunction from the confirm event of this sap.m.FacetFilter.
detachReset(fnFunction, oListener)Detaches event handler fnFunction from the reset event of this sap.m.FacetFilter.
fireConfirm(mParameters?)Fires event confirm to attached listeners.
fireReset(mParameters?)Fires event reset to attached listeners.
getLists()Gets content of aggregation lists.
getLiveSearch()Gets current value of property liveSearch.
getShowPersonalization()Gets current value of property showPersonalization.
getShowPopoverOKButton()Gets current value of property showPopoverOKButton.
getShowReset()Gets current value of property showReset.
getShowSummaryBar()Gets current value of property showSummaryBar.
getType()Gets current value of property type.
indexOfList(oList)Checks for the provided sap.m.FacetFilterList in the aggregation lists.
insertList(oList, iIndex)Inserts a list into the aggregation lists.
openFilterDialog()Opens the FacetFilter dialog.
removeAllLists()Removes all the controls from the aggregation lists.
removeList(vList)Removes a list from the aggregation lists.
setLiveSearch(bLiveSearch)Sets a new value for property liveSearch.
setShowPersonalization(bShowPersonalization)Sets a new value for property showPersonalization.
setShowPopoverOKButton(bShowPopoverOKButton)Sets a new value for property showPopoverOKButton.
setShowReset(bShowReset)Sets a new value for property showReset.
setShowSummaryBar(bShowSummaryBar)Sets a new value for property showSummaryBar.
setType(sType)Sets a new value for property type.
Constructor Detail
new sap.m.FacetFilter(sId?, mSettings?)

Constructor for a new FacetFilter.

Accepts an object literal mSettings that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject for a general description of the syntax of the settings object.

The supported settings are:

  • Properties

  • Aggregations

    • lists : sap.m.FacetFilterList[] (default)

  • Events

    • reset : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]
    • confirm : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]

In addition, all settings applicable to the base type sap.ui.core.Control can be used as well.

Parameters:
stringsId?ID for the new control, generated automatically if no ID is given
objectmSettings?Initial settings for the new control
Event Detail
confirm(oControlEvent)
Fired when the user confirms filter selection.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
reset(oControlEvent)
Fired when the Reset button is pressed to inform that all FacetFilterLists need to be reset.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
Method Detail
sap.m.FacetFilter.extend(sClassName, oClassInfo?, FNMetaImpl?): function

Creates a new subclass of class sap.m.FacetFilter with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

Parameters:
stringsClassNameName of the class being created
objectoClassInfo?Object literal with information about the class
functionFNMetaImpl?Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata
Returns:
functionCreated class / constructor function
sap.m.FacetFilter.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.m.FacetFilter.
Returns:
sap.ui.base.MetadataMetadata object describing this class
addList(oList): sap.m.FacetFilter
Adds some list to the aggregation lists.
Parameters:
sap.m.FacetFilterListoListthe list to add; if empty, nothing is inserted
Returns:
sap.m.FacetFilterReference to this in order to allow method chaining
attachConfirm(oData?, fnFunction, oListener?): sap.m.FacetFilter

Attaches event handler fnFunction to the confirm event of this sap.m.FacetFilter.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.FacetFilter itself.

Fired when the user confirms filter selection.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.FacetFilter itself
Returns:
sap.m.FacetFilterReference to this in order to allow method chaining
attachReset(oData?, fnFunction, oListener?): sap.m.FacetFilter

Attaches event handler fnFunction to the reset event of this sap.m.FacetFilter.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.FacetFilter itself.

Fired when the Reset button is pressed to inform that all FacetFilterLists need to be reset.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.FacetFilter itself
Returns:
sap.m.FacetFilterReference to this in order to allow method chaining
destroyLists(): sap.m.FacetFilter
Destroys all the lists in the aggregation lists.
Returns:
sap.m.FacetFilterReference to this in order to allow method chaining
detachConfirm(fnFunction, oListener): sap.m.FacetFilter

Detaches event handler fnFunction from the confirm event of this sap.m.FacetFilter.

The passed function and listener object must match the ones used for event registration.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.FacetFilterReference to this in order to allow method chaining
detachReset(fnFunction, oListener): sap.m.FacetFilter

Detaches event handler fnFunction from the reset event of this sap.m.FacetFilter.

The passed function and listener object must match the ones used for event registration.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.FacetFilterReference to this in order to allow method chaining
fireConfirm(mParameters?): sap.m.FacetFilter
Fires event confirm to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
Returns:
sap.m.FacetFilterReference to this in order to allow method chaining
fireReset(mParameters?): sap.m.FacetFilter
Fires event reset to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
Returns:
sap.m.FacetFilterReference to this in order to allow method chaining
getLists(): sap.m.FacetFilterList[]

Gets content of aggregation lists.

Collection of FacetFilterList controls.

Returns:
sap.m.FacetFilterList[]
getLiveSearch(): boolean

Gets current value of property liveSearch.

Enables/disables live search in the search field of all sap.m.FacetFilterList instances.

Default value is true.

Returns:
booleanValue of property liveSearch
getShowPersonalization(): boolean

Gets current value of property showPersonalization.

If set to true and the FacetFilter type is Simple, then the Add Facet icon will be displayed and each facet button will also have a Facet Remove icon displayed beside it, allowing the user to deactivate the facet.

Default value is false.

Returns:
booleanValue of property showPersonalization
getShowPopoverOKButton(): boolean

Gets current value of property showPopoverOKButton.

If set to true, an OK button is displayed for every FacetFilterList popover. This button allows the user to close the popover from within the popover instead of having to click outside of it.

Default value is false.

Returns:
booleanValue of property showPopoverOKButton
getShowReset(): boolean

Gets current value of property showReset.

Shows/hides the FacetFilter Reset button.

Default value is true.

Returns:
booleanValue of property showReset
getShowSummaryBar(): boolean

Gets current value of property showSummaryBar.

Shows the summary bar instead of the FacetFilter buttons bar when set to true.

Default value is false.

Returns:
booleanValue of property showSummaryBar

Gets current value of property type.

Defines the default appearance of the FacetFilter on the device. Possible values are Simple (default) and Light.

Default value is Simple.

Returns:
sap.m.FacetFilterTypeValue of property type
indexOfList(oList): int
Checks for the provided sap.m.FacetFilterList in the aggregation lists. and returns its index if found or -1 otherwise.
Parameters:
sap.m.FacetFilterListoListThe list whose index is looked for
Returns:
intThe index of the provided control in the aggregation if found, or -1 otherwise
insertList(oList, iIndex): sap.m.FacetFilter
Inserts a list into the aggregation lists.
Parameters:
sap.m.FacetFilterListoListthe list to insert; if empty, nothing is inserted
intiIndexthe 0-based index the list should be inserted at; for a negative value of iIndex, the list is inserted at position 0; for a value greater than the current size of the aggregation, the list is inserted at the last position
Returns:
sap.m.FacetFilterReference to this in order to allow method chaining
openFilterDialog(): sap.m.FacetFilter
Opens the FacetFilter dialog.
Returns:
sap.m.FacetFilterthis pointer for chaining
removeAllLists(): sap.m.FacetFilterList[]

Removes all the controls from the aggregation lists.

Additionally, it unregisters them from the hosting UIArea.

Returns:
sap.m.FacetFilterList[]An array of the removed elements (might be empty)
removeList(vList): sap.m.FacetFilterList
Removes a list from the aggregation lists.
Parameters:
int|string|sap.m.FacetFilterListvListThe list to remove or its index or id
Returns:
sap.m.FacetFilterListThe removed list or null
setLiveSearch(bLiveSearch): sap.m.FacetFilter

Sets a new value for property liveSearch.

Enables/disables live search in the search field of all sap.m.FacetFilterList instances.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Parameters:
booleanbLiveSearchNew value for property liveSearch
Returns:
sap.m.FacetFilterReference to this in order to allow method chaining
setShowPersonalization(bShowPersonalization): sap.m.FacetFilter

Sets a new value for property showPersonalization.

If set to true and the FacetFilter type is Simple, then the Add Facet icon will be displayed and each facet button will also have a Facet Remove icon displayed beside it, allowing the user to deactivate the facet.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Parameters:
booleanbShowPersonalizationNew value for property showPersonalization
Returns:
sap.m.FacetFilterReference to this in order to allow method chaining
setShowPopoverOKButton(bShowPopoverOKButton): sap.m.FacetFilter

Sets a new value for property showPopoverOKButton.

If set to true, an OK button is displayed for every FacetFilterList popover. This button allows the user to close the popover from within the popover instead of having to click outside of it.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Parameters:
booleanbShowPopoverOKButtonNew value for property showPopoverOKButton
Returns:
sap.m.FacetFilterReference to this in order to allow method chaining
setShowReset(bShowReset): sap.m.FacetFilter

Sets a new value for property showReset.

Shows/hides the FacetFilter Reset button.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Parameters:
booleanbShowResetNew value for property showReset
Returns:
sap.m.FacetFilterReference to this in order to allow method chaining
setShowSummaryBar(bShowSummaryBar): sap.m.FacetFilter

Sets a new value for property showSummaryBar.

Shows the summary bar instead of the FacetFilter buttons bar when set to true.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Parameters:
booleanbShowSummaryBarNew value for property showSummaryBar
Returns:
sap.m.FacetFilterReference to this in order to allow method chaining
setType(sType): sap.m.FacetFilter

Sets a new value for property type.

Defines the default appearance of the FacetFilter on the device. Possible values are Simple (default) and Light.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Simple.

Parameters:
sap.m.FacetFilterTypesTypeNew value for property type
Returns:
sap.m.FacetFilterReference to this in order to allow method chaining