Interact with the framework and its components

This is for:

Developer

There are three distinct but equivalent ways to interact with the Coveo JavaScript Search Framework and its components.

Note

About lazy loading

Coveo JavaScript Search Framework v2.2900.23

As of its July 2017 release (v2.2900.23), the Coveo JavaScript Search Framework allows you to use lazy loading to asynchronously download only the minimal amount of code your search page requires, rather than using eager loading to sequentially download the entire framework, whether your search page needs the totality of this code or not.

When using lazy loading in your search page, wait for a component promise to resolve before interacting with it.

Example

Interacting with a lazy Tab component would look something like this:

Coveo.load('Tab').then(function(Tab) {
  // Interact with the Tab component.
});

For more information on how to interact with the Coveo JavaScript Search Framework using lazy loading, see Lazy versus eager component loading - Interacting with lazy components.

For the sake of simplicity, this page uses eager loading in its examples, which doesn’t require you to wait for component promises to resolve.

Using "pure" JavaScript

You can interact with the Coveo JavaScript Search Framework using standard JavaScript.

Getting a component instance

You can use standard JavaScript methods such as document.querySelector() to get the HTML element of a component you want to interact with.

The Coveo.get() method then allows you to get a reference to the corresponding component instance. You can call methods from this reference.

Example

Consider the following markup:

[ ... ]

<div class='coveo-facet-column'>

  [ ... ]

  <div class='CoveoFacet' data-field='@author'></div>

  [ ... ]

</div>
[ ... ]

Running the following code sample will select the Facet component instance with the field option set to @author and collapse it (see Facet.collapse()).

var myFacetElement = document.querySelector('.CoveoFacet[data-field="@author"]');
var myFacetInstance = Coveo.get(myFacetElement);
myFacetInstance.collapse();

Calling a top-level function

Top-level functions are functions you can call directly from the Coveo namespace (for example, Coveo.executeQuery(), Coveo.state(), etc.). These functions usually require the root element of your search interface as an argument.

In most scenarios, this root element of your search interface has the search id.

Example

Consider the following markup:

[ ... ]

<body id='search' class='CoveoSearchInterface'>

[ ... ]

</body>

Running the following code sample will execute a query (see Coveo.executeQuery()).

var mySearchInterfaceRootElement = document.querySelector('#search');
Coveo.executeQuery(mySearchInterfaceRootElement);

Binding an event handler

You can use the standard JavaScript EventTarget.addEventListener() method to bind event handlers. Most of the time, the event target should be the root element of your search interface.

Important

A native event handler receives the event argument in the detail property of the CustomEvent instead of a second argument, as is the case when binding event handlers using either Coveo.$$ or jQuery.
Example

The script part of the following code sample binds an event handler to the root element of the search interface on the buildingQuery event to add foobar to the current query expression.

<head>

  [ ... ]

  <script>
    document.addEventListener('DOMContentLoaded', function () {
      Coveo.SearchEndpoint.configureSampleEndpoint();

      var root = document.querySelector('#search');
      root.addEventListener('buildingQuery', function(e) {
        e.detail.queryBuilder.expression.add('foobar');
      });
      Coveo.init(root);
    })
  </script>

  [ ... ]

</head>

<body id='search' class='CoveoSearchInterface'>

  [ ... ]

</body>

Using Dom helper class (Coveo.$$)

You can use the Coveo.$$ function, which wraps the Dom class to interact with the Coveo JavaScript Search Framework and its components. The Dom class implements a small subset of jQuery functionalities that the Coveo JavaScript Search Framework requires (append, find, on, etc.).

Note

The Dom class was introduced to minimize the risk of having jQuery conflicts when integrating the Coveo JavaScript Search Framework in various systems.

Internally, the Coveo JavaScript Search Framework doesn’t use jQuery at all; it always uses the Dom class.

Getting a component instance

You can use the Dom.find() method to get the HTML element of a component you want to interact with. The Coveo.get() method then allows you to get a reference to the corresponding component instance. You can call methods from this reference.

Example

Consider the following markup:

[ ... ]

<div class='coveo-tab-section'>

[ ... ]

  <div class='CoveoTab' data-id='All'></div>

[ ... ]

</div>

[ ... ]

Running the following code sample selects the Tab component instance whose id option is All and selects it (seeTab.select()).

var myTabElement = Coveo.$$(document).find('.CoveoTab[data-id="All"]');
var myTabInstance = Coveo.get(myTabElement);
myTabInstance.select();

Calling a top-level function

Top-level functions are functions you can call directly from the Coveo namespace (for example, Coveo.executeQuery(), Coveo.state(), etc.). These functions usually require the root element of your search interface as an argument.

In most scenarios, this root element of your search interface has the search id.

To get this element with Coveo.$$, use the Dom.find() method.

Example

Consider the following markup:

[ ... ]

<body id='search' class='CoveoSearchInterface'>

[ ... ]

</body>

Running the following code sample sets the current sort criteria of the QueryStateModel to date ascending (see Coveo.state()).

var mySearchInterfaceRootElement = Coveo.$$(document).find('#search');
Coveo.state(mySearchInterfaceRootElement, 'sort', 'date ascending');

Binding an event handler

You can use the Dom.on() method to bind event handlers. Most of the time, the event target should be the root element of your search interface.

Example

The script part of the following code sample binds an event handler to the root element of the search interface on the buildingQuery event to add foobar to the current query expression.

<head>

  [ ... ]

  <script>
    document.addEventListener('DOMContentLoaded', function () {
      Coveo.SearchEndpoint.configureSampleEndpoint();

      var root = Coveo.$$(document).find('#search');
      Coveo.$$(root).on('buildingQuery', function(e, args) {
        args.queryBuilder.expression.add('foobar');
      });
      Coveo.init(root);
    })
  </script>

  [ ... ]

</head>

<body id='search' class='CoveoSearchInterface'>

  [ ... ]

</body>

Using the jQuery extension

You can use the jQuery extension to call any of the Coveo JavaScript Search Framework top-level functions and component methods (see jQuery).

If you’re unfamiliar with jQuery, you’re encouraged to use another method instead.

Note

Initially, the Coveo JavaScript Search Framework was designed primarily as a jQuery extension. Over time, however, the Dom class was introduced to eliminate the need for this dependency.

Therefore, the jQuery extension is no longer considered "core" to the Coveo JavaScript Search Framework. This implies that you have to manually add a reference to the jQuery library to use the jQuery extension.

Example

You could include an online reference to the jQuery library.

<head>

  [ ... ]

  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>

  [ ... ]

</head>
Important

Some Coveo implementations such as Coveo for Salesforce and Coveo for Sitecore currently include their own references the jQuery library. Therefore, the jQuery extension should work out of the box with these products and you normally don’t need to add a new reference to the jQuery library to use it (see Coveo for Salesforce V2 and Coveo for Sitecore 4 Release Home).

Getting a component instance

You can call the Coveo.get() top-level function with the jQuery extension to get a component instance.

Example

Consider the following markup:

[ ... ]

<div class='coveo-search-section'>

  [ ... ]

  <div class='CoveoSettings'></div>

  [ ... ]

[ ... ]

Running the following code sample puts a reference to the Settings component instance in the mySettingsComponentInstance variable.

var mySettingsComponentInstance = $('.CoveoSettings').coveo('get');

Using the jQuery extension, you can also call a method directly on a component instance.

Example

Consider the following markup:

[ ... ]

<div class='coveo-facet-column'>

  [ ... ]

  <div class='CoveoFacetSlider' data-field='@size'></div>

  [ ... ]

[ ... ]

Running this code sample puts a copy of the current selection of the FacetSlider component instance whose id option is @size in the currentSelection variable (see FacetSlider.getSelectedValues()).

var currentSelection = $('.CoveoFacetSlider[data-id="@size"]').coveo('getSelectedValues');

If a method requires parameters, you can pass them as arguments with the jQuery extension.

Example

Consider the following markup:

[ ... ]

<div class='coveo-facet-column'>

  [ ... ]

  <div class='CoveoFacetSlider' data-field='@size' data-range-slider='true' data-begin='0' data-end='100'></div>

  [ ... ]

[ ... ]

Running this code sample sets the currently selected values of the FacetSlider component instance whose id option is @size to 10 and 25 (see FacetSlider.setSelectedValues()).

$('.CoveoFacetSlider[data-id="@size"]').coveo('setSelectedValues, [10, 25]);

Calling a top-level function

Top-level functions are functions you can call directly from the Coveo namespace (for example, Coveo.executeQuery(), Coveo.state(), etc.). You can call any top-level function using the jQuery extension. If a function requires parameters, you can pass them as arguments with the jQuery extension.

Example

Consider the following markup:

[ ... ]

<body id='search' class='CoveoSearchInterface'>

[ ... ]

</body>

Running the following code sample will log a custom event to the Coveo Search Analytics service (see Coveo.logCustomEvent()).

var myCustomEventReason = { name : 'myCustomEventName', type : 'myCustomEventType' };
var myCustomEventMetadata = { myKey_1 : 'my value 1', myKey_2 : 'my value 2', myKey_n : 'my value n' };
$('#search').coveo('logCustomEvent', myCustomEventReason, myCustomEventMetadata);

Binding an event handler

While this isn’t strictly part of the Coveo jQuery extension, you can use the jQuery on() method to bind an event handler. Most of the time, the event target should be the root element of your search interface.

Example

The script part of the following code sample binds an event handler to the root element of the search interface on the buildingQuery event to add foobar to the current query expression.

<head>

  [ ... ]

  <script>
    document.addEventListener('DOMContentLoaded', function () {
      Coveo.SearchEndpoint.configureSampleEndpointV2();

      var root = $('#search');
      $(root).on('buildingQuery', function(e, args) {
        args.queryBuilder.expression.add('foobar');
      });
      Coveo.init(root);
    })
  </script>

  [ ... ]

</head>

<body id='search' class='CoveoSearchInterface'>

  [ ... ]

</body>

Which way should I use?

You can use any of the three preceding ways to achieve perfectly equivalent results. It’s up to you to decide which one you prefer.

  • Using "pure" JavaScript can be a little verbose, but it will obviously always be supported.

  • Using Coveo.$$ allows you to access the Dom class, which implements some of the most frequently used jQuery functionalities without actually depending on jQuery at all. Internally, this is the method that the Coveo JavaScript Search Framework uses.

  • Using the jQuery extension can allow you to write less verbose code. However, it’s no longer considered "core" to the Coveo JavaScript Search Framework. The current major version of the framework will always support it, though.