CategoryFacet (Insight Engine)

This is for:

Developer

The CategoryFacet headless controller offers a high-level interface for designing a facet UI controller that renders values hierarchically.

Methods

deselectAll

Deselects all facet values.

disable

Disables the facet. I.e., prevents it from filtering results.

enable

Enables the facet. I.e., undoes the effects of disable.

isSortedBy

Checks whether the facet values are sorted according to the specified criterion.

Parameters

  • criterion: 'alphanumeric' | 'occurrences'

    The criterion to compare.

Returns boolean: Whether the facet values are sorted according to the specified criterion.

showLessValues

Sets the number of values displayed in the facet to the originally configured value.

showMoreValues

Increases the number of values displayed in the facet to the next multiple of the originally configured value.

sortBy

Sorts the facet values according to the specified criterion.

Parameters

  • criterion: 'alphanumeric' | 'occurrences'

    The criterion by which to sort values.

toggleSelect

Toggles the specified facet value.

Parameters

subscribe

Adds a callback that’s invoked on state change.

Parameters

  • listener: () => void

    A callback that’s invoked on state change.

Returns Unsubscribe: A function to remove the listener.

Attributes

facetSearch

Provides methods to search the facet’s values.

clear

Resets the query and empties the values.

Performs a facet search.

select

Selects a facet search result.

Parameters

showMoreResults

Shows more facet search results.

updateCaptions

Updates the facet value captions.

Parameters

  • captions: Record<string, string>

    A dictionary that maps index field values to facet value display names.

updateText

Updates the facet search query.

Parameters

  • text: string

    The facet search query.

state

The state of the Facet controller.

Properties

  • facetSearch: CategoryFacetSearchState

    The state of the facet’s searchbox.

  • activeValue: CategoryFacetValue | undefined

    The facet’s selected value if any, undefined otherwise.

  • canShowLessValues: boolean

    Returns true if fewer values can be displayed, and false if not.

  • canShowMoreValues: boolean

    Returns true if there are more values to display and, false if not.

  • enabled: boolean

    Whether the facet is enabled and its values are used to filter search results.

  • facetId: string

    The facet ID.

  • hasActiveValues: boolean

    Returns true if there’s at least one non-idle value, and false if not.

  • isHierarchical: boolean

    Whether valuesAsTree contains hierarchical values (i.e. facet values with children), or only 'flat' values (i.e. facet values without children).

  • isLoading: boolean

    Returns true if a search is in progress, and false if not.

  • parents: CategoryFacetValue[]

    The facet’s parent values.

  • selectedValueAncestry: CategoryFacetValue[]

    The selected facet values ancestry. The first element is the "root" of the selected value ancestry tree. The last element is the selected value itself.

  • sortCriteria: 'alphanumeric' | 'occurrences'

    The facet’s active sortCriterion.

  • values: CategoryFacetValue[]

    The facet’s values.

  • valuesAsTrees: CategoryFacetValue[]

    The root facet values. Child values might be available in valuesAsTrees[i].children[j]

Initialize

buildCategoryFacet

Creates an insight CategoryFacet controller instance.

Parameters

  • engine: InsightEngine

    The insight engine.

  • props: CategoryFacetProps

    The configurable CategoryFacet properties.

Returns CategoryFacet

CategoryFacetProps

The configurable CategoryFacet properties.

Properties

CategoryFacetOptions

The options for the CategoryFacet controller.

Properties

  • field: string

    The field whose values you want to display in the facet.

  • basePath?: string[]

    The base path shared by all values for the facet.

    Default: []

  • delimitingCharacter?: string

    The character that specifies the hierarchical dependency.

    Default: ;

  • facetId?: string

    A unique identifier for the controller. By default, a random unique ID is generated.

  • facetSearch?: CategoryFacetSearchOptions

    Facet search options.

  • filterByBasePath?: boolean

    Whether to filter the results using basePath.

    Default: true

  • filterFacetCount?: boolean

    Whether to exclude the parents of folded results when estimating the result count for each facet value.

    Default: true

  • injectionDepth?: number

    The maximum number of results to scan in the index to ensure that the facet lists all of the potential facet values.

    Note: A high injectionDepth may reduce facet request performance.

    Minimum: 0

    Default: 1000

  • numberOfValues?: number

    The number of values to request for this facet. This option also determines the number of additional values to request each time this facet is expanded, as well as the number of values to display when this facet is collapsed.

    Minimum: 1

    Default: 5

  • sortCriteria?: 'alphanumeric' | 'occurrences'

    The criterion to use for sorting returned facet values.

    Default: occurrences

CategoryFacetSearchOptions

Properties

  • captions?: Record<string, string>

    A dictionary that maps index field values to facet value display names.

  • numberOfValues?: number

    The maximum number of values to fetch.

    Default: 10

  • query?: string

    The string to match.

CategoryFacetSearchResult

Properties

  • count: number

    An estimate of the number of result items that match both the current query and the filter expression which would be generated if the facet value were selected.

  • displayValue: string

    The custom facet value display name, as specified in the captions argument of the facet request.

  • path: string[]

    The hierarchical path to the selected facet value.

  • rawValue: string

    The original facet value, as retrieved from the field in the index.

CategoryFacetSearchState

Properties

  • isLoading: boolean

    Returns true if the facet search is in progress, and false if not.

  • moreValuesAvailable: boolean

    Whether more values are available.

  • query: string

    The current query in the facet search box.

  • values: CategoryFacetSearchResult[]

    The facet search results.

CategoryFacetValue

Properties

  • children: CategoryFacetValue[]

    The children of this facet value.

  • isLeafValue: boolean

    When the hierarchical value has no children, this property is true.

  • moreValuesAvailable: boolean

    Whether more facet values are available.

  • numberOfResults: number

    The number of results that match the facet value.

  • path: string[]

    The hierarchical path to the facet value.

  • state: 'idle' | 'selected' | 'excluded'

    Whether a facet value is filtering results (selected) or not (idle).

  • value: string

    The facet value.

Unsubscribe

Call signatures

  • (): void;