Dynamic Facets - Algolia

Signature

DynamicFacetListConnector(
    searcher: SearcherIndex,
    filterState: FilterState,
    orderedFacets: List<AttributedFacets>,
    selections: SelectionsPerAttribute,
    selectionModeForAttribute: Map<String, SelectionMode>,
    filterGroupForAttribute: Map<String, FilterGroupDescriptor>
)

Explore example code

Browse the Dynamic Facets example code on GitHub.

DynamicFacetsListView is a view that displays the ordered list of facets and facet values. The order of groups and facet values in each group is defined by the corresponding index settings and applied index rules. You can configure the facet merchandising through the corresponding index setting. To learn more, see Facet display.

Requirements

You must set the attributes for faceting and configure the facet order, either using the dashboard or with the API parameters attributesForFaceting and renderingContent. You must also set the facets property of the query with Searcher.indexQueryState.query.facets and provide the facet attributes you want to retrieve.

You must use InstantSearch Android v2.11 or later to use DynamicFacets.

Examples

Instantiate a DynamicFacetsListConnector, set the query facets and launch an initial search on its searcher.

Kotlin

class MyActivity : AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = "YourApplicationID",
        apiKey = "YourSearchOnlyAPIKey",
        indexName = "YourIndexName"
    )
    val filterState = FilterState()
    val color = "color"
    val country = "country"
    val brand = "brand"
    val size = "size"
    val dynamicFacets = DynamicFacetListConnector(
            searcher = searcher,
            filterState = filterState,
            selectionModeForAttribute = mapOf(
                    color to SelectionMode.Multiple,
                    country to SelectionMode.Multiple
            ),
            filterGroupForAttribute = mapOf(
                    brand to (brand to FilterOperator.Or),
                    color to (color to FilterOperator.Or),
            )
    )
    val connection = ConnectionHandler(dynamicFacets)

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val dynamicFacetListView = DynamicFacetListAdapter(DynamicFacetListViewHolderImpl.Factory) // implementation of `DynamicFacetListView`
        connection += dynamicFacets.connectView(dynamicFacetListView)
        searcher.query = searcher.query.copy(facets = listOf(brand, color, size, country))
        searcher.searchAsync()
    }

    override fun onDestroy() {
        super.onDestroy()
        searcher.cancel()
        connection.clear()
    }
}

Parameters

searcher

SearcherIndex

required

The Searcher that handles your searches.

filterState

FilterState

required

The FilterState that holds your filters.

orderedFacets

List<AttributedFacets>

default: []

The ordered list of attributed facets.

selections

SelectionsPerAttribute

default: []

The mapping between a facet attribute and a set of selected facet values.

selectionModeForAttribute

Map<String, SelectionMode>

default: [:]

The mapping between a facet attribute and a facet values selection mode. If not provided, the default selection mode is Single.

filterGroupForAttribute

Map<String, FilterGroupDescriptor>

default: [:]

The mapping between a facet attribute and a descriptor of a filter group where the corresponding facet filters are stored in the filter state.

View

view

DynamicFacetListView

required

The view that render the dynamic facets list.

Kotlin

val facetListAdapter = FacetListAdapter(FacetListViewHolderImpl.Factory)
val facetListPresenter = FacetListPresenterImpl(listOf(FacetSortCriterion.CountDescending, FacetSortCriterion.AlphabeticalAscending))
facetListCategory.connectView(facetListAdapter, facetListPresenter)

Low-level API

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

Searcher: the Searcher that handles your searches.
FilterState: the current state of the filters.
DynamicFacetsListViewModel: dynamic facets business logic

Kotlin

class MyActivity : AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = "YourApplicationID",
        apiKey = "YourSearchOnlyAPIKey",
        indexName = "YourIndexName"
    )
    val filterState = FilterState()
    val color = "color"
    val country = "country"
    val brand = "brand"
    val size = "size"
    val dynamicFacetViewModel = DynamicFacetListViewModel(
          selectionModeForAttribute = mapOf(
                  color to SelectionMode.Multiple,
                  country to SelectionMode.Multiple
          )
  )
    val connection = ConnectionHandler(dynamicFacets)

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        connection += dynamicFacetViewModel.connectSearcher(searcher)
        connection += dynamicFacetViewModel.connectFilterState(filterState, mapOf(
                brand to (brand to FilterOperator.Or),
                color to (color to FilterOperator.Or))
        )
        val dynamicFacetListView = DynamicFacetListAdapter(DynamicFacetListViewHolderImpl.Factory) // implementation of `DynamicFacetListView`
        connection += dynamicFacets.connectView(dynamicFacetListView)
        searcher.query = searcher.query.copy(facets = listOf(brand, color, size, country))
        searcher.searchAsync()
    }

    override fun onDestroy() {
        super.onDestroy()
        searcher.cancel()
        connection.clear()
    }
}

Customizing your view

InstantSearch Android provides DynamicFacetListView interface, it’s the view presenting the ordered list of facets and handling user interaction. You can provide your implementation of DynamicFacetListView interface:

Kotlin

val myDynamicFacetListView = MyDynamicFacetListView() // your implementation `DynamicFacetListView`
dynamicFacets.connectView(myDynamicFacetListView)

Android view

InstantSearch Android provides DynamicFacetListAdapter, an opinionated implementation of DynamicFacetListView interface and a subclass of ListAdapter class. Provide your implementation of DynamicFacetListViewHolder.Factory interface to your DynamicFacetListAdapter:

Kotlin

val factory = DynamicFacetListViewHolderImpl.Factory // your implementation of `DynamicFacetListViewHolder.Factory`
val dynamicFacetListView = DynamicFacetListAdapter(factory)
dynamicFacets.connectView(dynamicFacetListView)

Compose UI

InstantSearch Android provides the DynamicFacetListState, an implementation of the DynamicFacetListView interface adapted for usage with Compose UI. It provides facetOrder and facetSelections properties with convenient toggle and isSelected functions which let you implement your own Compose UI view.

Implementation example

Kotlin

import com.algolia.client.model.search.FacetHits

@Composable
fun DynamicFacetsList(modifier: Modifier = Modifier, dynamicFacetListState: DynamicFacetListState) {
    LazyColumn(modifier) {
        dynamicFacetListState.facetOrder.forEach { (attribute, facets) ->
            item {
                Header(attribute = attribute)
            }
            items(facets) { facet ->
                FacetRow(
                    modifier = Modifier.fillMaxWidth(),
                    facet = facet,
                    isSelected = dynamicFacetListState.isSelected(facet, attribute),
                    onClick = { dynamicFacetListState.toggle(facet, attribute) }
                )
            }
        }
    }
}

@Composable
fun Header(modifier: Modifier = Modifier, attribute: String) {
    Text(modifier = modifier.padding(horizontal = 16.dp, vertical = 8.dp), text = attribute)
}

@Composable
fun FacetRow(modifier: Modifier = Modifier, facet: FacetHits, isSelected: Boolean, onClick: () -> Unit = {}) {
    Card(modifier = modifier, onClick = onClick) {
        Row(Modifier.padding(horizontal = 16.dp, vertical = 8.dp)) {
            Text(modifier = Modifier.weight(1f), text = facet.value)
            if (isSelected) Icon(Icons.Default.Check, contentDescription = null)
            Text(text = facet.count.toString())
        }
    }
}

Explore example code

​About this widget

​Requirements

​Examples

​Parameters

​View

​Low-level API

​Customizing your view

​Android view

​Compose UI

​Implementation example

About this widget

Requirements

Examples

Parameters

View

Low-level API

Customizing your view

Android view

Compose UI

Implementation example