InstantSearch (v3) for iOS

This version of InstantSearch for iOS has been deprecated in favor of the latest version of InstantSearch for iOS.

SearchBox

This widget lets the user perform a text-based query.

Examples

1
2
3
4
var searchBox = SearchBarWidget(frame: CGRect)
// var searchBox = TextFieldWidget(frame: CGRect)
searchBox.index = "clothes"
self.view.addSubview(searchBox)

Parameters

index

The index name if you want the searchBox to search only in a single index. When empty, the searchBox searches through all registered indices.

1
searchBox.index = "myIndex"

variant

Lets you distinguish between two widgets that target the same index, but with different search parameters.

1
searchBox.variant = "myVariant"

SearchViewModel

ViewModels can be used to customize the rendering of the SearchBox without reimplementing any business logic.

• search(query:)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
@IBOutlet weak var searchBar: SearchBarWidget!
var searchViewModel: SearchViewModel!

override func viewDidLoad() {
        super.viewDidLoad()

        searchViewModel = SearchViewModel(view: searchBar)
        InstantSearch.shared.register(viewModel: searchViewModel)

        // Now can access access the searchBar's delegate
        searchBar.delegate = self
    }

    public func searchBar(_ searchBar: UISearchBar, textDidChange searchText: String) {
        // Call the search function of the viewModel. It takes care of changing the
        // search state and sending search events when new results arrive.
        searchViewModel.search(query: searchText)
    }

Hits

This widget displays a list of results.

Examples

1
2
3
4
5
6
  var tableView = HitsTableWidget(frame: CGRect.zero, style: .grouped)
  tableView.index = "someIndex"
  tableView.infiniteScrolling = false
  tableView.hitsPerPage = 5
  tableView.showItemsOnEmptyQuery = true
  tableView.remainingItemsBeforeLoading = 3

Parameters

index

The index name associated with the widget.

1
searchBox.index = "myIndex"

variant

Lets you distinguish between two widgets that target the same index, but with different search parameters.

1
hitsWidget.variant = "myVariant"

hitsPerPage

How many hits are requested and displayed for each search query.

1
hitsWidget.hitsPerPage = 20

infiniteScrolling

When false, disables the infinite scroll of the widget.

1
hitsWidget.infiniteScrolling = false

remainingItemsBeforeLoading

When the minimum number of remaining hits is reached, the next page is loaded. For example, if remainingItemsBeforeLoading is set to 10, the next page is loaded when there are less than 10 items below the current visible item.

1
hitsWidget.remainingItemsBeforeLoading = 10

showItemsOnEmptyQuery

If false, displays an empty hits widget when there is no query text entered by the user.

1
hitsWidget.showItemsOnEmptyQuery = true

Multi Hits

A widget that displays search results for multiple indices. Each index’s list of results appears in its own section.

Examples

1
2
3
4
var tableView = MultiHitsTableWidget(frame: CGRect.zero, style: .grouped)
tableView.indices = "index1,index2"
tableView.hitsPerSection = "5,3"
tableView.showItemsOnEmptyQuery = true

Parameters

indices

The indices associated with this hit. The values are comma-separated with no spaces in between.

1
multiHitsWidget.indices = "index1,index2,index3"

variants

Lets you distinguish between two widgets that target the same index, but with different search parameters. The variants are comma-separated with no space in between.

1
multiHitsWidget.variants = "variant1,variant2,vartiant3"

hitsPerSection

How many hits are requested and displayed for each index, comma-separated.

1
multiHitsWidget.hitsPerSection = "5,3,3"

showItemsOnEmptyQuery

When false, displays an empty hits widget when there is no query text entered by the user.

1
multiHitsWidget.showItemsOnEmptyQuery = true

RefinementList

A filtering widget made to display facets that lets the user refine their search results.

Examples

1
2
3
4
5
6
var tableView = RefinementTableWidget(frame: CGRect.zero, style: .grouped)
tableView.attribute = "brand"
tableView.operator = "or"
tableView.limit = 10
tableView.isRefined = true
tableView.sortBy = "count:desc"

Parameters

attribute

The faceted attribute used by the widget.

1
refinementWidget.attribute = "brand"

operator

Can either be 'or' or 'and'. Controls whether the results should match any selected value (if or is used) or all selected values (if and is used).

1
refinementWidget.operator = "or"

limit

The maximum amount of facet values to display. If there are more values, displays those with the biggest count.

1
refinementWidget.limit = 12

isRefined

Whether the refined values are displayed first or not.

1
refinementWidget.isRefined = true

sortBy

The sort order of the attributes. This attribute accepts the following values:

• count:asc to sort the facets by ascending count.
• count:desc to sort the facets by descending count.
• name:asc to sort the facet values by alphabetical order.
• name:desc to sort the facet values by reverse alphabetical order.

1
refinementWidget.sortBy = "count:desc"

Numeric Filters

Widget that handle numeric filters.

Examples

1
2
3
4
var slider = SliderWidget(frame: CGRect)
slider.attribute = "price"
slider.operator = ">"
slider.inclusive = true

Parameters

attribute

The numeric attribute used by the widget.

1
numericWidget.attribute = "price"

operator

The numeric operator to apply to the filter. Possible ones are \<, \<=, ==, !=, \>= and \>.

1
numericWidget.operator = ">"

inclusive

Whether the refinement is inclusive or exclusive.

1
numericWidget.inclusive = true

OneValueSwitchWidget

A widget that provides an on/off filtering feature based on an attribute value.

Examples

1
2
3
let oneValueSwitchWidget = OneValueSwitchWidget(frame: CGRect)
oneValueSwitchWidget.attribute = "shipping"
oneValueSwitchWidget.valueOn = "premium"

Parameters

attribute

The attribute used by the widget.

1
oneValueSwitchWidget.attribute = "shipping"

valueOn

The value when the toggle is on.

1
oneValueSwitchWidget.valueOn = "premium"

inclusive

Whether the refinement is inclusive or exclusive.

1
oneValueSwitchWidget.inclusive = true

Stats

Widget that displays the total number of matching hits and the time it took to get them.

Examples

1
2
3
var statsWidget = StatsLabelWidget(frame: CGRect)
statsWidget.resultTemplate = "{nbHits} results in {processingTimeMS}"
statsWidget.errorText = "Error while loading"

Parameters

resultTemplate

What the widget displays when a search request returns successfully. It takes the form of a templated string with the following variables to replace:

• {nbHits}: the hit count for the current query.
• {processingTimeMS}: the time the server took to process the request, in milliseconds.
• {hitsPerPage}: the maximum number of hits returned per page.
• {nbPages}: the number of pages corresponding to the number of hits.
• {page}: the index of the current page (zero-based).
• {query}: the query text.

1
statsWidget.resultTemplate = "{nbHits} results in {processingTimeMS}"

errorText

What the widget displays when a search query returns with an error.

1
statsWidget.errorText = "Error while loading"