UI components

The TomTom SDKs provide UI elements to use with search in your application. To use them, add the SearchUI module to your application. SearchUI works with fuzzy search.

If you haven’t set up the project with the TomTom SDKs yet, read how to do it in the Project setup guide.

implementation("com.tomtom.sdk.search:ui:1.16.0")

The SearchUI module contains:

• SearchView: Input bar for the search phrase.
• SearchResultsView: View to attractively display search results.
• SearchSuggestionView: SearchSuggestion view.
• SearchFragment: Single fragment to bring SearchView, SearchResultsView and SearchSuggestionView functionality together.

Search view

The TomTom SDKs provide a predefined element for inserting a search query. It contains EditText to allow the user to enter text and a Clear Button for clearing entered text.

1. Add SearchView in your XML layout. CAUTION: Make sure you’re using SearchView from the TomTom SDKs rather than the Android one.
   Copy<com.tomtom.sdk.search.ui.SearchView android:id="@+id/search_view" android:layout_width="match_parent" android:layout_height="wrap_content" />

   1<com.tomtom.sdk.search.ui.SearchView
   2    android:id="@+id/search_view"
   3    android:layout_width="match_parent"
   4    android:layout_height="wrap_content" />

2. Get the instance of the SearchView in your Activity/Fragment class.
   Copyprivate val searchView: SearchView by lazy { findViewById(R.id.search_view) }

   private val searchView: SearchView by lazy { findViewById(R.id.search_view) }

3. Set the SearchViewListener to report on interactions with SearchView. SearchViewListener has 3 methods that are triggered when specific actions occur:
   • onSearchQueryCancel(): Called when the user taps the cancel button.
   • onSearchQueryChanged(String): Called whenever the query changes.
   • onCommandInsert(String): Reacts when the entered text is one of the commands provided in SearchProperties.

1searchView.searchViewListener =
2    object : SearchViewListener {
3        override fun onSearchQueryCancel() {
4            // YOUR CODE GOES HERE
5        }
6
7        override fun onSearchQueryChanged(input: String) {
8            // YOUR CODE GOES HERE
9        }
10
11        override fun onCommandInsert(command: String) {
12            // YOUR CODE GOES HERE
13        }
14    }

A query can also be set programmatically by calling SearchView.setQuery(String), which sets the text in the SearchView and triggers a search. In the same way, you can also clear the input using the SearchView.clear() method. The SearchView.hasInput() method checks if the search bar is not empty.

1searchView.setQuery("Amsterdam")
2searchView.clear()
3val isNotEmpty = searchView.hasInput()

Search results view

Once you have search results, the TomTom SDKs can help you show them to the user. Use SearchResultsView to present search results attractively. If an error occurred during the search request, SearchResultsView can also display that in a user-friendly way.

The first step is to add the SearchResultsView to your XML layout file.

1<com.tomtom.sdk.search.ui.SearchResultsView
2    android:id="@+id/search_results_view"
3    android:layout_width="wrap_content"
4    android:layout_height="wrap_content" />

Then get the instance of SearchResultsView in your Activity/Fragment class. Now SearchResultsView is ready to use.

To display search results, use the SearchResultsView.update(List<Place>, Boolean, String) method with the list of Place objects returned from the search, a boolean flag indicating whether the search query has finished (true by default), and an optional query to highlight matching results. The second argument, a boolean flag, indicates whether the search query has been completed. If false, the query is either ongoing or no query has been made yet. Calling SearchResultsView.update(List<Place>) or SearchResultsView.update(List<Place>, Boolean), without the last argument, disables highlighting. You can also use other searches (see Autocomplete and Fuzzy Search) and create a list of Place objects from their results.

searchResultsView.update(results, true, query)

Call SearchResults.displayError(String) to display an error message.

If you are using SearchView, you can call it with the SearchViewListener.onSearchError(Throwable) method.

searchResultsView.displayError(error.message!!)

Once the list of results is displayed, the user may want to select one for more information. Use SearchResultClickListener to be notified when the user taps on a search result. It provides the Place object of the result that the user selected.

1searchResultsView.searchResultClickListener =
2    SearchResultClickListener { placeDetails: PlaceDetails ->
3        // YOUR CODE GOES HERE
4    }

You can also clear all the results from the SearchResultsView in the code.

searchResultsView.clear()

Search suggestion view

TomTom’s Search Suggestion query can be used to create autocomplete functionality for the user. SearchSuggestionView suggests what the user may be searching for by processing their partial input. If the suggestion is correct, the user can tap on it to perform the search.

It wraps the query in an attractive container.

First add SearchSuggestionView to your XML layout.

1<com.tomtom.sdk.search.ui.SearchSuggestionView
2    android:id="@+id/search_suggestion_view"
3    android:layout_width="wrap_content"
4    android:layout_height="wrap_content" />

Then get the instance of the SearchSuggestionView in the Activity/Fragment class. Add the required parameters and set the SearchSuggestion to be displayed.

1searchSuggestionView.setSuggestion(
2    SearchSuggestion(
3        title = "TomTom",
4        subtitle = "Amsterdam",
5        query = "TomTom Amsterdam",
6        imageResId = R.drawable.ic_office,
7    ),
8)

The last step is to detect a user tap. To do so, set the SearchSuggestionClickListener. The listener provides the SearchSuggestion that was set to the SearchSuggestionView.

1searchSuggestionView.listener =
2    SearchSuggestionClickListener { suggestion: SearchSuggestion? ->
3        // YOUR CODE GOES HERE
4    }

Search fragment

The search fragment combines all of the views described above into a single fragment and adds search capabilities. If the search returns results, the SuggestionSearchView is hidden.

Start by adding the container for the SearchFragment to your layout file.

1<androidx.fragment.app.FragmentContainerView
2    android:id="@+id/search_fragment_container"
3    android:layout_width="match_parent"
4    android:layout_height="match_parent" />

Create a new instance of the SearchFragment. The SearchFragment.setSearchApi(SearchApi) method has to be called for it to be usable (preferably as part of onViewCreated() Android framework callback handler).

To do so you will need a SearchProperties object. The only required parameter is a TomTom API key that is valid for the Search API. See this link for how to get a TomTom API key.

You can configure the search by setting optional SearchApiProperties. The last parameter is the list of user commands that SearchView will recognize. When the user enters one of the commands listed, the SearchViewListener.onCommandInsert(String) method is triggered with the command as the parameter.

1val searchApiParameters =
2    SearchApiParameters(
3        limit = 5,
4        position = GeoPoint(52.377956, 4.897070),
5    )
6val searchProperties =
7    SearchProperties(
8        searchApiKey = "YOUR_TOMTOM_API_KEY",
9        searchApiParameters = searchApiParameters,
10        commands = listOf("TomTom"),
11    )

Then attach the new fragment to its parent using FragmentManager.

1val searchFragment = SearchFragment.newInstance(searchProperties)
2supportFragmentManager.beginTransaction()
3    .replace(R.id.search_fragment_container, searchFragment)
4    .commitNow()

SearchFragment is a user interface wrapper for Search. This means you have to set Search to the fragment.

searchFragment.setSearchApi(search)

By default, SearchFragment performs a search for the entered query in SearchView and displays the results in SearchResultsView.

To listen for events that occur during the process, set the SearchFragmentListener. This triggers the appropriate methods as in the separate views described above.

1val searchFragmentListener =
2    object : SearchFragmentListener {
3        override fun onSearchBackButtonClick() {
4            // YOUR CODE GOES HERE
5        }
6
7        override fun onSearchResultClick(placeDetails: PlaceDetails) {
8            // YOUR CODE GOES HERE
9        }
10
11        override fun onSearchError(throwable: Throwable) {
12            // YOUR CODE GOES HERE
13        }
14
15        override fun onSearchQueryChanged(input: String) {
16            // YOUR CODE GOES HERE
17        }
18
19        override fun onCommandInsert(command: String) {
20            // YOUR CODE GOES HERE
21        }
22    }
23searchFragment.setFragmentListener(searchFragmentListener)

Note that SearchFragment also adds a back arrow button. The SearchFragmentListener.onSearchBackButtonClick() method is triggered when the user taps on it. It can be removed.

searchFragment.enableSearchBackButton(false)

Next steps

Since you have learned how to use the search UI elements, here are recommendations for the next steps:

• Autocomplete and fuzzy search
• Map UI elements
• Styling the map