Coveo JavaScript Search Framework - Reference Documentation

Index

Coveo components

Modules

Enumerations

Classes

Interfaces

Type aliases

Functions

Object literals

Type aliases

BaseFormTypes

The basic types of form available to build an advanced search section.

Context

Context: IStringMap<string | string[]>

IAnalyticsDocumentViewMeta

IAnalyticsDocumentViewMeta: object

The IAnalyticsDocumentViewMeta interface describes the expected metadata when logging a click event / item view.

See also the Analytics component, and more specifically its logClickEvent method.

Type declaration

  • author: string

    The author of the clicked item.

  • Optional documentTitle?: string

    The title of the clicked item.

  • Optional documentURL?: string

    The URL of the clicked item.

IQueryExpression

IQueryExpression: string

The IQueryExpression type is a string type dedicated to query expressions.

This type is used to build a specific option for query expressions.

ResponseFormat

ResponseFormat: "json" | "opensearch-atom" | "opensearch-rss" | "xlsx"

The format of a successful response.

ValidLayout

ValidLayout: "list" | "card" | "table"

The possible valid and supported layouts.

See the Result Layouts documentation.

ValidTooltipPlacement

ValidTooltipPlacement: "auto-start" | "auto" | "auto-end" | "top-start" | "top" | "top-end" | "right-start" | "right" | "right-end" | "bottom-end" | "bottom" | "bottom-start" | "left-end" | "left" | "left-start"

The allowed Quickview tooltipPlacement option values. The -start and -end variations indicate relative alignement. Horizontally (top, bottom), -start means left and -end means right. Vertically (left, right), -start means top and -end means bottom. No variation means center.

Functions

$$

addActionCauseToList

  • Adds a new analytics action cause to the ActionCauseList. Adding a new actionCause allows to specify a custom user-action when triggering a search event.

    Parameters

    Returns void

clearLocalData

  • clearLocalData(searchRoot?: HTMLElement): void
  • Removes all session information stored in the browser (e.g., analytics visitor cookies, action history, etc.)

    Parameters

    • Default value searchRoot: HTMLElement = document.querySelector(Component.computeSelectorForType(SearchInterface.ID)) as HTMLElement

      The element to scan for an Analytics component. This can be an element onto which a component instance is bound (e.g., document.querySelector(".CoveoAnalytics"), or an ancestor of such an element (e.g., document.getElementById("search").

    Returns void

configureResourceRoot

  • configureResourceRoot(path: string): void
  • Sets the path from where the chunks used for lazy loading will be loaded. In some cases, in IE11, we cannot automatically detect it, use this instead.

    Parameters

    • path: string

      This should be the path of the Coveo script. It should also have a trailing slash.

    Returns void

disableAnalytics

  • disableAnalytics(searchRoot?: HTMLElement): void
  • Disables an Analytics component and clears local data.

    availablesince

    October 2019 Release (v2.7219)

    Parameters

    • Default value searchRoot: HTMLElement = document.querySelector(Component.computeSelectorForType(SearchInterface.ID)) as HTMLElement

      The element to scan for an Analytics component. This can be an element onto which a component instance is bound (e.g., document.querySelector(".CoveoAnalytics"), or an ancestor of such an element (e.g., document.getElementById("search").

    Returns void

enableAnalytics

  • enableAnalytics(searchRoot?: HTMLElement): void
  • Re-enables an Analytics component if it was previously disabled.

    availablesince

    October 2019 Release (v2.7219)

    Parameters

    • Default value searchRoot: HTMLElement = document.querySelector(Component.computeSelectorForType(SearchInterface.ID)) as HTMLElement

      The element to scan for an Analytics component. This can be an element onto which a component instance is bound (e.g., document.querySelector(".CoveoAnalytics"), or an ancestor of such an element (e.g., document.getElementById("search").

    Returns void

executeQuery

  • Execute a standard query. Active component in the interface will react to events/ push data in the query / handle the query success or failure as needed.

    It triggers a standard query flow for which the standard component will perform their expected behavior.

    If you wish to only perform a query on the index to retrieve results (without the component reacting), look into SearchInterface instead.

    Calling this method is the same as calling QueryController.executeQuery.

    Parameters

    • element: HTMLElement

      The root of the interface to initialize.

    Returns Promise<IQueryResults>

get

  • get(element: HTMLElement, componentClass?: any, noThrow?: boolean): BaseComponent
  • Get the component bound on the given HTMLElement.

    Parameters

    • element: HTMLElement

      The HTMLElement for which to get the component instance.

    • Optional componentClass: any

      If multiple components are bound to a single HTMLElement, you need to specify which components you wish to get.

    • Optional noThrow: boolean

      By default, the GET method will throw if there is no component bound, or if there are multiple component and no componentClass is specified. This deletes the error if set to true.

    Returns BaseComponent

init

  • init(element: HTMLElement, options?: any): Promise<object>
  • Initialize the framework with a basic search interface. Calls Initialization.initSearchInterface.

    If using the jQuery extension, this is called using $('#root').coveo('init');.

    Parameters

    • element: HTMLElement

      The root of the interface to initialize.

    • Default value options: any = {}

      JSON options for the framework (e.g.: {Searchbox : {enableSearchAsYouType : true}}).

    Returns Promise<object>

    }

initRecommendation

  • initRecommendation(element: HTMLElement, mainSearchInterface?: HTMLElement, userContext?: object, options?: any): Promise<object>
  • Initialize the framework with a recommendation interface. Calls Initialization.initRecommendationInterface.

    If using the jQuery extension, this is called using $('#root').coveo('initRecommendation');.

    Parameters

    • element: HTMLElement

      The root of the interface to initialize.

    • Optional mainSearchInterface: HTMLElement

      The search interface to link with the recommendation interface (see Recommendation).

    • Optional userContext: object

      The user context to pass with the query generated in the recommendation interface (see Recommendation).

      • [name: string]: any
    • Default value options: any = {}

      JSON options for the framework (e.g.: {Searchbox : {enableSearchAsYouType: true}}).

    Returns Promise<object>

    }

initSearchbox

  • initSearchbox(element: HTMLElement, searchPageUri: string, options?: any): Promise<object>
  • Initialize the framework with a standalone search box. Calls {@link Initialize.initStandaloneSearchInterface}.

    If using the jQuery extension, this is called using $('#root').coveo('initSearchbox');.

    Parameters

    • element: HTMLElement

      The root of the interface to initialize.

    • searchPageUri: string

      The search page on which to redirect when there is a query.

    • Default value options: any = {}

      JSON options for the framework (e.g.: {Searchbox : {enableSearchAsYouType : true}}).

    Returns Promise<object>

    }

load

  • load<T>(id: string): Promise<T>
  • Asynchronously loads a module, or chunk.

    This is especially useful when you want to extend a base component, and make sure the lazy component loading process recognizes it (see Lazy Versus Eager Component Loading).

    Example:

    export function lazyCustomFacet() {
      return Coveo.load<Facet>('Facet').then((Facet) => {
        class CustomFacet extends Facet {
          [ ... ]
        };
        Coveo.Initialization.registerAutoCreateComponent(CustomFacet);
        return CustomFacet;
      });
    };
    
    Coveo.LazyInitialization.registerLazyComponent('CustomFacet', lazyCustomFacet);
    

    You can also use this function to assert a component is fully loaded in your page before executing any code relating to it.

    Example:

    You could do Coveo.load('Searchbox').then((Searchbox) => {}) to load the Searchbox component, if it is not already loaded in your search page.

    Type parameters

    • T

    Parameters

    • id: string

      The identifier of the module you wish to load. In the case of components, this identifier is the component name (e.g., Facet, Searchbox).

    Returns Promise<T>

    A Promise of the module, or chunk.

logClickEvent

  • Finds the Analytics component instance, and uses it to log a Click usage analytics event.

    A Click event corresponds to an item view (e.g., clicking on a ResultLink or opening a Quickview).

    Click events are immediately sent to the Coveo Usage Analytics service.

    Type parameters

    Parameters

    • element: HTMLElement

      The root of the search interface which contains the Analytics component.

    • clickEventCause: IAnalyticsActionCause

      The cause of the event.

    • metadata: TMeta

      The metadata you want to use to create custom dimensions. Metadata can contain as many key-value pairs as you need. Each key must contain only alphanumeric characters and underscores. The Coveo Usage Analytics service automatically converts white spaces to underscores, and uppercase characters to lowercase characters in key names. Each value must be a simple string. If you do not need to log metadata, you can simply pass an empty JSON ( {} ).

    • result: IQueryResult

      The result that was clicked.

    Returns void

logCustomEvent

  • Finds the Analytics component instance, and uses it to log a Custom usage analytics event.

    You can use Custom events to create custom reports, or to track events which are neither queries nor item views.

    Type parameters

    Parameters

    • element: HTMLElement

      The root of the search interface which contains the Analytics component.

    • customEventCause: IAnalyticsActionCause

      The cause of the event.

    • metadata: TMeta

      The metadata you want to use to create custom dimensions. Metadata can contain as many key-value pairs as you need. Each key must contain only alphanumeric characters and underscores. The Coveo Usage Analytics service automatically converts white spaces to underscores, and uppercase characters to lowercase characters in key names. Each value must be a simple string. If you do not need to log metadata, you can simply pass an empty JSON ( {} ).

    • Optional result: IQueryResult

      The query result that relates to the custom event, if applicable.

    Returns void

logSearchAsYouTypeEvent

  • logSearchAsYouTypeEvent<TMeta>(element: HTMLElement, searchAsYouTypeEventCause: IAnalyticsActionCause, metadata: TMeta): void
  • Finds the Analytics component instance, and uses it to log a SearchAsYouType usage analytics event.

    This function is very similar to the logSearchEvent function, except that logSearchAsYouTypeEvent should, by definition, be called more frequently. Consequently, in order to avoid logging every single partial query, the PendingSearchAsYouTypeEvent takes care of logging only the "relevant" last event: an event that occurs after 5 seconds have elapsed without any event being logged, or an event that occurs after another part of the interface triggers a search event.

    It is important to call this method before executing the query. Otherwise, no SearchAsYouType event will be logged, and you will get a warning message in the console. See Logging Your Own Search Events.

    Type parameters

    Parameters

    • element: HTMLElement

      The root of the search interface which contains the Analytics component.

    • searchAsYouTypeEventCause: IAnalyticsActionCause

      The cause of the event.

    • metadata: TMeta

      The metadata you want to use to create custom dimensions. Metadata can contain as many key-value pairs as you need. Each key must contain only alphanumeric characters and underscores. The Coveo Usage Analytics service automatically converts white spaces to underscores, and uppercase characters to lowercase characters in key names. Each value must be a simple string. If you do not need to log metadata, you can simply pass an empty JSON ( {} ).

    Returns void

logSearchEvent

  • Finds the Analytics component instance, and uses it to log a Search usage analytics event.

    A Search event is actually sent to the Coveo Usage Analytics service only after the query successfully returns (not immediately after calling this method). Therefore, it is important to call this method before executing the query. Otherwise, the Search event will not be logged, and you will get a warning message in the console. See Logging Your Own Search Events.

    Parameters

    • element: HTMLElement

      The root of the search interface which contains the Analytics component.

    • searchEventCause: IAnalyticsActionCause

      The cause of the event.

    • metadata: IStringMap<string>

      The metadata you want to use to create custom dimensions. Metadata can contain as many key-value pairs as you need. Each key must contain only alphanumeric characters and underscores. The Coveo Usage Analytics service automatically converts white spaces to underscores, and uppercase characters to lowercase characters in key names. Each value must be a simple string. If you do not need to log metadata, you can simply pass an empty JSON ( {} ).

    Returns void

options

  • options(element: HTMLElement, optionsToSet?: any): void
  • Pass options to the framework, before it is initialized (init).
    All the options passed with this calls will be merged together on initialization.

    Parameters

    • element: HTMLElement

      The root of the interface for which you wish to set options.

    • Default value optionsToSet: any = {}

      JSON options for the framework (e.g.: {Searchbox : {enableSearchAsYouType: true}}).

    Returns void

patch

  • patch(element: HTMLElement, methodName: string, handler: function): void
  • Patch the given methodName on an instance of a component bound to an HTMLElement with a new handler.

    Parameters

    • element: HTMLElement
    • methodName: string
    • handler: function
        • (...args: any[]): any
        • Parameters

          • Rest ...args: any[]

          Returns any

    Returns void

racePromises

  • racePromises<T>(promises: Thenable<T>[]): Promise<T>

removeActionCauseFromList

  • removeActionCauseFromList(actionCauseToRemoveName: string): void

state

  • state(element: HTMLElement, ...args: any[]): any
  • Performs read and write operations on the QueryStateModel instance of the search interface. See State.

    Can perform the following actions:

    • Get the QueryStateModel instance:

      Coveo.state(element);
      
    • Get the value of a single state attribute from the QueryStateModel instance:

      // You can replace `q` with any registered state attribute.
      Coveo.state(element, "q");
      
    • Set the value of a single state attribute in the QueryStateModel instance:

      // You can replace `q` with any registered state attribute.
      Coveo.state(element, "q", "my new value");
      
    • Set multiple state attribute values in the QueryStateModel instance:

      // You can replace `q` and `sort` with any registered state attributes.
      Coveo.state(element, {
        "q" : "my new value",
        "sort" : "relevancy"
      });
      

    Note:

    When setting one or several state attribute values with this function, you can pass an additional argument to set the silent attribute to true in order to prevent the state change from triggering state change events.

    Example:

    Coveo.state(element, "q", "my new value", { "silent" : true });
    

    Parameters

    • element: HTMLElement

      The root of the interface whose QueryStateModel instance the function should interact with.

    • Rest ...args: any[]

      The arguments that determine the action to perform on the QueryStateModel instance.

    Returns any

    Depends on the action performed.

Object literals

Const ResponsiveFacetOptions

ResponsiveFacetOptions: object

ResponsiveFacets options

dropdownHeaderLabel

dropdownHeaderLabel: string

If the [enableResponsiveMode]{@link Facet.options.enableResponsiveMode} option is true for all facets and {@link FacetSlider.options.enableResponsiveMode} is also true for all sliders, specifies the label of the dropdown button that allows to display the facets when in responsive mode.

If more than one Facet or FacetSlider component in the search interface specifies a value for this option, the framework uses the first occurrence of the option.

Default value is Filters.

enableResponsiveMode

enableResponsiveMode: boolean

Specifies whether to enable responsive mode for facets. Setting this options to false on any Facet, or FacetSlider component in a search interface disables responsive mode for all other facets in the search interface.

Responsive mode displays all facets under a single dropdown button whenever the width of the HTML element which the search interface is bound to reaches or falls behind a certain threshold (see SearchInterface.responsiveComponents).

See also the [dropdownHeaderLabel]{@link Facet.options.dropdownHeaderLabel} option.

Default value is true.