class sap.ui.comp.smartfilterbar.SmartFilterBar

Visiblity: public
UX Guidelines: Smart Filter Bar
Implements:
Available since: N/A
Module: sap/ui/comp/smartfilterbar/SmartFilterBar
Application Component: CA-UI5-CMP

The SmartFilterBar control uses the OData metadata of an entity in order to create a FilterBar.
Whether a field is visible on the FilterBar, supports type-ahead and value help, for example, is automatically determined. When you use control configurations and group configurations it is possible to configure the FilterBar and adapt it according to your needs.
Note: Most of the attributes/properties are not dynamic and cannot be changed once the control has been initialized.

Important: Keep in mind that SmartFilterBar, like all SAPUI5 smart controls, retrieves and analyzes the metadata and annotations of OData services. The OData metadata is its primary API. These OData services are not part of the SAPUI5 framework and are usually maintained by the backend developers of your application.

With time, SmartFilterBar can evolve and acquire new features. This means that its behavior or functionalities may change if the annotations that define this change are maintained in your backend metadata. To benefit from the new functionalities, your application should be able to adapt the backend metadata. Therefore, we recommend using SmartFilterBar only if you have control over the metadata of your application.


Constructor

Constructor for a new smartfilterbar/SmartFilterBar.

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.ui.comp.smartfilterbar.SmartFilterBar(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
basicSearchFieldName string

Name of the field that is the focus of the basic search.

Visibility: public
considerAnalyticalParameters boolean false

Indicates if the analytical parameters (SelectionVariant) must be taken into consideration.

Since: 1.42.0.

Visibility: public
considerSelectionVariants boolean false

Indicates if the annotation com.sap.vocabularies.UI.v1.SelectionVariant is taken into account.
Note: Only relevant for control level personalization.

Visibility: public
defaultSelectionVariantName string

Determines one specific variant that is based on the com.sap.vocabularies.UI.v1.SelectionVariant annotation, which is then used as the default variant.
This property is only relevant in case considerSelectionVariants is set to true and will only be applied if there is no user-defined default variant specified.
Note: Only relevant for control level personalization.

Visibility: public
enableBasicSearch boolean false

Enables the basic search field. The entered value can be accessed with sap.ui.comp.smartfilterbar.SmartFilterBar#getParameters. Note: When the SmartFilterBar control is used with a sap.ui.comp.smarttable.SmartTable control the parameters are handled automatically. Therefore, this must only be enabled for OData service entities that support basic search.

Visibility: public
entitySet string

The OData entity set whose metadata is used to create the SmartFilterBar. Note: Changing this value after the SmartFilterBar is initialized (initialise event was fired) has no effect.

Visibility: public
entityType string

The OData entity type whose metadata is used to create the SmartFilterBar. Note: Changing this value after the SmartFilterBar is initialized (initialise event was fired) has no effect.

Visibility: public
liveMode boolean false

If set the search will be automatically triggered, when a filter value was set via the change event.
Note: The liveMode only operates on non-mobile scenarios.
Additionally, if liveMode is set, the following applies:

  • The error messagebox is not displayed, and the showMessages property is ignored.
  • The search is triggered after a variant has been selected.
  • Execute on Select for VariantManagement is not shown and not taken into account


Since: 1.40.

Visibility: public
navigationProperties string empty string

This property is only evaluated if the property sap.ui.comp.smartfilterbar.SmartFilterBar#getUseProvidedNavigationProperties is set to true. It contains a comma-separated list of navigation property names which are checked for filters.


Since: 1.48.

Visibility: public
resourceUri string

Optional. The OData service URL. If it is not specified, the service URL from the OData model (this.getModel()) will be used. Note: Changing this value after the SmartFilterBar is initialized (initialise event was fired) has no effect.

Visibility: public
showMessages boolean false

If set to true, any errors that occur during the search, are displayed in a message box in addition to the valueState with the error. Note: As of version 1.89, the default value has been changed from true to false.

Since: 1.40.

Visibility: public
suppressSelection boolean false

If set to true all search requests will be ignored. This functionality is only intended to be used internally to enable an optimal solution when the filter bar is controlled by the smart templates. NOTE: As long as this property is set to true, all search requests will be neglected.

Since: 1.44.0.

Visibility: public
useDateRangeType boolean

If set to true all date fields with filter restriction interval will be treated as DateTimeRange filters. The useDateRangeType can be set only once during initialization. Note: If this property is set to true and any date filters with filter restriction interval were stored as part of a variant, the values of these filters cannot be applied. If this property is set to false, any previously stored filters which were treated as type DateTimeRange based on the former setting, cannot be converted back to the standard date interval.

Since: 1.46.0.

Visibility: public
useProvidedNavigationProperties boolean false

If set to true, only the navigation properties mentioned in property sap.ui.comp.smartfilterbar.SmartFilterBar#getNavigationProperties are checked for further filters.

Since: 1.48.

Visibility: public

Borrowed Properties

Name Type Default Value Description
advancedMode boolean false

The advanced mode is only relevant for the value help scenario. UI representation is different from the standard FilterBar.

Visibility: public
considerGroupTitle boolean false

If this property is set, then the label for filters will be prefixed with the group title.

Since: 1.28.0.

Visibility: public
deltaVariantMode boolean true

Stores the delta as compared to the standard variant.

Since: 1.34.0.

Visibility: public
expandAdvancedArea boolean false

Collapses/expands the advanced area.

Visibility: public
filterBarExpanded boolean true

Shows the filters area. When property useToolbar is set to false, filterBarExpanded is set to true automatically. Note: When SmartFilterBar is used inside a ValueHelpDialog, it is initially collapsed. The filter bar is initially expanded in the following cases:

- When there is no basic search field. - When preventInitialDataFetchInValueHelpDialog is set to true or the fetchValues property of the valueList annotation is set to 2. - When there are mandatory fields, all fields are expanded (not only the first 7).

Since: 1.26.1.

Visibility: public
filterContainerWidth string 12rem

Sets the width of the filters container.

Since: 1.34.0.

Visibility: public
header string empty string

Specifies header text that is shown in the toolbar on the first position. This property is ignored, when useToolbar is set to false.

Since: 1.38.0.

Visibility: public
isRunningInValueHelpDialog boolean false

Sets whether the filter bar should look like the filters area in a ValueHelpDialog. True for SmartFilterBar when used in a ValueHelpDialog. False otherwise.

Visibility: public
persistencyKey string empty string

Key used to access personalization data. Only if the persistencyKey is provided, will the VariantManagement control be used.

Visibility: public
searchEnabled boolean true

Enables/disables the Search button.

Visibility: public
showClearButton boolean false

Handles visibility of the Clear button on the Filters dialog.

Visibility: public
showClearOnFB boolean false

Handles visibility of the Clear button on the FilterBar.

Since: 1.28.0.

Visibility: public
showFilterConfiguration boolean true

Handles visibility of the Filters button on the FilterBar.

Since: 1.38.0.

Visibility: public
showGoButton boolean

Handles visibility of the Go button on the FilterBar.

Since: 1.26.1.

Visibility: public
showGoOnFB boolean true

Handles visibility of the Go button on the FilterBar.

Since: 1.28.0.

Visibility: public
showRestoreButton boolean true

Handles visibility of the "Restore" button on the "Filters" dialog. Note: Restore works only automatically when a property persistencyKey is set and therefore Variant Management is used. In all other cases the "restore" behavior needs to be implemented by the app, based on the event reset. Since 1.84 the "Restore" button text is changed to "Reset"

Since: 1.26.1.

Visibility: public
showRestoreOnFB boolean false

Handles visibility of the Restore button on the FilterBar.

Since: 1.28.0.

Visibility: public
useSnapshot boolean

Determines the behavior when reset is executed.
Note: This property is only relevant if no variant management is used, and the filter bar is not used in the advanced mode. A snapshot shows the current state of the filter bar, just before the Filters dialog is opened.

  • undefined (default) defines the standard behavior: snapshot will be applied after reset was triggered
  • false defines that the snapshot will not be applied
  • trueis not considered at all


Since: 1.44.

Visibility: public
useToolbar boolean true

Determines what design is used. Default is the design with toolbar. If the property useToolbar is set to false, the property filterBarExpanded is set to true automatically. Note:
If set to false, the VariantManagement control is not available at all. This scenario is only intended for the sap.ui.comp.smartfilterbar.SmartFilterBar.

Since: 1.38.0.

Visibility: public

Aggregations

Default Aggregation:

Name Cardinality Type Description
controlConfiguration 0..n sap.ui.comp.smartfilterbar.ControlConfiguration

Using control configurations you can add additional configuration to filter fields, for example set custom labels, change the order of fields, or change the filter field control type. Note: Changing the values here after the SmartFilter is initialized (initialise event was fired) has no effect.

groupConfiguration 0..n sap.ui.comp.smartfilterbar.GroupConfiguration

Provides the possibility to add additional configuration to groups. Groups are used to show fields in the advanced area of the SmartFilterBar. With additional configuration, you can for example set custom labels or change the order of groups. Note: Changing the values here after the SmartFilter is initialized (initialise event was fired) has no effect.

Borrowed Aggregations

Name Cardinality Type Description
filterGroupItems 0..n sap.ui.comp.filterbar.FilterGroupItem

Contains all FilterBar filters.
Note:In case a filter has to be added to the basic group

  • the property groupName has to be set to the constant sap.ui.comp.filterbar.FilterBar.INTERNAL_GROUP
  • the property groupLabel will be handled internally and will be ignored, if set
  • the property partOfCurrentVariant has to be set to true
  • if the property visibleInFilterBar is set to true, the property partOfCurrentVariant will be set internally also to true

filterItems 0..n sap.ui.comp.filterbar.FilterItem

Filters belonging to the basic group.
Deprecated as of version 1.48.0. Use aggregation filterGroupItems instead.


Associations

Name Cardinality Type Description
smartVariant 0..1 sap.ui.comp.smartvariants.SmartVariantManagement

Identifies the SmartVariant control which should be used for the personalization.

Since: 1.38.


Events Overview

Event Description
pendingChange

This event is fired after the pending state of the FilterBar control changes.

Since: 1.36.

pendingChange

This event is fired after the pending state of the FilterBar control changes.

Since: 1.36.

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

Methods Overview

{
	"custom": {
		"search-focus": "MySearchFocusFieldName",
		"search": "MySearchString"
	}
}

These parameters can be handed over as custom parameters, for example, to the sap.ui.model.odata.v2.ODataListBinding.

Method Description
_attachValueListAnnotationLoaded
addControlConfiguration

Adds some controlConfiguration to the aggregation controlConfiguration.

addFieldToAdvancedArea

Searches for the filter field having the specified OData key and adds this filter field to the advanced area. If there is no corresponding field in the OData metadata, this method has no effect.

addGroupConfiguration

Adds some groupConfiguration to the aggregation groupConfiguration.

applyVariant

Applies the current variant as opposed to fetchVariant. The variant is retrieved via the flex layer.

attachPendingChange

Attaches event handler fnFunction to the pendingChange event of this sap.ui.comp.smartfilterbar.SmartFilterBar.

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.ui.comp.smartfilterbar.SmartFilterBar itself.

This event is fired after the pending state of the FilterBar control changes.

destroyControlConfiguration

Destroys all the controlConfiguration in the aggregation controlConfiguration.

destroyGroupConfiguration

Destroys all the groupConfiguration in the aggregation groupConfiguration.

detachPendingChange

Detaches event handler fnFunction from the pendingChange event of this sap.ui.comp.smartfilterbar.SmartFilterBar.

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

ensureLoadedValueHelp

Ensures the associated ValueHelpProvider is loaded.

sap.ui.comp.smartfilterbar.SmartFilterBar.extend

Creates a new subclass of class sap.ui.comp.smartfilterbar.SmartFilterBar 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.comp.filterbar.FilterBar.extend.

fetchVariant

Retrieves the currently visible filters and the values for storing them as variants. The result will be passed on as a JSON object to the callee smart variant control.

firePendingChange

Fires event pendingChange to attached listeners.

getAnalyticBindingPath

Returns the binding paths for the parameters.

getBasicSearchControl

Returns an instance of the control for the basic search.

getBasicSearchFieldName

Gets current value of property basicSearchFieldName.

Name of the field that is the focus of the basic search.

getConsiderAnalyticalParameters

Gets current value of property considerAnalyticalParameters.

Indicates if the analytical parameters (SelectionVariant) must be taken into consideration.

Default value is false.

getConsiderSelectionVariants

Gets current value of property considerSelectionVariants.

Indicates if the annotation com.sap.vocabularies.UI.v1.SelectionVariant is taken into account.
Note: Only relevant for control level personalization.

Default value is false.

Since 1.87 Please use the <code>com.sap.vocabularies.UI.v1.SelectionPresentationVariant</code> annotation through the {@link sap.ui.comp.smartvariants.SmartVariantManagement#setEntitySet}
getControlByKey

Returns the control (if any) with the specified key (Property name in OData entity). Use just the property name as the key when getting a control from the basic area. Example: "CompanyCode" & Use "EntityName/GroupName.FieldName" format to get controls from groups. Example:"Account.CompanyCode"

getControlConfiguration

Gets content of aggregation controlConfiguration.

Using control configurations you can add additional configuration to filter fields, for example set custom labels, change the order of fields, or change the filter field control type. Note: Changing the values here after the SmartFilter is initialized (initialise event was fired) has no effect.

getCustomFilterData

Returns the _CUSTOM data currently set in the filter data model.

getDefaultSelectionVariantName

Gets current value of property defaultSelectionVariantName.

Determines one specific variant that is based on the com.sap.vocabularies.UI.v1.SelectionVariant annotation, which is then used as the default variant.
This property is only relevant in case considerSelectionVariants is set to true and will only be applied if there is no user-defined default variant specified.
Note: Only relevant for control level personalization.

Since 1.87 Please use the <code>com.sap.vocabularies.UI.v1.SelectionPresentationVariant</code> annotation through the {@link sap.ui.comp.smartvariants.SmartVariantManagement#setEntitySet}
getDescriptionForKeys

Reads the descriptions for given filters and value keys.

getEnableBasicSearch

Gets current value of property enableBasicSearch.

Enables the basic search field. The entered value can be accessed with sap.ui.comp.smartfilterbar.SmartFilterBar#getParameters. Note: When the SmartFilterBar control is used with a sap.ui.comp.smarttable.SmartTable control the parameters are handled automatically. Therefore, this must only be enabled for OData service entities that support basic search.

Default value is false.

getEntitySet

Gets current value of property entitySet.

The OData entity set whose metadata is used to create the SmartFilterBar. Note: Changing this value after the SmartFilterBar is initialized (initialise event was fired) has no effect.

getEntityType

Gets current value of property entityType.

The OData entity type whose metadata is used to create the SmartFilterBar. Note: Changing this value after the SmartFilterBar is initialized (initialise event was fired) has no effect.

Since 1.40 Use <code>entitySet</code> property instead of this one, to enable V4 annotation support
getFilterContextUrl

Get the filter context url.

getFilterData

Returns the data currently set in the filter data model.

getFilterDataAsString

Returns the data currently set in the filter data model as string.

getFilters

Returns an array of filters (sap.ui.model.Filter instances), for visible fields, that can be used to restrict the query result from OData.
The result of this method can directly be used during aggregation binding or OData read.

getFiltersWithValues

Returns all filter items

  • Containing a value
  • With the visible property set to true
  • That are either flagged as partOfCurrentVariant or visibleInFilterBar
  • That are not custom filters
Even hidden filters will be considered as long as the mentioned criteria is fullfilled.

getGroupConfiguration

Gets content of aggregation groupConfiguration.

Provides the possibility to add additional configuration to groups. Groups are used to show fields in the advanced area of the SmartFilterBar. With additional configuration, you can for example set custom labels or change the order of groups. Note: Changing the values here after the SmartFilter is initialized (initialise event was fired) has no effect.

getLiveMode

Gets current value of property liveMode.

If set the search will be automatically triggered, when a filter value was set via the change event.
Note: The liveMode only operates on non-mobile scenarios.
Additionally, if liveMode is set, the following applies:

  • The error messagebox is not displayed, and the showMessages property is ignored.
  • The search is triggered after a variant has been selected.
  • Execute on Select for VariantManagement is not shown and not taken into account

Default value is false.

sap.ui.comp.smartfilterbar.SmartFilterBar.getMetadata

Returns a metadata object for class sap.ui.comp.smartfilterbar.SmartFilterBar.

getModelData

Get the model data.

getNavigationProperties

Gets current value of property navigationProperties.

This property is only evaluated if the property sap.ui.comp.smartfilterbar.SmartFilterBar#getUseProvidedNavigationProperties is set to true. It contains a comma-separated list of navigation property names which are checked for filters.

Default value is empty string.

getParameterBindingPath

Returns the binding paths for the parameters. This API can be used for both analytical and non-analytical services. NoteFor analytical services, the API is NOT stable yet. Use at your own risk.

getParameterContextUrl

Get the parameter context url.

getParameters

Returns a parameter object that can be used to restrict the result of an OData service request if a basic search is performed.

Example of a returned object:
getResourceUri

Gets current value of property resourceUri.

Optional. The OData service URL. If it is not specified, the service URL from the OData model (this.getModel()) will be used. Note: Changing this value after the SmartFilterBar is initialized (initialise event was fired) has no effect.

Since 1.29 Set an ODataModel as the main model on your control/view instead
getShowMessages

Gets current value of property showMessages.

If set to true, any errors that occur during the search, are displayed in a message box in addition to the valueState with the error. Note: As of version 1.89, the default value has been changed from true to false.

Default value is false.

getSmartVariant

ID of the element which is the current target of the association smartVariant, or null.

getSuppressSelection

Gets current value of property suppressSelection.

If set to true all search requests will be ignored. This functionality is only intended to be used internally to enable an optimal solution when the filter bar is controlled by the smart templates. NOTE: As long as this property is set to true, all search requests will be neglected.

Default value is false.

getUseDateRangeType

Gets current value of property useDateRangeType.

If set to true all date fields with filter restriction interval will be treated as DateTimeRange filters. The useDateRangeType can be set only once during initialization. Note: If this property is set to true and any date filters with filter restriction interval were stored as part of a variant, the values of these filters cannot be applied. If this property is set to false, any previously stored filters which were treated as type DateTimeRange based on the former setting, cannot be converted back to the standard date interval.

getUseProvidedNavigationProperties

Gets current value of property useProvidedNavigationProperties.

If set to true, only the navigation properties mentioned in property sap.ui.comp.smartfilterbar.SmartFilterBar#getNavigationProperties are checked for further filters.

Default value is false.

indexOfControlConfiguration

Checks for the provided sap.ui.comp.smartfilterbar.ControlConfiguration in the aggregation controlConfiguration. and returns its index if found or -1 otherwise.

indexOfGroupConfiguration

Checks for the provided sap.ui.comp.smartfilterbar.GroupConfiguration in the aggregation groupConfiguration. and returns its index if found or -1 otherwise.

insertControlConfiguration

Inserts a controlConfiguration into the aggregation controlConfiguration.

insertGroupConfiguration

Inserts a groupConfiguration into the aggregation groupConfiguration.

isInitialised

Checks whether the control is initialised

isInUTCMode

Determines if the custom data 'dateFormatSettings' is set with UTC mode true

isPending

Checks the pending state of the FilterBar control

refreshFiltersCount

Recalculates the filters count and updates their number in the UI. The sap.ui.comp.filterbar.FilterBar#AssignedFiltersChanged event will be triggered.

removeAllControlConfiguration

Removes all the controls from the aggregation controlConfiguration.

Additionally, it unregisters them from the hosting UIArea.

removeAllGroupConfiguration

Removes all the controls from the aggregation groupConfiguration.

Additionally, it unregisters them from the hosting UIArea.

removeControlConfiguration

Removes a controlConfiguration from the aggregation controlConfiguration.

removeGroupConfiguration

Removes a groupConfiguration from the aggregation groupConfiguration.

resumeSelection

Resumes calls to the search method. If it was called during the suspension, the search will be triggered once regardless of how many times it was called during suspension.

resumeSetFilterData
search

Overwrites method from base class. Called when user clicks the search button of the FilterBar. The search is executed asynchronously per default, but can be forced to synchronously execution by providing the bSync set to true. Synchronous mode is only supported for non live mode scenarios. In the synchronous mode a mandatory check prior to the search execution is made.

setBasicSearchFieldName

Sets a new value for property basicSearchFieldName.

Name of the field that is the focus of the basic search.

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

setConsiderAnalyticalParameters

Sets a new value for property considerAnalyticalParameters.

Indicates if the analytical parameters (SelectionVariant) must be taken into consideration.

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

Default value is false.

setConsiderSelectionVariants

Sets a new value for property considerSelectionVariants.

Indicates if the annotation com.sap.vocabularies.UI.v1.SelectionVariant is taken into account.
Note: Only relevant for control level personalization.

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

Default value is false.

Since 1.87 Please use the <code>com.sap.vocabularies.UI.v1.SelectionPresentationVariant</code> annotation through the {@link sap.ui.comp.smartvariants.SmartVariantManagement#setEntitySet}
setCustomFilterData

Sets the _CUSTOM data in the filter data model. The filterChange event is not triggered.

setDefaultSelectionVariantName

Sets a new value for property defaultSelectionVariantName.

Determines one specific variant that is based on the com.sap.vocabularies.UI.v1.SelectionVariant annotation, which is then used as the default variant.
This property is only relevant in case considerSelectionVariants is set to true and will only be applied if there is no user-defined default variant specified.
Note: Only relevant for control level personalization.

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

Since 1.87 Please use the <code>com.sap.vocabularies.UI.v1.SelectionPresentationVariant</code> annotation through the {@link sap.ui.comp.smartvariants.SmartVariantManagement#setEntitySet}
setEnableBasicSearch

Sets a new value for property enableBasicSearch.

Enables the basic search field. The entered value can be accessed with sap.ui.comp.smartfilterbar.SmartFilterBar#getParameters. Note: When the SmartFilterBar control is used with a sap.ui.comp.smarttable.SmartTable control the parameters are handled automatically. Therefore, this must only be enabled for OData service entities that support basic search.

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

Default value is false.

setEntityType

Sets a new value for property entityType.

The OData entity type whose metadata is used to create the SmartFilterBar. Note: Changing this value after the SmartFilterBar is initialized (initialise event was fired) has no effect.

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

Since 1.40 Use <code>entitySet</code> property instead of this one, to enable V4 annotation support
setFilterData

Sets the data in the filter data model. The follow-on filterChange event is only triggered when none _CUSTOM data is set.

setFilterDataAsString

Sets the data in the filter data model as string.

setLiveMode

Sets a new value for property liveMode.

If set the search will be automatically triggered, when a filter value was set via the change event.
Note: The liveMode only operates on non-mobile scenarios.
Additionally, if liveMode is set, the following applies:

  • The error messagebox is not displayed, and the showMessages property is ignored.
  • The search is triggered after a variant has been selected.
  • Execute on Select for VariantManagement is not shown and not taken into account

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

Default value is false.

setNavigationProperties

Sets a new value for property navigationProperties.

This property is only evaluated if the property sap.ui.comp.smartfilterbar.SmartFilterBar#getUseProvidedNavigationProperties is set to true. It contains a comma-separated list of navigation property names which are checked for filters.

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

Default value is empty string.

setResourceUri

Uses the provided resource URI to fetch the OData metadata instead of using the default ODataModel (getModel()). You should only set this if you intend to get the metadata for the filter bar from elsewhere!

Since 1.29 Set an ODataModel as the main model on your control/view instead
setShowMessages

Sets a new value for property showMessages.

If set to true, any errors that occur during the search, are displayed in a message box in addition to the valueState with the error. Note: As of version 1.89, the default value has been changed from true to false.

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

Default value is false.

setSmartVariant

Sets the associated smartVariant.

setSuppressSelection

Sets a new value for property suppressSelection.

If set to true all search requests will be ignored. This functionality is only intended to be used internally to enable an optimal solution when the filter bar is controlled by the smart templates. NOTE: As long as this property is set to true, all search requests will be neglected.

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

Default value is false.

setUseDateRangeType

Sets a new value for property useDateRangeType.

If set to true all date fields with filter restriction interval will be treated as DateTimeRange filters. The useDateRangeType can be set only once during initialization. Note: If this property is set to true and any date filters with filter restriction interval were stored as part of a variant, the values of these filters cannot be applied. If this property is set to false, any previously stored filters which were treated as type DateTimeRange based on the former setting, cannot be converted back to the standard date interval.

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

setUseProvidedNavigationProperties

Sets a new value for property useProvidedNavigationProperties.

If set to true, only the navigation properties mentioned in property sap.ui.comp.smartfilterbar.SmartFilterBar#getNavigationProperties are checked for further filters.

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

Default value is false.

suspendSelection

Suspends calls to the search method when not called with the bSync parameter.

suspendSetFilterData
validateMandatoryFields

Verify if all mandatory filters or parameters have values.

verifySearchAllowed

Verifies if search is possible.

_attachValueListAnnotationLoaded

Param Type DefaultValue Description
oData object

An object that will be passed to the handler along with the event object when the event is fired

fnFunction function

The handler function to call when the event occurs.

oListener object

The object that wants to be notified when the event occurs

addControlConfiguration

Adds some controlConfiguration to the aggregation controlConfiguration.

Param Type DefaultValue Description
oControlConfiguration sap.ui.comp.smartfilterbar.ControlConfiguration

The controlConfiguration to add; if empty, nothing is inserted

addFieldToAdvancedArea

Searches for the filter field having the specified OData key and adds this filter field to the advanced area. If there is no corresponding field in the OData metadata, this method has no effect.

Param Type DefaultValue Description
sKey string

The key like specified in the OData metadata

addGroupConfiguration

Adds some groupConfiguration to the aggregation groupConfiguration.

Param Type DefaultValue Description
oGroupConfiguration sap.ui.comp.smartfilterbar.GroupConfiguration

The groupConfiguration to add; if empty, nothing is inserted

applyVariant

Applies the current variant as opposed to fetchVariant. The variant is retrieved via the flex layer.

Param Type DefaultValue Description
oVariant object

The variant that must be applied. oVariant must contain a valid JSON object.

attachPendingChange

Attaches event handler fnFunction to the pendingChange event of this sap.ui.comp.smartfilterbar.SmartFilterBar.

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.ui.comp.smartfilterbar.SmartFilterBar itself.

This event is fired after the pending state of the FilterBar control changes.

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.ui.comp.smartfilterbar.SmartFilterBar itself

destroyControlConfiguration

Destroys all the controlConfiguration in the aggregation controlConfiguration.

destroyGroupConfiguration

Destroys all the groupConfiguration in the aggregation groupConfiguration.

detachPendingChange

Detaches event handler fnFunction from the pendingChange event of this sap.ui.comp.smartfilterbar.SmartFilterBar.

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

ensureLoadedValueHelp

Ensures the associated ValueHelpProvider is loaded.

Param Type DefaultValue Description
sFieldName string

is the name of the property from the entity type which is associated with a Value Help.

sap.ui.comp.smartfilterbar.SmartFilterBar.extend

Creates a new subclass of class sap.ui.comp.smartfilterbar.SmartFilterBar 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.comp.filterbar.FilterBar.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

fetchVariant

Retrieves the currently visible filters and the values for storing them as variants. The result will be passed on as a JSON object to the callee smart variant control.

firePendingChange

Fires event pendingChange to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

getAnalyticBindingPath

Returns the binding paths for the parameters.

getBasicSearchControl

Returns an instance of the control for the basic search.

getBasicSearchFieldName

Gets current value of property basicSearchFieldName.

Name of the field that is the focus of the basic search.

getConsiderAnalyticalParameters

Gets current value of property considerAnalyticalParameters.

Indicates if the analytical parameters (SelectionVariant) must be taken into consideration.

Default value is false.

getConsiderSelectionVariants

Gets current value of property considerSelectionVariants.

Indicates if the annotation com.sap.vocabularies.UI.v1.SelectionVariant is taken into account.
Note: Only relevant for control level personalization.

Default value is false.

Since 1.87 Please use the <code>com.sap.vocabularies.UI.v1.SelectionPresentationVariant</code> annotation through the {@link sap.ui.comp.smartvariants.SmartVariantManagement#setEntitySet}

getControlByKey

Returns the control (if any) with the specified key (Property name in OData entity). Use just the property name as the key when getting a control from the basic area. Example: "CompanyCode" & Use "EntityName/GroupName.FieldName" format to get controls from groups. Example:"Account.CompanyCode"

Param Type DefaultValue Description
sKey string

The key as present in the OData property name/control configuration

getControlConfiguration

Gets content of aggregation controlConfiguration.

Using control configurations you can add additional configuration to filter fields, for example set custom labels, change the order of fields, or change the filter field control type. Note: Changing the values here after the SmartFilter is initialized (initialise event was fired) has no effect.

getCustomFilterData

Returns the _CUSTOM data currently set in the filter data model.

getDefaultSelectionVariantName

Gets current value of property defaultSelectionVariantName.

Determines one specific variant that is based on the com.sap.vocabularies.UI.v1.SelectionVariant annotation, which is then used as the default variant.
This property is only relevant in case considerSelectionVariants is set to true and will only be applied if there is no user-defined default variant specified.
Note: Only relevant for control level personalization.

Since 1.87 Please use the <code>com.sap.vocabularies.UI.v1.SelectionPresentationVariant</code> annotation through the {@link sap.ui.comp.smartvariants.SmartVariantManagement#setEntitySet}

getDescriptionForKeys

Reads the descriptions for given filters and value keys.

Param Type DefaultValue Description
aFiltersWithKeyValues array

List of filters with value keys to be retrieved

getEnableBasicSearch

Gets current value of property enableBasicSearch.

Enables the basic search field. The entered value can be accessed with sap.ui.comp.smartfilterbar.SmartFilterBar#getParameters. Note: When the SmartFilterBar control is used with a sap.ui.comp.smarttable.SmartTable control the parameters are handled automatically. Therefore, this must only be enabled for OData service entities that support basic search.

Default value is false.

getEntitySet

Gets current value of property entitySet.

The OData entity set whose metadata is used to create the SmartFilterBar. Note: Changing this value after the SmartFilterBar is initialized (initialise event was fired) has no effect.

getEntityType

Gets current value of property entityType.

The OData entity type whose metadata is used to create the SmartFilterBar. Note: Changing this value after the SmartFilterBar is initialized (initialise event was fired) has no effect.

Since 1.40 Use <code>entitySet</code> property instead of this one, to enable V4 annotation support

getFilterContextUrl

Get the filter context url.

getFilterData

Returns the data currently set in the filter data model.

Param Type DefaultValue Description
bAllFilterData boolean false

Also include empty/invisible fields filter data

getFilterDataAsString

Returns the data currently set in the filter data model as string.

Param Type DefaultValue Description
bAllFilterData boolean

Also include empty/invisible fields filter data

getFilters

Returns an array of filters (sap.ui.model.Filter instances), for visible fields, that can be used to restrict the query result from OData.
The result of this method can directly be used during aggregation binding or OData read.

Param Type DefaultValue Description
aFieldNames string[]

optional array of field names that filters should be returned, if not given all visible filters are returned

getFiltersWithValues

Returns all filter items

Even hidden filters will be considered as long as the mentioned criteria is fullfilled.

getGroupConfiguration

Gets content of aggregation groupConfiguration.

Provides the possibility to add additional configuration to groups. Groups are used to show fields in the advanced area of the SmartFilterBar. With additional configuration, you can for example set custom labels or change the order of groups. Note: Changing the values here after the SmartFilter is initialized (initialise event was fired) has no effect.

getLiveMode

Gets current value of property liveMode.

If set the search will be automatically triggered, when a filter value was set via the change event.
Note: The liveMode only operates on non-mobile scenarios.
Additionally, if liveMode is set, the following applies:

Default value is false.

sap.ui.comp.smartfilterbar.SmartFilterBar.getMetadata

Returns a metadata object for class sap.ui.comp.smartfilterbar.SmartFilterBar.

getModelData

Get the model data.

getNavigationProperties

Gets current value of property navigationProperties.

This property is only evaluated if the property sap.ui.comp.smartfilterbar.SmartFilterBar#getUseProvidedNavigationProperties is set to true. It contains a comma-separated list of navigation property names which are checked for filters.

Default value is empty string.

getParameterBindingPath

Returns the binding paths for the parameters. This API can be used for both analytical and non-analytical services. NoteFor analytical services, the API is NOT stable yet. Use at your own risk.

getParameterContextUrl

Get the parameter context url.

getParameters

Returns a parameter object that can be used to restrict the result of an OData service request if a basic search is performed. Example of a returned object:

{
	"custom": {
		"search-focus": "MySearchFocusFieldName",
		"search": "MySearchString"
	}
}

These parameters can be handed over as custom parameters, for example, to the sap.ui.model.odata.v2.ODataListBinding.

getResourceUri

Gets current value of property resourceUri.

Optional. The OData service URL. If it is not specified, the service URL from the OData model (this.getModel()) will be used. Note: Changing this value after the SmartFilterBar is initialized (initialise event was fired) has no effect.

Since 1.29 Set an ODataModel as the main model on your control/view instead

getShowMessages

Gets current value of property showMessages.

If set to true, any errors that occur during the search, are displayed in a message box in addition to the valueState with the error. Note: As of version 1.89, the default value has been changed from true to false.

Default value is false.

getSmartVariant

ID of the element which is the current target of the association smartVariant, or null.

getSuppressSelection

Gets current value of property suppressSelection.

If set to true all search requests will be ignored. This functionality is only intended to be used internally to enable an optimal solution when the filter bar is controlled by the smart templates. NOTE: As long as this property is set to true, all search requests will be neglected.

Default value is false.

getUseDateRangeType

Gets current value of property useDateRangeType.

If set to true all date fields with filter restriction interval will be treated as DateTimeRange filters. The useDateRangeType can be set only once during initialization. Note: If this property is set to true and any date filters with filter restriction interval were stored as part of a variant, the values of these filters cannot be applied. If this property is set to false, any previously stored filters which were treated as type DateTimeRange based on the former setting, cannot be converted back to the standard date interval.

getUseProvidedNavigationProperties

Gets current value of property useProvidedNavigationProperties.

If set to true, only the navigation properties mentioned in property sap.ui.comp.smartfilterbar.SmartFilterBar#getNavigationProperties are checked for further filters.

Default value is false.

indexOfControlConfiguration

Checks for the provided sap.ui.comp.smartfilterbar.ControlConfiguration in the aggregation controlConfiguration. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oControlConfiguration sap.ui.comp.smartfilterbar.ControlConfiguration

The controlConfiguration whose index is looked for

indexOfGroupConfiguration

Checks for the provided sap.ui.comp.smartfilterbar.GroupConfiguration in the aggregation groupConfiguration. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oGroupConfiguration sap.ui.comp.smartfilterbar.GroupConfiguration

The groupConfiguration whose index is looked for

insertControlConfiguration

Inserts a controlConfiguration into the aggregation controlConfiguration.

Param Type DefaultValue Description
oControlConfiguration sap.ui.comp.smartfilterbar.ControlConfiguration

The controlConfiguration to insert; if empty, nothing is inserted

iIndex int

The 0-based index the controlConfiguration should be inserted at; for a negative value of iIndex, the controlConfiguration is inserted at position 0; for a value greater than the current size of the aggregation, the controlConfiguration is inserted at the last position

insertGroupConfiguration

Inserts a groupConfiguration into the aggregation groupConfiguration.

Param Type DefaultValue Description
oGroupConfiguration sap.ui.comp.smartfilterbar.GroupConfiguration

The groupConfiguration to insert; if empty, nothing is inserted

iIndex int

The 0-based index the groupConfiguration should be inserted at; for a negative value of iIndex, the groupConfiguration is inserted at position 0; for a value greater than the current size of the aggregation, the groupConfiguration is inserted at the last position

isInitialised

Checks whether the control is initialised

isInUTCMode

Determines if the custom data 'dateFormatSettings' is set with UTC mode true

isPending

Checks the pending state of the FilterBar control

refreshFiltersCount

Recalculates the filters count and updates their number in the UI. The sap.ui.comp.filterbar.FilterBar#AssignedFiltersChanged event will be triggered.

removeAllControlConfiguration

Removes all the controls from the aggregation controlConfiguration.

Additionally, it unregisters them from the hosting UIArea.

removeAllGroupConfiguration

Removes all the controls from the aggregation groupConfiguration.

Additionally, it unregisters them from the hosting UIArea.

removeControlConfiguration

Removes a controlConfiguration from the aggregation controlConfiguration.

Param Type DefaultValue Description
vControlConfiguration int string sap.ui.comp.smartfilterbar.ControlConfiguration

The controlConfiguration to remove or its index or id

removeGroupConfiguration

Removes a groupConfiguration from the aggregation groupConfiguration.

Param Type DefaultValue Description
vGroupConfiguration int string sap.ui.comp.smartfilterbar.GroupConfiguration

The groupConfiguration to remove or its index or id

resumeSelection

Resumes calls to the search method. If it was called during the suspension, the search will be triggered once regardless of how many times it was called during suspension.

resumeSetFilterData

search

Overwrites method from base class. Called when user clicks the search button of the FilterBar. The search is executed asynchronously per default, but can be forced to synchronously execution by providing the bSync set to true. Synchronous mode is only supported for non live mode scenarios. In the synchronous mode a mandatory check prior to the search execution is made.

Param Type DefaultValue Description
bSync boolean false

Indicates if the search should be triggered synchronously

setBasicSearchFieldName

Sets a new value for property basicSearchFieldName.

Name of the field that is the focus of the basic search.

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

Param Type DefaultValue Description
sBasicSearchFieldName string

New value for property basicSearchFieldName

setConsiderAnalyticalParameters

Sets a new value for property considerAnalyticalParameters.

Indicates if the analytical parameters (SelectionVariant) must be taken into consideration.

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
bConsiderAnalyticalParameters boolean false

New value for property considerAnalyticalParameters

setConsiderSelectionVariants

Sets a new value for property considerSelectionVariants.

Indicates if the annotation com.sap.vocabularies.UI.v1.SelectionVariant is taken into account.
Note: Only relevant for control level personalization.

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

Default value is false.

Since 1.87 Please use the <code>com.sap.vocabularies.UI.v1.SelectionPresentationVariant</code> annotation through the {@link sap.ui.comp.smartvariants.SmartVariantManagement#setEntitySet}
Param Type DefaultValue Description
bConsiderSelectionVariants boolean false

New value for property considerSelectionVariants

setCustomFilterData

Sets the _CUSTOM data in the filter data model. The filterChange event is not triggered.

Param Type DefaultValue Description
oJson object

The JSON data in the filter bar

setDefaultSelectionVariantName

Sets a new value for property defaultSelectionVariantName.

Determines one specific variant that is based on the com.sap.vocabularies.UI.v1.SelectionVariant annotation, which is then used as the default variant.
This property is only relevant in case considerSelectionVariants is set to true and will only be applied if there is no user-defined default variant specified.
Note: Only relevant for control level personalization.

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

Since 1.87 Please use the <code>com.sap.vocabularies.UI.v1.SelectionPresentationVariant</code> annotation through the {@link sap.ui.comp.smartvariants.SmartVariantManagement#setEntitySet}
Param Type DefaultValue Description
sDefaultSelectionVariantName string

New value for property defaultSelectionVariantName

setEnableBasicSearch

Sets a new value for property enableBasicSearch.

Enables the basic search field. The entered value can be accessed with sap.ui.comp.smartfilterbar.SmartFilterBar#getParameters. Note: When the SmartFilterBar control is used with a sap.ui.comp.smarttable.SmartTable control the parameters are handled automatically. Therefore, this must only be enabled for OData service entities that support basic search.

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
bEnableBasicSearch boolean false

New value for property enableBasicSearch

setEntityType

Sets a new value for property entityType.

The OData entity type whose metadata is used to create the SmartFilterBar. Note: Changing this value after the SmartFilterBar is initialized (initialise event was fired) has no effect.

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

Since 1.40 Use <code>entitySet</code> property instead of this one, to enable V4 annotation support
Param Type DefaultValue Description
sEntityType string

New value for property entityType

setFilterData

Sets the data in the filter data model. The follow-on filterChange event is only triggered when none _CUSTOM data is set.

Param Type DefaultValue Description
oJson object

The JSON data in the filter bar

bReplace boolean

Replace existing filter data

setFilterDataAsString

Sets the data in the filter data model as string.

Param Type DefaultValue Description
sJson string

The JSON data in the filter bar

bReplace boolean

Replace existing filter data

setLiveMode

Sets a new value for property liveMode.

If set the search will be automatically triggered, when a filter value was set via the change event.
Note: The liveMode only operates on non-mobile scenarios.
Additionally, if liveMode is set, the following applies:

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
bLiveMode boolean false

New value for property liveMode

setNavigationProperties

Sets a new value for property navigationProperties.

This property is only evaluated if the property sap.ui.comp.smartfilterbar.SmartFilterBar#getUseProvidedNavigationProperties is set to true. It contains a comma-separated list of navigation property names which are checked for filters.

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

Default value is empty string.

Param Type DefaultValue Description
sNavigationProperties string ""

New value for property navigationProperties

setResourceUri

Uses the provided resource URI to fetch the OData metadata instead of using the default ODataModel (getModel()). You should only set this if you intend to get the metadata for the filter bar from elsewhere!

Since 1.29 Set an ODataModel as the main model on your control/view instead
Param Type DefaultValue Description
sResourceUri string

The URI of the oData service from which the metadata would be read

setShowMessages

Sets a new value for property showMessages.

If set to true, any errors that occur during the search, are displayed in a message box in addition to the valueState with the error. Note: As of version 1.89, the default value has been changed from true to false.

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
bShowMessages boolean false

New value for property showMessages

setSmartVariant

Sets the associated smartVariant.

Param Type DefaultValue Description
oSmartVariant sap.ui.core.ID sap.ui.comp.smartvariants.SmartVariantManagement

ID of an element which becomes the new target of this smartVariant association; alternatively, an element instance may be given

setSuppressSelection

Sets a new value for property suppressSelection.

If set to true all search requests will be ignored. This functionality is only intended to be used internally to enable an optimal solution when the filter bar is controlled by the smart templates. NOTE: As long as this property is set to true, all search requests will be neglected.

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
bSuppressSelection boolean false

New value for property suppressSelection

setUseDateRangeType

Sets a new value for property useDateRangeType.

If set to true all date fields with filter restriction interval will be treated as DateTimeRange filters. The useDateRangeType can be set only once during initialization. Note: If this property is set to true and any date filters with filter restriction interval were stored as part of a variant, the values of these filters cannot be applied. If this property is set to false, any previously stored filters which were treated as type DateTimeRange based on the former setting, cannot be converted back to the standard date interval.

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

Param Type DefaultValue Description
bUseDateRangeType boolean

New value for property useDateRangeType

setUseProvidedNavigationProperties

Sets a new value for property useProvidedNavigationProperties.

If set to true, only the navigation properties mentioned in property sap.ui.comp.smartfilterbar.SmartFilterBar#getNavigationProperties are checked for further filters.

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
bUseProvidedNavigationProperties boolean false

New value for property useProvidedNavigationProperties

suspendSelection

Suspends calls to the search method when not called with the bSync parameter.

suspendSetFilterData

validateMandatoryFields

Verify if all mandatory filters or parameters have values.

verifySearchAllowed

Verifies if search is possible.