Implement tabs

This is for:

Developer
In this article

A search interface often includes a single-select widget that the end user can interact with to address different search needs. Selecting an item in this widget typically enforces a static filter expression on queries, but may also have other effects such as routing queries through a specific query pipeline, modifying the maximum age of cached query result sets, or toggling the visibility of certain elements in the search interface. This article provides guidelines for properly implementing tabs on your own, assuming that you can’t use the Coveo JavaScript Search Framework in your custom search integration with Coveo.

As a reference, you may want to look at the source code of the Tab component to see how it’s implemented in the Coveo JavaScript Search Framework.

Selecting a tab

When the end user selects a tab (e.g., by clicking the corresponding link/button):

  1. Prepare a new query. Ensure that:

    • The tab search request parameter is set to the name/identifier of the newly selected tab (e.g., BooksTab).

    • The cq search request parameter includes the static filter expression enforced by the newly selected tab, if any, and no longer contains the expression enforced by the previously selected tab, if applicable.

      Avoid including end-user input or dynamic content in the cq search request parameter. Otherwise, you risk filling the cache with useless data, which may adversely impact query performance.

    • Other search request parameters are set as required to further customize the behavior of the tab (e.g., enableDuplicateFiltering, maximumAge, pipeline, sortCriteria, etc.).

  2. Call the Search API to execute the query prepared in step 1 (see Perform a Query). When the Search API returns:

    1. Call the Usage Analytics Write API to log the corresponding Search event (see Log Search Events). In the request body:

      • Set the actionCause property to interfaceChange.
      • Include the following key-value pair in the customData property:
        • "interfaceChangeTo": <interfaceChangeTo>

        where:

        • <interfaceChangeTo> (string) is the name/identifier of the newly selected tab (e.g., BooksTab).
      • Set the originLevel2 property to the same value as the tab search request parameter (i.e., the name/identifier of the newly selected tab).
      • Set other required/optional properties as appropriate (queryText, language, originLevel1, etc.).
    2. Render the query results (see Implement a Result List - Rendering Query Results).
    3. Render facets if any (see Implement Facets - Requesting and Rendering Facets).
    4. Hide or show elements in the search interface as required by the newly selected tab, if applicable.

These guidelines suggest a rather simplistic tab implementation. In a search interface that relies on the Coveo JavaScript Search Framework, selecting a Tab component instance may also have the following effects:

Moreover, selecting a Coveo JavaScript Search Framework Tab component instance can optionally contribute a static filter expression to the advanced query expression (aq) rather than to the constant query expression (cq).

Regardless of its configuration, however, selecting a Tab component instance always sets the tab search request parameter to the name/identifier of the newly selected tab, and logs a Search event precisely as described in step 2.a.

Executing a query after the Books tab has been selected

POST https://myorganizationid9sd8df7s.org.coveo.com/rest/search/v2 HTTP/1.1
 
Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

Payload (excerpt)

{
  ...
  "cq": "@documenttype==Book",
  "groupBy": [
    ...
  ],
  "locale": "en-US",
  "q": "John Keats",
  "searchHub": "BookstoreSearch",
  "tab": "Books",
  ...
}

200 OK response body (excerpt)

{
  ...
  "duration": 145,
  "groupByResults": [
    ...
  ],
  "results": [
    ...
  ],
  "searchUid": "7bfc652a-9dea-4811-b3f9-6d24345c37ce"
}

Logging a Search event for the previous action

POST https://myorganizationid9sd8df7s.analytics.org.coveo.com/rest/ua/v15/analytics/search?visitor=28s6g49d-f81s-1435-2r5x153dle72 HTTP/1.1
 
Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

Payload (excerpt)

{
  ...
  "actionCause": "interfaceChange",
  "customData": {
    ...
    "interfaceChangeTo": "Books",
    ...
  },
  "language": "en",
  "originLevel1": "BookstoreSearch",
  "originLevel2": "Books",
  "queryText": "John Keats",
  "responseTime": 145,
  "searchQueryUid": "7bfc652a-9dea-4811-b3f9-6d24345c37ce",
  ...
}