Dynamic facet list

Signature

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

Explore example code

Browse the example code on GitHub.

Requirements

Declare each facet attribute in attributesForFaceting. Configure the facet order in the Algolia dashboard or with renderingContent. Set the query’s facets property and include each facet attribute to retrieve.

Dynamic facet list requires InstantSearch Android v2.1.1 or later.

Example

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

Kotlin

class MyActivity : AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = "ALGOLIA_APPLICATION_ID",
        apiKey = "ALGOLIA_SEARCH_API_KEY",
        indexName = "INDEX_NAME"
    )
    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)
        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

SearcherIndex

required

The Searcher that runs searches.

FilterState

required

The FilterState that stores the current filters.

List<AttributedFacets>

default: []

The initial ordered facets.

SelectionsPerAttribute

default: []

Maps each facet attribute to its selected facet values.

Map<String, SelectionMode>

default: [:]

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

Map<String, FilterGroupDescriptor>

default: [:]

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

View

DynamicFacetListView

required

The view that renders the dynamic facet list.

Kotlin

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

Low-level API

Use the following components to connect the dynamic facet list:

Searcher: runs searches.
FilterState: stores the current filter state.
DynamicFacetsListViewModel: manages dynamic facet state and behavior.

Kotlin

class MyActivity : AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = "ALGOLIA_APPLICATION_ID",
        apiKey = "ALGOLIA_SEARCH_API_KEY",
        indexName = "INDEX_NAME"
    )
    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))
        )
        // Your implementation of `DynamicFacetListView`
        val dynamicFacetListView = DynamicFacetListAdapter(DynamicFacetListViewHolderImpl.Factory)
        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()
    }
}

Customize the view

The DynamicFacetListView interface displays the ordered facets and handles user interactions. Use this interface to provide a custom view:

Kotlin

// Implements DynamicFacetListView.
val myDynamicFacetListView = MyDynamicFacetListView() 
dynamicFacets.connectView(myDynamicFacetListView)

Android views

DynamicFacetListAdapter is a built-in implementation of DynamicFacetListView that extends ListAdapter. Pass a DynamicFacetListViewHolder.Factory implementation to the adapter:

Kotlin

// Implements DynamicFacetListViewHolder.Factory.
val factory = DynamicFacetListViewHolderImpl.Factory
val dynamicFacetListView = DynamicFacetListAdapter(factory)
dynamicFacets.connectView(dynamicFacetListView)

Compose UI

DynamicFacetListState implements DynamicFacetListView for Compose UI. Use its facetOrder and facetSelections properties and its toggle and isSelected functions to build a custom Compose UI.

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

​Example

​Parameters

​View

​Low-level API

​Customize the view

​Android views

​Compose UI

​Implementation example

About this widget

Requirements

Example

Parameters

View

Low-level API

Customize the view

Android views

Compose UI

Implementation example