UI libraries / InstantSearch iOS / Widgets

RelatedItems

About this widget

The RelatedItems components computes search parameters to fetch related items. You pass it a hit, which will be the reference in computing the search parameters and retrieving the related items.

To add RelatedItems to your search experience, use these components:

  • Searcher: A new Searcher that handles your searches for related items.
  • HitsInteractor: The hits interactor to display the related items.
  • HitsController: The controller that interfaces with a concrete hits view.

In a way, this component acts similarly to the Hits component, but it only modifies the results.

See code examples

Examples

Connect HitsInteractor and HitsController with each other using the provided connection method, and connect the HitsInteractor with Searcher. In this example, we use the HitsTableController provided by InstantSearch.

Now, each time you launch a new search:

  • Searcher receives new results and transmit them to HitsInteractor
  • HitsInteractor parses search results and notifies HitsController
  • HitsController refreshes the view presenting the hits
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

let searcher = HitsSearcher(appID: "YourApplicationID",
                            apiKey: "YourSearchOnlyAPIKey",
                            indexName: "YourIndexName")
let hitsInteractor: HitsInteractor<JSON> = .init()
let hitsTableViewController = CustomHitsTableViewController()
let matchingPatterns: [MatchingPattern<Product>] =
[
  MatchingPattern(attribute: "brand", score: 3, filterPath: \.brand),
  MatchingPattern(attribute: "categories", score: 2, filterPath: \.categories),
]

let hit: Hit<Product> = .init(objectID: "objectID123", object: product)

override func viewDidLoad() {
  super.viewDidLoad()
  setup()
}

func setup() {
  hitsInteractor.connectSearcher(searcher, withRelatedItemsTo: hit, with: matchingPatterns)
  hitsInteractor.connectController(hitsTableViewController)
  searcher.search()
}

Parameters

Parameter Description
hit
type: Hit<T>
Required

The reference hit to compute the search parameters to send to Algolia.

You can retrieve this hit from any location (app state, your backend, the history, etc.).
Copy 
1
2

let product = Product.init(name: "productName", brand: "Amazon", categories: ["Streaming Media Players", "TV & Home Theater"])
let hit: Hit<Product> = .init(objectID: "1234", object: product)
matchingPatterns
type: [MatchingPattern<T>]
Required

A schema that creates scored filters based on the hit’s attributes.

In the example below, the brand value gets a score of 1 while the category values gets a score of 2.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

struct Product: Codable {
    let name: String
    let brand: String
    let type: String
    let categories: [String]
    let image: URL
}

let matchingPatterns: [MatchingPattern<Product>] =
  [
    MatchingPattern(attribute: "brand", score: 1, filterPath: \.brand),
    MatchingPattern(attribute: "categories", score: 2, filterPath: \.categories)
  ]

The hit above would generate the following search parameters:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

{
  "sumOrFiltersScores": true,
  "facetFilters": ["objectID:-1234"],
  "optionalFilters": [
    ["brand:Amazon<score=1>"],
    [
      [
        "categories:TV & Home Theater<score=2>",
        "categories:Streaming Media Players<score=2>"
      ]
    ]
  ]
}

Customizing your view

Related items list appear in the controller implementing HitsController protocol. Read more about customizing Hits view in the HitsController documentation.

Did you find this page helpful?
InstantSearch iOS v7