DateFacet (Product Listing Engine)

This is for:

Developer

Example Implementation

date-facet.fn.tsx

import {DateFacet as HeadlessDateFacet, DateFacetValue} from '@coveo/headless';
import {useEffect, useState, FunctionComponent} from 'react';
import {parseDate} from './date-utils';
 
interface DateFacetProps {
  controller: HeadlessDateFacet;
}
 
export const DateFacet: FunctionComponent<DateFacetProps> = (props) => {
  const {controller} = props;
  const [state, setState] = useState(controller.state);
 
  useEffect(() => controller.subscribe(() => setState(controller.state)), []);
 
  function getKeyForRange(value: DateFacetValue) {
    return `[${value.start}..${value.end}]`;
  }
 
  function format(dateStr: string) {
    return parseDate(dateStr).format('MMMM D YYYY');
  }
 
  if (
    !state.values.filter(
      (value) => value.state !== 'idle' || value.numberOfResults > 0
    ).length
  ) {
    return <div>No facet values</div>;
  }
 
  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.numberOfResults}{' '}
          {value.numberOfResults === 1 ? 'result' : 'results'})
        </li>
      ))}
    </ul>
  );
};
 
// usage
 
/**
 * ```tsx
 * const controller = buildDateFacet(engine, {
 *   options: {
 *     field: 'created',
 *     generateAutomaticRanges: false,
 *     currentValues: [ // Must be specified when `generateAutomaticRanges` is false.
 *       buildDateRange({
 *         start: new Date(2015, 1),
 *         end: new Date(2018, 1),
 *       }),
 *       buildDateRange({
 *         start: new Date(2018, 1),
 *         end: new Date(2020, 1),
 *       }),
 *       buildDateRange({
 *         start: new Date(2020, 1),
 *         end: new Date(2021, 1),
 *       }),
 *     ],
 *   },
 * });
 *
 * <DateFacet controller={controller} />;
 * ```
 */

relative-date-facet.fn.tsx

import {
  DateFacet,
  DateFacetValue,
  deserializeRelativeDate,
} from '@coveo/headless';
import {useEffect, useState, FunctionComponent} from 'react';
 
interface RelativeDateFacetProps {
  controller: DateFacet;
}
 
export const RelativeDateFacet: FunctionComponent<RelativeDateFacetProps> = (
  props
) => {
  const {controller} = props;
  const [state, setState] = useState(controller.state);
 
  useEffect(() => controller.subscribe(() => setState(controller.state)), []);
 
  function getKeyForRange(value: DateFacetValue) {
    return `[${value.start}..${value.end}]`;
  }
 
  function format(value: string) {
    const relativeDate = deserializeRelativeDate(value);
    return relativeDate.period === 'now'
      ? relativeDate.period
      : `${relativeDate.period} ${relativeDate.amount} ${relativeDate.unit}`;
  }
 
  if (
    !state.values.filter(
      (value) => value.state !== 'idle' || value.numberOfResults > 0
    ).length
  ) {
    return <div>No facet values</div>;
  }
 
  return (
    <ul>
      {state.values.map((value) => (
        <li key={getKeyForRange(value)}>
          <input
            type="checkbox"
            checked={controller.isValueSelected(value)}
            onChange={() => controller.toggleSingleSelect(value)}
            disabled={state.isLoading}
          />
          {format(value.start)} to {format(value.end)} ({value.numberOfResults}{' '}
          {value.numberOfResults === 1 ? 'result' : 'results'})
        </li>
      ))}
    </ul>
  );
};
 
// usage
 
/**
 * ```tsx
 * const controller = buildDateFacet(engine, {
 *   options: {
 *     field: 'created',
 *     generateAutomaticRanges: false,
 *     currentValues: [
 *       buildDateRange({
 *         start: {period: 'past', unit: 'day', amount: 1},
 *         end: {period: 'now'},
 *       }),
 *       buildDateRange({
 *         start: {period: 'past', unit: 'week', amount: 1},
 *         end: {period: 'now'},
 *       }),
 *     ],
 *   },
 * });
 *
 * <DateFacet controller={controller} />;
 * ```
 */

The DateFacet controller makes it possible to create a facet with date ranges.

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: RangeFacetSortCriterion

    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: RangeFacetSortCriterion

    The criterion by which to sort values.

toggleExclude

Toggles exclusion of the specified facet value

Parameters

toggleSelect

Toggles the specified facet value.

Parameters

toggleSingleExclude

Toggles exclusion of the specified facet value, deselecting others.

Parameters

toggleSingleSelect

Toggles the specified facet value, deselecting others.

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

state

The state of the DateFacet controller.

Properties

  • enabled: boolean

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

  • facetId: string

    The facet ID.

  • hasActiveValues: boolean

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

  • isLoading: boolean

    true if a search is in progress and false otherwise.

  • sortCriterion: RangeFacetSortCriterion

    The active sortCriterion of the facet.

  • values: DateFacetValue[]

    The values of the facet.

Initialize

buildDateFacet

Creates a DateFacet controller instance for the product listing.

Parameters

  • engine: ProductListingEngine

    The headless engine.

  • props: DateFacetProps

    The configurable DateFacet controller properties.

Returns DateFacet

DateFacetProps

The configurable DateFacet controller properties.

Properties

DateFacetOptions

The options for the DateFacet controller.

Properties

  • field: string

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

  • 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.

  • currentValues?: DateRangeRequest[]

    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.

    Default: []

  • facetId?: string

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

  • filterFacetCount?: boolean

    Whether to exclude folded result parents 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 potential facet values.

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

    Minimum: 0

    Default: 1000

  • 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.

    Minimum: 1

    Default: 8

  • rangeAlgorithm?: RangeFacetRangeAlgorithm

    The algorithm that’s used for generating the ranges of this facet when they aren’t manually defined. The default value of "even" generates equally sized facet ranges across all of the results. The value "equiprobable" generates facet ranges which vary in size but have a more balanced number of results within each range.

    Default: even

  • sortCriteria?: RangeFacetSortCriterion

    The sort criterion to apply to the returned facet values.

    Default: ascending

Utils

buildDateRange

Creates a DateRangeRequest.

Parameters

Returns DateRangeRequest: The options defining a value to display in a DateFacet.

DateFacetValue

Properties

  • end: string

    The ending value for the date range, formatted as YYYY/MM/DD@HH:mm:ss or the Relative date format "period-amount-unit"

  • endInclusive: boolean

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

  • numberOfResults: number

    The number of results that have the facet value.

  • start: string

    The starting value for the date range, formatted as YYYY/MM/DD@HH:mm:ss or the Relative date format "period-amount-unit"

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

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

DateRangeOptions

Properties

  • end: AbsoluteDate | RelativeDate

    The ending value for the date range. A date range can be either absolute or relative.

  • start: AbsoluteDate | RelativeDate

    The starting value for the date range. A date range can be either absolute or relative.

  • dateFormat?: string

    Allows specifying a custom string date format. See Day.js for possible parsing tokens. Assumes ISO 8601^ format by default.

  • endInclusive?: boolean

    Whether to include the end value in the range.

    Default: false

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

    The current facet value state.

    Default: idle

DateRangeRequest

Properties

  • end: string

    The ending value for the date range, formatted as YYYY/MM/DD@HH:mm:ss or the Relative Date format "period-amount-unit".

  • endInclusive: boolean

    Whether to include the end value in the range.

  • start: string

    The starting value for the date range, formatted as YYYY/MM/DD@HH:mm:ss or the Relative Date format "period-amount-unit".

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

    The current facet value state.

Unsubscribe

Call signatures

  • (): void;