API Reference / InstantSearch iOS Widgets / Stats

About this widget

Each search results comes with a SearchStats structure containing metadata that you might display in your search experience. The following information is available within SearchStats:

  • hitsPerPage: Number of hits per page.
  • totalHitsCount: Total number of hits.
  • pagesCount: Total number of pages.
  • page: Current page.
  • processingTimeMS: Processing time of the request (in ms).
  • query: Query text that produced these results.

InstantSearch provides two types of StatsController:

  • LabelStatsController: presents metadata in UILabel in the form of text.
  • AttributedLabelStatsController: presents metadata in UILabel in the form of attributed text.

The format in which metadata appears in StatsController is defined in the presenter closure provided while connecting the controller with Interactor.

Examples

Instantiate a StatsConnector and launch an initial search on its Searcher.

1
2
3
4
5
6
7
8
9
10
let searcher: SingleIndexSearcher = .init(appID: "YourApplicationID",
                                          apiKey: "YourSearchOnlyAPIKey",
                                          indexName: "YourIndexName")
let labelStatsController: LabelStatsController = LabelStatsController(label: UILabel())

let statsConnector: StatsConnector = .init(searcher: searcher,
                                           controller: labelStatsController,
                                           presenter: DefaultPresenter.Stats.present)

searcher.search()

Parameters

searcher
type: SingleIndexSearcher
Required

The Searcher that handles your searches.

interactor
type: StatsInteractor
default: .init()
Required

The logic applied to Stats.

controller
type: ItemController
default: nil
Optional

The Controller interfacing with a concrete stats view.

presenter
type: Presenter<SearchStats?, Output>
default: nil
Optional

The Presenter defining how stats appear in the controller.

Low-level API

If you want to fully control the Stats components and connect them manually, you can use the following components:

  • Searcher: The Searcher that handles your searches.
  • StatsInteractor: The logic applied to the stats.
  • StatsController: The controller that interfaces with a concrete stats view.
1
2
3
4
5
6
7
8
9
let searcher: SingleIndexSearcher = .init(appID: "YourApplicationID",
                                          apiKey: "YourSearchOnlyAPIKey",
                                          indexName: "YourIndexName")
let labelStatsController: LabelStatsController = LabelStatsController(label: UILabel())
let statsInteractor: StatsInteractor = .init()
statsInteractor.connectSearcher(searcher)
statsInteractor.connectController(labelStatsController, presenter: DefaultPresenter.Stats.present)

searcher.search()

Customizing your view

The default controllers, e.g., the LabelStatsController, work well when you want to use native UIKit with their default behavior.

If you want to use another component (other than a UILabel) such as a UITextView, a 3rd party view, or want to introduce some custom behavior to the already provided UIKit component, you can create your own controller conforming to the StatsTextController protocol.

Protocol

func setItem(_ item: String?): Function called when new metadata are received.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
public class LabelStatsController: StatsTextController {

  public let label: UILabel

  public init (label: UILabel) {
    self.label = label
  }

  public func setItem(_ item: String?) {
    label.text = item
  }

}

SwiftUI

InstantSearch provides the StatsTextObservableController data model, which is an implementation of the StatsTextController protocol adapted for usage with SwiftUI. StatsTextObservableController must be connected to the StatsConnector or StatsConnector like any other StatsTextController implementation.

The example of the current filters view presenting the grouped filters.

1
2
3
4
5
6
7
8
9
struct ContentView: View {
  
  @ObservedObject var statsController: StatsTextObservableController
  
  var body: some View {
    Text(statsController.stats)
  }
  
}

If you prefer to create a custom textual stats SwiftUI view, you can directly use the StatsTextObservableController as a data model. It provides the stats property to streamline the design process of your custom SwiftUI view.

Did you find this page helpful?