class sap.m.FacetFilter

Control sample: sap.m.FacetFilter
Visiblity: public
UX Guidelines:
Implements: sap.ui.core.IShrinkable
Available since: N/A
Module: sap/m/FacetFilter
Application Component: CA-UI5-CTR-BAL

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:

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

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#constructor for a general description of the syntax of the settings object.

new sap.m.FacetFilter(sId?, mSettings?)
Param Type Default Value Description
sId? string

ID for the new control, generated automatically if no ID is given

mSettings? object

Initial settings for the new control


Properties

Name Type Default Value Description
liveSearch boolean true

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

Visibility: public
showPersonalization boolean false

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.

Note: Always set this property to true when your facet lists are not active, so that the user is able to select them and interact with them.

Visibility: public
showPopoverOKButton boolean false

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.

Visibility: public
showReset boolean true

Shows/hides the FacetFilter Reset button.

Visibility: public
showSummaryBar boolean false

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

Visibility: public
type sap.m.FacetFilterType Simple

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

Visibility: public

Aggregations

Default Aggregation: lists

Name Cardinality Type Description
addFacetButton 0..1 sap.m.Button

Hidden aggregation for the Add Facet button. This button allows the user to open the facet dialog and add or configure facets. This is displayed only if personalization is enabled and the FacetFilter is of type Simple.

arrowLeft 0..1 sap.ui.core.Icon

Hidden aggregation for the arrow that scrolls the facets to the left when the FacetFilter is set to type Simple.

arrowRight 0..1 sap.ui.core.Icon

Hidden aggregation for the arrow that scrolls the facets to the right when the FacetFilter is set to type Simple.

buttons 0..n sap.m.Button

Hidden aggregation of buttons that open each FacetFilterList popover. These buttons are displayed only when the FacetFilter is of type Simple.

dialog 0..1 sap.m.Dialog

Hidden aggregation for the dialog that displays the facet and filter items pages.

lists (default) 0..n sap.m.FacetFilterList

Collection of FacetFilterList controls.

popover 0..1 sap.m.Popover

Hidden aggregation for the FacetFilterLists popover.

removeFacetIcons 0..n sap.ui.core.Icon

Hidden aggregation of icons for setting FacetFilterLists to inactive, thereby, removing the FacetFilter button from the display. The icon is displayed only if personalization is enabled.

resetButton 0..1 sap.m.Button

Hidden aggregation for the Reset button displayed for FacetFilter of type Simple.

summaryBar 0..1 sap.m.Toolbar

Hidden aggregation for the summary bar.


Events Overview

Event Description
confirm

Fired when the user confirms filter selection.

reset

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

The default filtering behavior of the sap.m.FacetFilterList can be prevented by calling sap.ui.base.Event.prototype.preventDefault function in the search event handler function. If the default filtering behavior is prevented then filtering behavior has to be defined at application level inside the search and reset event handler functions.

confirm

Fired when the user confirms filter selection.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

reset

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

The default filtering behavior of the sap.m.FacetFilterList can be prevented by calling sap.ui.base.Event.prototype.preventDefault function in the search event handler function. If the default filtering behavior is prevented then filtering behavior has to be defined at application level inside the search and reset event handler functions.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

Methods Overview

Method Description
addList

Adds some list to the aggregation lists.

attachConfirm

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.

attachReset

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.

The default filtering behavior of the sap.m.FacetFilterList can be prevented by calling sap.ui.base.Event.prototype.preventDefault function in the search event handler function. If the default filtering behavior is prevented then filtering behavior has to be defined at application level inside the search and reset event handler functions.

destroyLists

Destroys all the lists in the aggregation lists.

detachConfirm

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.

detachReset

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.

sap.m.FacetFilter.extend

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.

fireConfirm

Fires event confirm to attached listeners.

fireReset

Fires event reset to attached listeners.

getLists

Gets content of aggregation lists.

Collection of FacetFilterList controls.

getLiveSearch

Gets current value of property liveSearch.

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

Default value is true.

sap.m.FacetFilter.getMetadata

Returns a metadata object for class sap.m.FacetFilter.

getShowPersonalization

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.

Note: Always set this property to true when your facet lists are not active, so that the user is able to select them and interact with them.

Default value is false.

getShowPopoverOKButton

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.

getShowReset

Gets current value of property showReset.

Shows/hides the FacetFilter Reset button.

Default value is true.

getShowSummaryBar

Gets current value of property showSummaryBar.

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

Default value is false.

getType

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.

indexOfList

Checks for the provided sap.m.FacetFilterList in the aggregation lists. and returns its index if found or -1 otherwise.

insertList

Inserts a list into the aggregation lists.

openFilterDialog

Opens the FacetFilter dialog.

refreshFacetList

This method refreshes the internal model for thr FacetList. It should be called everytime when the model of FacetFilter is changed and update to the FacetList is needed

removeAllLists

Removes all the controls from the aggregation lists.

Additionally, it unregisters them from the hosting UIArea.

removeList

Removes a list from the aggregation lists.

setLiveSearch

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.

setShowPersonalization

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.

Note: Always set this property to true when your facet lists are not active, so that the user is able to select them and interact with them.

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

Default value is false.

setShowPopoverOKButton

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.

setShowReset

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.

setShowSummaryBar

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.

setType

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.

addList

Adds some list to the aggregation lists.

Param Type DefaultValue Description
oList sap.m.FacetFilterList

The list to add; if empty, nothing is inserted

attachConfirm

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.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.FacetFilter itself

attachReset

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.

The default filtering behavior of the sap.m.FacetFilterList can be prevented by calling sap.ui.base.Event.prototype.preventDefault function in the search event handler function. If the default filtering behavior is prevented then filtering behavior has to be defined at application level inside the search and reset event handler functions.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.FacetFilter itself

destroyLists

Destroys all the lists in the aggregation lists.

detachConfirm

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.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachReset

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.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

sap.m.FacetFilter.extend

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.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

fireConfirm

Fires event confirm to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireReset

Fires event reset to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

getLists

Gets content of aggregation lists.

Collection of FacetFilterList controls.

getLiveSearch

Gets current value of property liveSearch.

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

Default value is true.

sap.m.FacetFilter.getMetadata

Returns a metadata object for class sap.m.FacetFilter.

getShowPersonalization

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.

Note: Always set this property to true when your facet lists are not active, so that the user is able to select them and interact with them.

Default value is false.

getShowPopoverOKButton

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.

getShowReset

Gets current value of property showReset.

Shows/hides the FacetFilter Reset button.

Default value is true.

getShowSummaryBar

Gets current value of property showSummaryBar.

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

Default value is false.

getType

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.

indexOfList

Checks for the provided sap.m.FacetFilterList in the aggregation lists. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oList sap.m.FacetFilterList

The list whose index is looked for

insertList

Inserts a list into the aggregation lists.

Param Type DefaultValue Description
oList sap.m.FacetFilterList

The list to insert; if empty, nothing is inserted

iIndex int

The 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

openFilterDialog

Opens the FacetFilter dialog.

refreshFacetList

This method refreshes the internal model for thr FacetList. It should be called everytime when the model of FacetFilter is changed and update to the FacetList is needed

removeAllLists

Removes all the controls from the aggregation lists.

Additionally, it unregisters them from the hosting UIArea.

removeList

Removes a list from the aggregation lists.

Param Type DefaultValue Description
vList int string sap.m.FacetFilterList

The list to remove or its index or id

setLiveSearch

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.

Param Type DefaultValue Description
bLiveSearch boolean true

New value for property liveSearch

setShowPersonalization

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.

Note: Always set this property to true when your facet lists are not active, so that the user is able to select them and interact with them.

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

Default value is false.

Param Type DefaultValue Description
bShowPersonalization boolean false

New value for property showPersonalization

setShowPopoverOKButton

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.

Param Type DefaultValue Description
bShowPopoverOKButton boolean false

New value for property showPopoverOKButton

setShowReset

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.

Param Type DefaultValue Description
bShowReset boolean true

New value for property showReset

setShowSummaryBar

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.

Param Type DefaultValue Description
bShowSummaryBar boolean false

New value for property showSummaryBar

setType

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.

Param Type DefaultValue Description
sType sap.m.FacetFilterType Simple

New value for property type