Dynamic facet list

Signature

DynamicFacetListConnector(
  searcher: Searcher,
  filterState: FilterState,
  orderedFacets: [AttributedFacets],
  selections: [Attribute: Set<String>],
  selectionModeForAttribute: [Attribute: SelectionMode],
  filterGroupForAttribute: [Attribute: FilterGroupDescriptor],
  controller: DynamicFacetListController
)

Explore example code

Browse the example code on GitHub.

Requirements

Declare each facet attribute in attributesForFaceting. Use the Algolia dashboard or the API. Configure the facet order with renderingContent.facetOrdering. Add each facet attribute to the query’s facets property with Searcher.request.query.facets.

Dynamic facet list requires InstantSearch iOS v7.12.0 or later.

Example

Create a DynamicFacetListConnector, set the query’s facets, and run the initial search.

Swift

let searcher = HitsSearcher(appID: "ALGOLIA_APPLICATION_ID",
                           apiKey: "ALGOLIA_SEARCH_API_KEY",
                           indexName: "INDEX_NAME")
searcher.request.query.facets = ["brand", "color", "size", "country"]

let filterState = FilterState()
let dynamicFacetListController = DynamicFacetListTableViewController()

let dynamicFacetlistConnector = DynamicFacetListConnector(searcher: searcher,
                                                          filterState: filterState,
                                                          selectionModeForAttribute: [
                                                            "color": .multiple,
                                                            "country": .multiple
                                                          ],
                                                          filterGroupForAttribute: [
                                                            "brand": ("brand", .or),
                                                            "color" : ("color", .or),
                                                          ],
                                                          controller: dynamicFacetListController)

searcher.connectFilterState(filterState)
searcher.search()

Parameters

Searcher

required

The Searcher that runs searches.

FilterState

required

The FilterState that stores the current filters.

[AttributedFacets]

default: []

The initial ordered facets.

[Attribute: Set<String>]

default: []

Maps each facet attribute to its selected facet values.

[Attribute: SelectionMode]

default: [:]

Maps each facet attribute to its facet-value selection mode. The default mode is .single.

[Attribute: FilterGroupDescriptor]

default: [:]

Maps each facet attribute to the filter group that stores its filters in the filter state.

DynamicFacetListController

The controller that displays the ordered facets and handles selections.

Low-level API

Use the following components to connect the dynamic facet list:

Searcher: runs searches.
FilterState: stores the current filter state.
DynamicFacetListInteractor: manages dynamic facet state and behavior.
DynamicFacetListController: displays the ordered facets and handles user interactions.

Swift

let searcher = HitsSearcher(appID: "ALGOLIA_APPLICATION_ID",
                            apiKey: "ALGOLIA_SEARCH_API_KEY",
                            indexName: "INDEX_NAME")
searcher.request.query.facets = ["brand", "color", "size", "country"]

let filterState = FilterState()
let dynamicFacetListController = DynamicFacetListTableViewController()

let dynamicFacetListInteractor = DynamicFacetListInteractor(selectionModeForAttribute: [
                                                              "color": .multiple,
                                                              "country": .multiple
                                                            ])

dynamicFacetListInteractor.connectSearcher(searcher)
dynamicFacetListInteractor.connectFilterState(filterState, filterGroupForAttribute: [
                                                             "brand": ("brand", .or),
                                                             "color" : ("color", .or),
                                                           ])
dynamicFacetListInteractor.connectController(dynamicFacetListController)

searcher.connectFilterState(filterState)
searcher.search()

Customize the view

Use a built-in controller or use DynamicFacetListController to customize how the dynamic facet list appears and handles user interactions.

UIKit

DynamicFacetListTableViewController is a built-in UITableViewController that conforms to the DynamicFacetListController protocol. To use a UICollectionView, a third-party view, or custom behavior, create a controller that conforms to DynamicFacetListController.

`DynamicFacetListController` protocol

Member	Description
`func setOrderedFacets(_ orderedFacets: [AttributedFacets])`	Updates the ordered facets.
`func setSelections(_ selections: [Attribute: Set<String>])`	Updates the selected facet values.
`var didSelect: ((Attribute, Facet) -> Void)?`	Runs when users select a facet.

SwiftUI

DynamicFacetListObservableController conforms to DynamicFacetListController for SwiftUI. Use its orderedFacets and selections properties and its toggle and isSelected methods to build a custom SwiftUI view.

Build a SwiftUI view

Swift

struct ContentView: View {

  @ObservedObject var dynamicFacetListController: DynamicFacetListObservableController

  var body: some View {
    ScrollView {
      ForEach(dynamicFacetListController.orderedFacets, id: \.attribute) { orderedFacet in
        VStack(spacing: 0) {
          // Facet header
          ZStack {
            Color(.systemGray5)
            Text(orderedFacet.attribute.rawValue)
              .fontWeight(.semibold)
              .frame(maxWidth: .infinity, alignment: .leading)
              .padding(.horizontal, 5)
          }
          // Facet values
          ForEach(orderedFacet.facets, id: \.value) { facet in
            VStack(spacing: 0) {
              FacetRow(facet: facet,
                      isSelected: dynamicFacetListController.isSelected(facet, for: orderedFacet.attribute))
                .onTapGesture {
                  dynamicFacetListController.toggle(facet, for: orderedFacet.attribute)
                }
                .frame(minHeight: 44, idealHeight: 44, maxHeight: .infinity, alignment: .center)
                .padding(.horizontal, 5)
            }
          }
        }
      }
    }
  }
}

Explore example code

​About this widget

​Requirements

​Example

​Parameters

​Low-level API

​Customize the view

​UIKit

​DynamicFacetListController protocol

​SwiftUI

​Build a SwiftUI view

About this widget

Requirements

Example

Parameters

Low-level API

Customize the view

UIKit

`DynamicFacetListController` protocol

SwiftUI

Build a SwiftUI view