Search results view | Search SDK | Android Docs

SearchResultsView - is a UI component that can display search results list. Technically, this is a subclass of the RecyclerView with predefined Adapter where items represent search states, for example, search result items that display details like name, address, distance to the place from user's location, and icon.

Integration

SearchResultsView inherits all the functionality from Android SDK RecyclerView, it can be added to your layout the way you would add any other UI element:


<com.mapbox.search.ui.view.SearchResultsView
    android:id="@+id/search_results_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="@drawable/card_background"
    android:clipToPadding="false"
    android:elevation="4dp"
    android:paddingTop="8dp"
    android:paddingBottom="22dp"
/>


val searchResultsView = findViewById<SearchResultsView>(R.id.search_results_view)

To make SearchResultsView work properly, you will have to call initialize() function where you will need to pass CommonSearchViewConfiguration object with DistanceUnitType, which tells the view how to display distances, in meters or miles:


searchResultsView.initialize(
    SearchResultsView.Configuration(
        CommonSearchViewConfiguration(DistanceUnitType.IMPERIAL)
    )
)

To fill the view with the items, you will need to call setAdapterItems() function where you will need to provider the list of SearchResultAdapterItem. SearchResultAdapterItem is an abstract class which provides a list of predefined subtypes that can be used as adapter items. The subtypes are:

These types should be combined together in the way that represent one of possible search states. Let's look at the code example. The following code snippet shows user's search history on the SearchResultsView:

Initially we show SearchResultAdapterItem.Loading item that indicates the progress of search history loading operation
Load search history items
If the loading operation completed successfully, we show loading items and Recent searches header
If the loading operation failed, we show error


fun showSearchHistory() {
    val historyDataProvider = ServiceProvider.INSTANCE.historyDataProvider()
    
    // Show `loading` item that indicates the progress of `search history` loading operation.
    searchResultsView.setAdapterItems(listOf(SearchResultAdapterItem.Loading))
    
    // Load `search history`
    loadingTask = historyDataProvider.getAll(object : CompletionCallback<List<HistoryRecord>> {
        override fun onComplete(result: List<HistoryRecord>) {
            val viewItems = mutableListOf<SearchResultAdapterItem>().apply {
                // Add `Recent searches` header
                add(SearchResultAdapterItem.RecentSearchesHeader)
                
                // Add history record items
                addAll(result.map { history ->
                    SearchResultAdapterItem.History(
                        history,
                        isFavorite = false
                    )
                })
            }

            // Show prepared items
            searchResultsView.setAdapterItems(viewItems)
        }

        override fun onError(e: Exception) {
            // Show error in case of failure
            val errorItem = SearchResultAdapterItem.Error(UiError.createFromException(e))
            searchResultsView.setAdapterItems(listOf(errorItem))
        }
    })
}

Each setAdapterItems() call replaces previous added items, so we don't need to explicitly remove loading item when we want to show search history elements.

Adapters

SearchResultsView is a flexible view which is not tied to concrete SDK. For example, you can use it to show search results from any source like Search Engine, Offline Search Engine, Address Autofill, etc.

Search UI provides ready-made adapters for the SearchResultsView that implement interactions with the core parts of SDK and provide simplified interface for users.

`SearchEngineUiAdapter`

SearchEngineUiAdapter is an adapter for the Search Engine and Offline Search Engine. SearchEngineUiAdapter implements logic that:

Shows search history when search query is empty
Shows search suggestions when a user types search query
Switches between online and offline search engines depending on device's connectivity

To integrate SearchEngineUiAdapter into your app, you will need to complete the following steps:

Instantiate the SearchEngineUiAdapter


val searchResultsView = findViewById<SearchResultsView>(R.id.search_results_view)
// searchResultsView initialization

val searchEngine = SearchEngine.createSearchEngineWithBuiltInDataProviders(
    SearchEngineSettings(getString(R.string.mapbox_access_token))
)

val offlineSearchEngine = OfflineSearchEngine.create(
    OfflineSearchEngineSettings(getString(R.string.mapbox_access_token))
)

val searchEngineUiAdapter = SearchEngineUiAdapter(
    view = searchResultsView,
    searchEngine = searchEngine,
    offlineSearchEngine = offlineSearchEngine,
)

Add SearchEngineUiAdapter.SearchListener to process user clicks and search events


searchEngineUiAdapter.addSearchListener(object : SearchEngineUiAdapter.SearchListener {
    // interface implementation
})

Call search() function when the query text is changed by the user


fun onQueryTextChange(newText: String) {
    searchEngineUiAdapter.search(newText)
}

That's it! These steps are enough to add search experience to your app. Explore all the SearchEngineUiAdapter's functionality in the SearchEngineUiAdapter API reference page.

Below you can find a complete sample that shows integration of the SearchEngineUiAdapter with Place card and Maps SDK.

EXAMPLE

Search Engine example

Search Engine example that utilizes the SearchResultsView UI component with SearchEngineUiAdapter.

`AddressAutofillUiAdapter`

AddressAutofillUiAdapter is an adapter for the Address Autofill SDK.

This integration is like the SearchEngineUiAdapter integration.

Instantiate the AddressAutofillUiAdapter


val searchResultsView = findViewById<SearchResultsView>(R.id.search_results_view)
// searchResultsView initialization

val addressAutofill = AddressAutofill.create(getString(R.string.mapbox_access_token))

val addressAutofillUiAdapter = AddressAutofillUiAdapter(
    view = searchResultsView,
    addressAutofill = addressAutofill
)

Add AddressAutofillUiAdapter.SearchListener to process user clicks and autofill events


addressAutofillUiAdapter.addSearchListener(object : AddressAutofillUiAdapter.SearchListener {
    // interface implementation
})

Call search() function when the query text is changed by the user. search() is a suspend function which should be called only from a coroutine or another suspend function. In this short example we will assume that we call it from Activity's lifecycleScope:


fun onQueryTextChange(newText: String) {
    val query = Query.create(newText)
    if (query != null) {
        lifecycleScope.launchWhenStarted {
            addressAutofillUiAdapter.search(query)
        }
    }
}