Smart Filter Bar

The sap.ui.comp.smartfilterbar.SmartFilterBar control analyzes the $metadata document of an OData service and renders a FilterBar that can be used to filter a table.

The frequently asked questions section aims to answer the basic questions that may occur when using the SmartFilterBar control.

For more information about this control, see the API Reference in the Demo Kit and the sample in the Explored app in the Demo Kit.

For more information about annotations for this control, see the API Reference in the Demo Kit.

Overview

The SmartFilterBar control is a wrapper control that analyzes the $metadata document of an OData service. It renders a FilterBar control and provides integration with the VariantManagement control that is easy to configure.

$metadata is an XML-based document containing several annotations. These annotations are used to:

  • Determine the type of control (for example, whether a field is shown as MultiInput control or as DatePicker)
  • Enable the Suggest feature
  • Enable ValueHelpDialog
Details

In addition to the $metadata document, you can also have an additional configuration in the XML view. This additional configuration can be either sap.ui.comp.smartfilterbar.ControlConfiguration or sap.ui.comp.smartfilterbar.GroupConfiguration. Using this additional configuration, you can override certain settings from the OData metadata, such as labels, indexes, or the type of control. You can also add custom fields or custom groups to the filter bar that are not part of the OData $metadata document at all.

The FieldGroup annotation is used by the SmartFilterBar control to create a grouping of the fields. The grouping is shown in the filter dialog. Any label specified in this dialog is used to override the default label of the property. Only sap:filterable fields are enabled in the SmartFilterBar control by default (default is true when null).

Multi-value and unrestricted Date fields are supported if the annotation sap:filter-restriction="multi-value" is set for date properties.

For MultiInput filter fields, the MultiLine mode is active.

The SmartFilterBar control supports the Edm.Time OData type. The fields bound to OData properties of this type are represented by the sap.m.TimePicker control. The filter panel of the SmartFilterBar control containing the conditions allows filtering for time types using the TimePicker control.

FAQ

Question

TypeAhead is not working. When I start typing, no http requests are sent.

Answer

Take a look at the $metadata document and make sure there are ValueHelp annotations for this field. The Target attribute must look like this: {Namespace}.{EntityName}/{FieldName}.

Make sure that the namespace in the Target attribute is correct.

Example of a ValueHelp annotation:

#!xml
<Annotations Target="FAP_VENDOR_LINE_ITEMS_SRV.Item/Creditor" xmlns="http://docs.oasis-open.org/odata/ns/edm">
	<Annotation Term="com.sap.vocabularies.Common.v1.ValueList">
		<Record>
			<PropertyValue Property="CollectionPath" String="Vendors"/>
			<PropertyValue Property="SearchSupported" Bool="true"/>
			<PropertyValue Property="Parameters">
				<Collection>
					<Record Type="com.sap.vocabularies.Common.v1.ValueListParameterInOut">
						<PropertyValue Property="LocalDataProperty" PropertyPath="Creditor"/>
						<PropertyValue Property="ValueListProperty" String="VendorID"/>
					</Record>
				</Collection>
			</PropertyValue>
		</Record>
	</Annotation>
	</Annotations>

Question

I have a field Entered on that’s an Input field. It should be a DatePicker.

Answer

Take a look at the $metadata document and make sure that the property is of type Edm.DateTime and the property is annotated with sap:display-format="Date".

Question

I tried to set default values for a filter field in the control configuration in JavaScript. These default values don’t have any effect.

Answer

The ControlConfiguration and GroupConfiguration are intended to be used to add static configuration in an XML view.

There are three properties that can be set dynamically:

  • visible

  • label

  • visibleInAdvancedArea

All other properties and aggregations are not dynamic. This means they have to be set statically in the XML view, and not dynamically by JavaScript. Any changes made in the ControlConfiguration or GroupConfiguration after the initialise event has been fired do not have any effect.

If you have to set values of a filter field dynamically in JavaScript, you can use the setFilterData API.

Question

The value help dialog for a filter field contains a table with multiple columns. How can I change the order of these columns?

Answer

The order of the columns is specified in the OData $metadata document in the ValueHelp annotation.

There is one column for each ValueListParameterInOut or ValueListParameterOut in the related annotation.

The order of the columns is the same as the order of the InOut/Out parameters in the $metadata document. You can’t use configuration in the XML view to change this order. If you want to change the order, you can do it in the OData $metadata document.

Question

I have added custom controls to the SmartFilterBar. If I save a variant and load it again the custom fields are initial. What do I have to do to enable custom fields for variant management?

Answer

In general, custom fields cannot be handled automatically by the SmartFilterBar control. You have to implement this in the view’s controller. The SmartFilterBar offers two events that can be used to enable custom fields for variant management:

  • beforeVariantSave
  • afterVariantLoad

You can use the beforeVariantSave event to update the model of the SmartFilterBar with the values from the custom fields. Every value within the model is stored as a variant. The values of custom fields should be stored under the property _CUSTOM, for example, oSmartFilter.setFilterData({_ CUSTOM :{field1:"abc", field2:"123"}});

You can use the event afterVariantLoad to get the values from the model and use them to update the custom filter fields, for example: 

#!js
oData = oSmartFilter.getFilterData();
var oCustomFieldData = oData["_CUSTOM"];
oCustomField1.setValue(oCustomFieldData.field1);

If both events are handled this way, custom fields are enabled for variant management.

Question

How can I set initial or default data in the SmartFilterBar control?

Answer

Static data can be set in the control using ControlConfiguration in the view.xml:

#!xml
<smartFilterBar:SmartFilterBar id="smartFilterBar" ...>
… 
<smartFilterBar:controlConfiguration>
              <smartFilterBar:ControlConfiguration key="CompanyCode" visible="true" index="3"…>
                     <smartFilterBar:defaultFilterValues>
                            <smartFilterBar:SelectOption low="0001">
                            </smartFilterBar:SelectOption>
                     </smartFilterBar:defaultFilterValues>
              </smartFilterBar:ControlConfiguration>

Question

How can I set dynamic data as initial or default data in the SmartFilterBar control, for example, for navigation parameters?

Answer

Dynamic data can be set as initial or default data in the control by registering to the initialise event and setting JSON/JSONstring using the setFilterData API in your controller.js.

#!js
…
onInitSmartFilter: function(oEvent) { //Assuming that this is the eventhandler registered for the "initialise" event of the SmartFilterBar control in your view.xml
              var    oSmartFilter = oView.byId("smartFilterBar");
              var oTodaysDate = new Date();
              //Sample Data
              var oJSONData = {
                           Company: {
                                  items: [ //MultiInput fields with filter-restriction="multi-value" (Ex: shown as Tokens based on control type)
                                         {
                                            key:"0001",
                                            text:"SAP SE" //Display text on the token --> not used for filtering!
                                   },
                                   {
                                      key:"0002",
                                      text:"SAP XYZ"
                                  }
                                   ]
                           },                         
                           SomeDate: { //DateRange field with filter-restriction="interval"
                                  low: oTodaysDate, //Date fields require JavaScript Date objects!
                                  high: oTodaysDate
                           }, 
                           YearInterval: {
                                  low: "2000-2014" //simple input field with filter-restriction="interval" --> text separated by a single "-"
                           },
                           Ledger:"0L" //Single-value field --> Plain input
              };
              
              oSmartFilter.setFilterData(oJSONData); //Data will be updated with existing data in the SmartFilter
       },
…
Note You can use the setFilterData API to set data in the SmartFilterBar control.

Question

How does the SmartFilterBar determine if a filter has a value assigned to it?

Answer

The SmartFilterBar control handles the checks whether values are set for the OData-service-based filters, but has only a limited capability to do the same for custom fields. For checks like this, the custom field provider has to provide a Boolean value (true/false) as an indicator whether a value for the custom field exists via the custom data extension hasValue. If the custom data does not exist, the SmartFilterBar control analyzes if the custom control has either the method getValue or getSelectedKey and by using those tries to determine whether the value exists.

Note The method-based check is not very reliable, since, for example, MultiComboBox provides both methods mentioned, but the actual value is accessed via getSelectedKeys. It is strongly recommended to use the custom data extension for such scenarios. The SmartFilterBar control can only react to an onChange event. Therefore, the application has to set the hasValue custom data while handling the onChange event.