Tab (Search Engine)

This is for:

Developer

Example Implementation

tab.fn.tsx

import {Tab as HeadlessTab} from '@coveo/headless';
import {useEffect, useState, FunctionComponent, PropsWithChildren} from 'react';
 
interface TabProps extends PropsWithChildren {
  controller: HeadlessTab;
}
 
export const Tab: FunctionComponent<TabProps> = (props) => {
  const {controller} = props;
  const [state, setState] = useState(controller.state);
 
  useEffect(() => controller.subscribe(() => setState(controller.state)), []);
 
  return (
    <button disabled={state.isActive} onClick={() => controller.select()}>
      {props.children}
    </button>
  );
};
 
/* Usage
 
const messageExpression = buildQueryExpression()
  .addStringField({
    field: 'objecttype',
    operator: 'isExactly',
    values: ['Message'],
  })
  .toQuerySyntax();
 
const controller = buildTab(engine, {
  initialState: {isActive: true},
  options: {
    id: 'messages',
    expression: messageExpression,
  },
});
 
<Tab controller={controller}>Messages</Tab>;
*/

The Tab headless controller offers a high-level interface for designing a common tab UI controller.

Methods

select

Activates the tab.

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 Tab controller.

Properties

  • isActive: boolean

    Indicates whether the current tab is selected.

Initialize

buildTab

Creates a Tab controller instance.

Parameters

  • engine: SearchEngine

    The headless engine.

  • props: TabProps

    The configurable Tab properties.

Returns Tab

TabProps

The configurable Tab properties.

Properties

  • options: TabOptions

    The options for the Tab controller.

  • initialState?: TabInitialState

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

TabOptions

The options for the Tab controller.

Properties

  • expression: string

    A constant query expression or filter that the Tab should add to any outgoing query.

    Example:

    @objecttype==Message

  • id: string

    A unique identifier for the tab. The value will be used as the originLevel2 when the tab is active.

TabInitialState

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

Properties

  • isActive: boolean

    Specifies if the tab is currently selected. Note that there can be only one active tab for a given headless engine.

Utils

buildQueryExpression

Creates an QueryExpression instance.

Returns QueryExpression: A utility to help build query expressions.

DateFieldExpression

Properties

  • field: string

    The field name.

  • operator: NumericOperator

    The operator to use when comparing field and value. Options for the operator are: "isExactly" | "lowerThan" | "lowerThanOrEqual" | "greaterThan" | "greaterThanOrEqual".

  • value: string

    The value to match against the field. For absolute dates, please use form YYYY/MM/DD. For relative dates, please refer to the supported date/time operators.

  • negate?: boolean

    If true, the inverse expression will be created.

DateRangeFieldExpression

Properties

  • field: string

    The field name.

  • from: string

    The start of the range. For absolute dates, please use form YYYY/MM/DD. For relative dates, please refer to the supported date/time operators.

  • to: string

    The end of the range. For absolute dates, please use form YYYY/MM/DD. For relative dates, please refer to the supported date/time operators.

  • negate?: boolean

    If true, the inverse expression will be created.

ExactMatchExpression

Properties

  • expression: string

    An expression that must appear in its entirety at least once for an item to be returned.

    e.g. specifying Star Wars will only return items containing the exact phrase.

  • negate?: boolean

    If true, the inverse expression will be created.

FieldExistsExpression

Properties

  • field: string

    The field that should be defined on all matching items.

  • negate?: boolean

    If true, the inverse expression will be created.

KeywordExpression

Properties

  • expression: string

    An expression containing terms to match. Terms can be in any order, and may also be expanded with stemming.

    e.g. specifying Star Wars will return items containing either Star or Wars or both.

  • negate?: boolean

    If true, the inverse expression will be created.

NearExpression

Properties

  • otherTerms: OtherTerm[]

    The other terms to check against the reference term. See NEAR for an example.

  • startTerm: string

    The reference term.

  • negate?: boolean

    If true, the inverse expression will be created.

NumericFieldExpression

Properties

  • field: string

    The field name.

  • operator: NumericOperator

    The operator to use when comparing field and value.

  • value: number

    The value to match against the field.

  • negate?: boolean

    If true, the inverse expression will be created.

NumericRangeFieldExpression

Properties

  • field: string

    The field name.

  • from: number

    The start of the range.

  • to: number

    The end of the range.

  • negate?: boolean

    If true, the inverse expression will be created.

OtherTerm

Properties

  • endTerm: string

    The term to check against the reference term.

  • maxKeywordsBetween: number

    The maximum number of keywords that should exist between the current term and the reference term.

QueryExpression

Properties

  • addDateField: function

    Adds an expression that uses an operator to compare a date field to a value. Returns all of the items for which the expression evaluates to true.

    Parameters

  • addDateRangeField: function

    Adds an expression that returns all items for which the value of the date field is within the defined range.

    Parameters

  • addExactMatch: function

    Adds an expression that must appear in its entirety, at least once, for an item to be returned.

    Parameters

  • addExpression: function

    Adds a QueryExpression to the current instance.

    Parameters

  • addFieldExists: function

    Adds an expression returning all items where the defined field exists.

    Parameters

  • addKeyword: function

    Adds an expression containing terms to match. Terms can be in any order, and may also be expanded with stemming.

    Parameters

  • addNear: function

    Adds an expression that returns all of the items in which the specified startTerm appears no more than maxKeywordsBetween from the endTerm, for each element in otherTerms.

    Parameters

  • addNumericField: function

    Adds an expression that uses an operator to compare a numeric field to a value. Returns all of the items for which the expression evaluates to true.

    Parameters

  • addNumericRangeField: function

    Adds an expression that returns all items for which the value of the numeric field is within the defined range.

    Parameters

  • addQueryExtension: function

    Adds an expression that invokes a query extension.

    Parameters

  • addStringFacetField: function

    Adds an expression that uses an operator to compare a string facet field to a value. Returns all of the items for which the expression evaluates to true.

    Parameters

  • addStringField: function

    Adds an expression that uses an operator to compare a string field against certain values. Returns all of the items for which the expression evaluates to true.

    Parameters

  • joinUsing: function

    Allows specifying a boolean operator join expressions with. Possible values are and and or.

    Parameters

    • operator: BooleanOperator

      The boolean operator to join individual expressions with.

      Returns QueryExpression: The QueryExpression instance.

  • toQuerySyntax: function

    Joins all expressions using the configured boolean operator.

    Returns string: A string representation of the configured expressions.

QueryExtensionExpression

Properties

  • name: string

    The query extension name without the leading $ sign. See Standard Query Extensions for examples.

  • parameters: QueryExtensionParameters

    The query extension parameters where applicable.

StringFacetFieldExpression

Properties

  • field: string

    The field name.

  • operator: StringFacetFieldOperator

    The operator to use when comparing field and value.

  • value: string

    The value to match against the field.

  • negate?: boolean

    If true, the inverse expression will be created.

StringFieldExpression

Properties

  • field: string

    The field name.

  • operator: StringOperator

    The operator to use when comparing field and values.

  • values: string[]

    The values to match against the field.

  • negate?: boolean

    If true, the inverse expression will be created.

Unsubscribe

Call signatures

  • (): void;