Intro

Usage

Use a search field (sap.m.SearchField) if you want to enable users to enter text to search for information. The search field is also the control of choice for filtering down a given amount of information.

Responsiveness

When suggestions are turned on, the suggestion list displays differently depending on the device type.

Types

SAP Fiori comes with two different search types.

1. The manual search is triggered explicitly after the user enters text in the search field and clicks the Search button or presses the Enter key.
2. The live search (also known as “incremental search” or “search-as-you-type”) is triggered by each character that the user enters or deletes. There is a default delay of 400 ms before sending the search data to the back end. This ensures better performance and optimizes user experience.

Queries that are entered are used to search the back-end data for term matches (not case-sensitive). While a live search uses a “contains” approach, a manual search uses a “starts with” approach. “Contains” means that the result needs to match the query only partly to be a valid result. “Starts with” means that full terms of the result need to start with the entered query to be visualized.

Layout

The search input field (or search box) consists of two parts:

1. The text input, which is left-aligned. Initially, the field shows a placeholder (Search). As soon as the user enters a character, this prompt text disappears. It appears again if the user deletes the entry.
2. If a manual search is to be implemented, a search button with a magnifier icon is placed on the right side of this input control. The user clicks this button to trigger the search. In live searches, the magnifier icon is also placed here, but it functions more like an additional indicator to signify that this is a search input field. It also functions as an explicit search button if the user wants to search again for a query that has already been entered.

All item attributes defined by the app development team are searched. When the results are displayed, the items found do not necessarily have to show the attribute through which the item was found. The results are displayed in the same list that contained the original item set. Initial grouping and the order of the list are not affected by the search.

When the flexible column layout is used to show a list-detail relationship, the search field appears at the top of the list. In full screen mode, the search field is placed at the top of the page.

Properties

The following methods are important.

For the live search:

• attachLiveChange(oData ?, fnFunction, oListener ?) Attach event handler fnFunction to the liveChange event of this sap.m.SearchField.
• detachLiveChange(fnFunction, oListener) Detach event handler fnFunction from the liveChange event of this sap.m.SearchField.
• fireLiveChange(mArguments ?) Fire liveChange event to attached listeners.

For the manual search:

• attachSearch(oData ?, fnFunction, oListener ?) Attach event handler fnFunction to the search event of this sap.m.SearchField.
• detachSearch(fnFunction, oListener) Detach event handler fnFunction from the search event of this sap.m.SearchField.
• fireSearch(mArguments ?) Fire search event to attached listeners.

If a Refresh button is needed:

• getShowRefreshButton() Getter for property showRefreshButton.
• setShowRefreshButton(bShowRefreshButton) Setter for property showRefreshButton.

To show the Search button:

• getShowSearchButton() Getter for property showSearchButton.
• setShowSearchButton(bShowSearchButton) Setter for property showSearchButton.

To ensure the focus is set to input:

• setSelectOnFocus(bSelectOnFocus) Setter for property selectOnFocus.

If the search is triggered automatically when the value of the field is changed (unlike the liveChange event, the change event is not fired for each key press):

• attachChange(oData ?, fnFunction, oListener ?) Attach event handler fnFunction to the change event of this sap.m.SearchField.
• detachChange(fnFunction, oListener) Detach event handler fnFunction from the change event of this sap.m.SearchField.
• fireChange(mArguments ?) Fire change event to attached listeners.

Guidelines

• Implement the live search whenever possible.
• Use a manual search only if the amount of data is too large and if your app would otherwise run into performance issues.
• Show an appropriate prompt text:Search if queries are sent to all connected services, or Search In: if the search is limited to a certain source or providing service.

Resources