Tab (Search Engine)

This is for:

Developer

In this article

Example implementation
Methods
Attributes
Initialize
Utils
Related types

Note

This component was introduced in version 1.41.7.

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.
clearFiltersOnTabChange?: boolean

Whether to clear the state when the active tab changes.

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

for example, 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.

for example, 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
- expression: DateFieldExpression
  
  A date field expression.
  
  Returns QueryExpression: The QueryExpression instance.
addDateRangeField: function

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

Parameters
- expression: DateRangeFieldExpression
  
  A numeric field expression.
  
  Returns QueryExpression: The QueryExpression instance.
addExactMatch: function

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

Parameters
- expression: ExactMatchExpression
  
  An exact match expression.
  
  Returns QueryExpression: The QueryExpression instance.
addExpression: function

Adds a QueryExpression to the current instance.

Parameters
- expression: QueryExpression
  
  The query expression instance to add.
  
  Returns QueryExpression: The QueryExpression instance.
addFieldExists: function

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

Parameters
- expression: FieldExistsExpression
  
  A field exists expressions.
  
  Returns QueryExpression: The QueryExpression instance.
addKeyword: function

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

Parameters
- expression: KeywordExpression
  
  A keyword expression.
  
  Returns QueryExpression: The QueryExpression instance.
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
- expression: NearExpression
  
  A near expression.
  
  Returns QueryExpression: The QueryExpression instance.
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
- expression: NumericFieldExpression
  
  A numeric field expression.
  
  Returns QueryExpression: The QueryExpression instance.
addNumericRangeField: function

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

Parameters
- expression: NumericRangeFieldExpression
  
  A numeric field expression.
  
  Returns QueryExpression: The QueryExpression instance.
addQueryExtension: function

Adds an expression that invokes a query extension.

Parameters
- expression: QueryExtensionExpression
  
  A query extension expression.
  
  Returns QueryExpression: The QueryExpression instance.
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
- expression: StringFacetFieldExpression
  
  A string facet field expression.
  
  Returns QueryExpression: The QueryExpression instance.
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
- expression: StringFieldExpression
  
  A string field expression.
  
  Returns QueryExpression: The QueryExpression instance.
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;