Create your own InstantSearch Android widgets

Learn how you can create a custom widget for your InstantSearch Android app.

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.

1. 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
       }
   }
   
2. 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
   }
   
3. 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
   }
   
4. 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
       }
   }
   
5. 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)
       }
   }
   
6. 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()