Provides filtering functionality with multiple parameters.
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.
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.
The FacetFilter
supports the following two types, which can be configured using the control's type
property:
For more information, go to Developer Guide section in the Demo Kit and navigate to More About Controls > sap.m > Facet Filter
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 |
Name | Type | Default Value | Description |
---|---|---|---|
liveSearch | boolean | true | Enables/disables live search in the search field of all |
showPersonalization | boolean | false | If set to Note: Always set this property to |
showPopoverOKButton | boolean | false | If set to |
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 |
type | sap.m.FacetFilterType | Simple | Defines the default appearance of the FacetFilter on the device. Possible values are |
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 |
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 |
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 |
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 |
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 |
summaryBar | 0..1 | sap.m.Toolbar |
Hidden aggregation for the summary bar. |
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 |
Fired when the user confirms filter selection.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object |
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 |
Method | Description |
---|---|
addList |
Adds some list to the aggregation lists. |
attachConfirm |
Attaches event handler When called, the context of the event handler (its Fired when the user confirms filter selection. |
attachReset |
Attaches event handler When called, the context of the event handler (its 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 |
destroyLists |
Destroys all the lists in the aggregation lists. |
detachConfirm |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachReset |
Detaches event handler 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
|
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 Default value is |
sap.m.FacetFilter.getMetadata |
Returns a metadata object for class sap.m.FacetFilter. |
getShowPersonalization |
Gets current value of property showPersonalization. If set to Note: Always set this property to Default value is |
getShowPopoverOKButton |
Gets current value of property showPopoverOKButton. If set to Default value is |
getShowReset |
Gets current value of property showReset. Shows/hides the FacetFilter Reset button. Default value is |
getShowSummaryBar |
Gets current value of property showSummaryBar. Shows the summary bar instead of the FacetFilter buttons bar when set to Default value is |
getType |
Gets current value of property type. Defines the default appearance of the FacetFilter on the device. Possible values are Default value is |
indexOfList |
Checks for the provided |
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 When called with a value of Default value is |
setShowPersonalization |
Sets a new value for property showPersonalization. If set to Note: Always set this property to When called with a value of Default value is |
setShowPopoverOKButton |
Sets a new value for property showPopoverOKButton. If set to When called with a value of Default value is |
setShowReset |
Sets a new value for property showReset. Shows/hides the FacetFilter Reset button. When called with a value of Default value is |
setShowSummaryBar |
Sets a new value for property showSummaryBar. Shows the summary bar instead of the FacetFilter buttons bar when set to When called with a value of Default value is |
setType |
Sets a new value for property type. Defines the default appearance of the FacetFilter on the device. Possible values are When called with a value of Default value is |
Adds some list to the aggregation lists.
Param | Type | DefaultValue | Description |
---|---|---|---|
oList | sap.m.FacetFilterList |
The list to add; if empty, nothing is inserted |
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 |
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 |
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 |
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 |
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 |
Fires event confirm to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
Fires event reset to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
Gets current value of property liveSearch.
Enables/disables live search in the search field of all sap.m.FacetFilterList
instances.
Default value is true
.
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
.
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
.
Gets current value of property showReset.
Shows/hides the FacetFilter Reset button.
Default value is true
.
Gets current value of property showSummaryBar.
Shows the summary bar instead of the FacetFilter buttons bar when set to true
.
Default value is false
.
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
.
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 |
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 |
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
Removes all the controls from the aggregation lists.
Additionally, it unregisters them from the hosting UIArea.
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 |
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 |
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 |
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 |
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 |
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 |
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 |