Create your own InstantSearch Android widgets

If none of the existing widgets fit your use case, you can implement your own.

If you’re creating a custom InstantSearch widget because you didn’t find a built-in option for your use case, consider opening a feature request to describe what you’re trying to build.

Creating a widget takes three steps:

Create the MyWidgetViewModel, containing the business logic for your widget.
Create a MyWidgetView interface, describing the rendering of the widget data.
- Implement your view in a MyWidgetViewImpl that you’ll use.
Create the Connections between your ViewModel and the other components:
- Create a MyWidgetConnectionView to connect your ViewModel to its View.
- If it uses the Searcher, create a MyWidgetConnectionSearcher.
- If it uses the FilterState, create a MyWidgetConnectionFilterState.

Example

You’ll build a widget that displays the number of searches made since it was last clicked.

Create the view model

The ViewModel will be quite straightforward: it stores a sum that can be incremented or reseted to 0. It will use InstantSearch’s SubscriptionValue to allow subscribing to changes of the sum’s value.

Kotlin

class SumSearchesViewModel {

    val sum = SubscriptionValue(0)

    fun increment() {
        sum.value++
    }

    fun reset() {
        sum.value = 0
    }
}

Create the view interface

To interact with the data in our ViewModel, you need a view than can display a number, and handle clicks for resetting.

Kotlin

interface SumSearchesView {

    fun setSum(sum: Int) // will be called on new sum
    var onReset: Callback<Unit>? // will hold the callback to reset the sum
}

Implement the view

Implement a SumSearchesView: it should display the data received in setSum and trigger the onReset when clicked.

Kotlin

class SumSearchesViewImpl(val view: TextView) : SumSearchesView {

    init {
        view.setOnClickListener { onReset?.invoke(Unit) }
    }

    override fun setSum(sum: Int) {
        view.text = "$sum searches."
    }

    override var onReset: Callback<Unit>? = null
}

Create the connection view

To link the ViewModel and its View, define a connection to describe what should happen when connecting (subscribe to sum and set the reset callback) and when disconnecting (unsubscribe to sum and remove the callback).

Kotlin

data class SumSearchesConnectionView(
        private val viewModel: SumSearchesViewModel,
        private val view: SumSearchesView
) : ConnectionImpl() {

    private val updateViewSum: (Int) -> Unit = {
        view.setSum(it)
    }

    override fun connect() {
        super.connect()
        viewModel.sum.subscribePast(updateViewSum)
        view.onReset = { viewModel.reset() }
    }

    override fun disconnect() {
        super.disconnect()
        viewModel.sum.unsubscribe(updateViewSum)
        view.onReset = null
    }
}

Create the connection searcher

Because the widget needs to be aware of searches to count them, it needs to be connected to a Searcher.Subscribe to its response to call increment() on every new search response.

Kotlin

import com.algolia.client.model.search.SearchResponse

data class SumSearchesConnectionSearcher(
        private val viewModel: SumSearchesViewModel,
        private val searcher: HitsSearcher
) : ConnectionImpl() {

    private val updateSum: (SearchResponse?) -> Unit = {
        viewModel.increment()
    }

    override fun connect() {
        super.connect()
        searcher.response.subscribe(updateSum)
    }

    override fun disconnect() {
        super.disconnect()
        searcher.response.unsubscribe(updateSum)
    }
}

Create helper functions

To simplify usage of the widget, create two extension functions that connect the ViewModel to other components:

Kotlin

fun SumSearchesViewModel.connectView(
        view: SumSearchesView
): Connection {
    return SumSearchesConnectionView(this, view)
}

fun SumSearchesViewModel.connectSearcher(
        searcher: HitsSearcher
): Connection {
    return SumSearchesConnectionSearcher(this, searcher)
}

Final touches

You just created your first custom widget and you can now use it in your app like any other widget:

Kotlin

val searcher = HitsSearcher(
    applicationID = "YourApplicationID",
    apiKey = "YourSearchOnlyAPIKey",
    indexName = "YourIndexName"
) // Initialize your Searcher
val view = TextView(context) // Create or find the view you want to use

// Create a connectionHandler to hold all connections
val connection = ConnectionHandler()

// Create your ViewModel and View implementation
val viewModel = SumSearchesViewModel()
val sumView = SumSearchesViewImpl(view)

// Connect your ViewModel to start displaying the count of searches
connection += viewModel.connectSearcher(searcher)
connection += viewModel.connectView(sumView)

// When you want to disconnect everything and ensure no memory leak
// for example in your Activity's onDestroy()`
connection.disconnect()

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Create your own InstantSearch Android widgets

Example

Final touches

​Example

​Final touches

Example

Final touches