THIS IS ARCHIVED DOCUMENTATION

(Deprecated) NumericFacet

The NumericFacet controller makes it possible to create a facet with numeric ranges.

Methods

deselectAll

Deselects all facet values.

isSortedBy

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

Parameters

  • criterion: 'ascending' | 'descending'

    The criterion to compare.

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

isValueSelected

Checks whether the specified facet value is selected.

Parameters

Returns boolean: Whether the specified facet value is selected.

sortBy

Sorts the facet values according to the specified criterion.

Parameters

  • criterion: 'ascending' | 'descending'

    The criterion to sort values by.

toggleSelect

Toggles the specified facet value.

Parameters

subscribe

Adds a callback that will be called on state change.

Parameters

  • listener: () ⇒ void

    A callback to be invoked on state change.

Returns Unsubscribe: An unsubscribe function to remove the listener.

Attributes

state

The state of the NumericFacet controller.

Properties

  • facetId: string

    The facet ID.

  • hasActiveValues: boolean

    true if there’s at least one non-idle value and false otherwise.

  • isLoading: boolean

    true if a search is in progress and false otherwise.

  • sortCriterion: 'ascending' | 'descending'

    The active sortCriterion of the facet.

  • values: NumericFacetValue[]

    The values of the facet.

Initialize

buildNumericFacet

Creates a NumericFacet controller instance.

Parameters

  • engine: Engine<NumericFacetSection & ConfigurationSection & SearchSection>

    The headless engine.

  • props: NumericFacetProps

    The configurable NumericFacet properties.

Returns NumericFacet

NumericFacetProps

The configurable NumericFacet properties.

Properties

NumericFacetOptions

The options for the NumericFacet controller.

Properties

  • currentValues?: NumericRangeRequest[]

    The values displayed by the facet in the search interface at the moment of the request.

    If generateAutomaticRanges is false, values must be specified. If generateAutomaticRanges is true, automatic ranges are going to be appended after the specified values.

  • facetId?: string

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

  • field: string

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

  • filterFacetCount?: boolean

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

  • generateAutomaticRanges: boolean

    Whether the index should automatically create range values.

    Tip: If you set this parameter to true, you should ensure that the 'Use cache for numeric queries' option is enabled for this facet’s field in your index in order to speed up automatic range evaluation.

  • injectionDepth?: number

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

    Note: A high injectionDepth may negatively impact the facet request performance.

  • numberOfValues?: number

    The number of values to request for this facet. Also determines the number of additional values to request each time this facet is expanded, and the number of values to display when this facet is collapsed.

  • sortCriteria?: 'ascending' | 'descending'

    The sort criterion to apply to the returned facet values.

Utils

buildNumericRange

Creates a NumericRangeRequest.

Parameters

Returns NumericRangeRequest: The options defining a value to display in a NumericFacet.

NumericFacetValue

Properties

  • end: number

    The ending value for the numeric range.

  • endInclusive: boolean

    Whether or not the end value is included in the range.

  • numberOfResults: number

    The number of results having the facet value.

  • start: number

    The starting value for the numeric range.

  • state: 'idle' | 'selected'

    The state of the facet value, indicating whether it is filtering results (selected) or not (idle).

NumericRangeOptions

Properties

  • end: number

    The end value of the range.

  • endInclusive?: boolean

    Whether to include the end value in the range.

  • start: number

    The start value of the range.

  • state?: 'idle' | 'selected'

    The current facet value state.

NumericRangeRequest

Properties

  • end: number

    The end value of the range.

  • endInclusive: boolean

    Whether to include the end value in the range.

  • start: number

    The start value of the range.

  • state: 'idle' | 'selected'

    The current facet value state.

Unsubscribe

Call signatures

  • (): void

Example Implementation

numeric-facet.fn.tsx

import {useEffect, useState, FunctionComponent} from 'react';
import {
  NumericFacet as HeadlessNumericFacet,
  NumericFacetValue,
} from '@coveo/headless';
 
interface NumericFacetProps {
  controller: HeadlessNumericFacet;
  format: (n: number) => string;
}
 
export const NumericFacet: FunctionComponent<NumericFacetProps> = (props) => {
  const {controller} = props;
  const [state, setState] = useState(controller.state);
 
  useEffect(() => controller.subscribe(() => setState(controller.state)), []);
 
  function getKeyForRange(value: NumericFacetValue) {
    return `[${value.start}..${value.end}${value.endInclusive ? ']' : '['}`;
  }
 
  if (!state.values.length) {
    return <div>No facet values</div>;
  }
 
  const {format} = props;
 
  return (
    <ul>
      {state.values.map((value) => (
        <li key={getKeyForRange(value)}>
          <input
            type="checkbox"
            checked={controller.isValueSelected(value)}
            onChange={() => controller.toggleSelect(value)}
            disabled={state.isLoading}
          />
          {format(value.start)} to {format(value.end)}{' '}
          {value.endInclusive ? 'inclusively' : 'exclusively'} (
          {value.numberOfResults}{' '}
          {value.numberOfResults === 1 ? 'result' : 'results'})
        </li>
      ))}
    </ul>
  );
};
 
// usage
 
/**
 * ```tsx
 * const [KB, MB, GB] = [1e3, 1e6, 1e9];
 *
 * const controller = buildNumericFacet(engine, {
 *   options: {
 *     field: 'size',
 *     generateAutomaticRanges: false,
 *     currentValues: [ // Must be specified when `generateAutomaticRanges` is false.
 *       buildNumericRange({start: 0, end: 5 * KB}),
 *       buildNumericRange({start: 5 * KB, end: 5 * MB}),
 *       buildNumericRange({start: 5 * MB, end: 5 * GB}),
 *     ],
 *   },
 * });
 *
 * <NumericFacet controller={controller} format={(bytes) => `${bytes} bytes`} />;
 * ```
 */