Sort (Search Engine)

This is for:

Developer

The Sort controller manages how the results are sorted.

Methods

isSortedBy

Checks whether the specified sort criterion matches the value in state.

Parameters

  • criterion: SortByRelevancy | SortByQRE | SortByDate | SortByField | SortByNoSort

    The criterion to compare.

Returns boolean: true if the passed sort criterion matches the value in state, and false otherwise.

sortBy

Updates the sort criterion and executes a new search.

Parameters

  • criterion: SortByRelevancy | SortByQRE | SortByDate | SortByField | SortByNoSort

    The new sort criterion.

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

A scoped and simplified part of the headless state that is relevant to the Sort controller.

Properties

  • sortCriteria: string

    The current sort criteria.

Initialize

buildSort

Creates a Sort controller instance.

Parameters

  • engine: SearchEngine

    The headless engine.

  • props: SortProps

    The configurable Sort controller properties.

Returns Sort

SortProps

The configurable Sort controller properties.

Properties

  • initialState?: SortInitialState

    The initial state that should be applied to this Sort controller.

SortInitialState

The initial state that should be applied to this Sort controller.

Properties

  • criterion?: SortCriterion | SortCriterion[]

    The initial sort criterion to register in state.

Unsubscribe

Call signatures

  • (): void

Example Implementation

sort.fn.tsx

import {useEffect, useState, FunctionComponent} from 'react';
import {
  buildCriterionExpression,
  Sort as HeadlessSort,
  SortCriterion,
} from '@coveo/headless';
 
interface SortProps {
  controller: HeadlessSort;
  criteria: [string, SortCriterion][];
}
 
export const Sort: FunctionComponent<SortProps> = (props) => {
  const {controller} = props;
  const [state, setState] = useState(controller.state);
 
  useEffect(() => controller.subscribe(() => setState(controller.state)), []);
 
  const getCriterionFromName = (name: string) =>
    props.criteria.find(([criterionName]) => criterionName === name)!;
 
  const getCurrentCriterion = () =>
    props.criteria.find(
      ([, criterion]) =>
        state.sortCriteria === buildCriterionExpression(criterion)
    )!;
 
  return (
    <select
      value={getCurrentCriterion()[0]}
      onChange={(e) =>
        controller.sortBy(getCriterionFromName(e.target.value)[1])
      }
    >
      {props.criteria.map(([criterionName]) => (
        <option key={criterionName} value={criterionName}>
          {criterionName}
        </option>
      ))}
    </select>
  );
};
 
// usage
 
/**
 * ```tsx
 * const criteria: [string, SortCriterion][] = [
 *   ['Relevance', buildRelevanceSortCriterion()],
 *   ['Date (Ascending)', buildDateSortCriterion(SortOrder.Ascending)],
 *   ['Date (Descending)', buildDateSortCriterion(SortOrder.Descending)],
 *   ['Size (Ascending)', buildFieldSortCriterion('size', SortOrder.Ascending)],
 *   ['Size (Descending)', buildFieldSortCriterion('size', SortOrder.Descending)],
 * ];
 * const initialCriterion = criteria[0][1];
 * const controller = buildSort(engine, {
 *   initialState: {criterion: initialCriterion},
 * });
 *
 * <Sort controller={controller} criteria={criteria} />;
 * ```
 */