jQuery extension

This is for:

Developer

Many features of the Coveo JavaScript Search Framework are accessed through a jQuery extension named coveo. This extension provides ways to initialize components and work with them as well as a certain number of global utility calls.

The coveo extension can be invoked on a jQuery object resulting from the evaluation of a selector. The first argument passed to the extension is the name of the method to execute, followed by the arguments specific to the method being called.

Here is an example of a call using the extension:

$('.someClass').coveo('methodName', arg1, arg2);

If your JavaScript Search Framework version was released before July 2016, it’s developed, tested, and delivered with a specific jQuery version (see Download the JavaScript Search Framework). You must therefore include and use this jQuery version to minimize risks of jQuery version related issues.

Like many sites, yours may already include a version of jQuery that’s different from the one bundled with the Coveo JavaScript Framework. You can load two versions of jQuery and use them independently (see Use two versions of jQuery in the same page).

Global calls

Initialize the search interface

The following coveo extension call initializes a search interface by automatically creating the components associated with the CSS classes found on the children of the selected element.

$(selector).coveo('init', [options])

options - Json object that represents the options to use to initialize the components. See Components to find the available options of each component.

Initialize all components of the same kind with a global option

To reference all components of the same type, use the name of the component without the Coveo prefix. So CoveoFacet becomes Facet, CoveoSort becomes Sort, etc.

//Example: Disable the search option in all the facets 
$(selector).coveo('init', {
    Facet: {
        enableFacetSearch: false
    }
})

Initialize one instance of a component with an option

To reference a particular component bound to an HTML element in your page, add an id attribute on that HTML element.

//Example: Disable the search option for a single facet 
$(selector).coveo('init', {
    SearchDisabled: {
        enableFacetSearch: false
    }
})

// [...]
// [...]
// [...]
 
 <div class='CoveoFacet' id='SearchDisabled'></div>

The following coveo extension call initializes a standalone search box that will redirect searches to url (see Create a standalone search box). The third parameter can be used to pass options much in the same way as for the init call.

$(selector).coveo('initSearchbox', url, [options])

Get the instance of a component bound to an HTML element

The following coveo extension call retrieves the instance of the component object bound to an element. If the selector matches more than one element, only the first component object is returned.

$(selector).coveo('get'[, 'ComponentType'])

If many components are bound to the same element (frequent when dealing with the root element), you can specify the name of the component. Be careful not to include the Coveo prefix that’s part of the CSS class for each component.

Special case

Invoking the coveo extension without any method name is a shortcut to call the get method. Therefore, the following calls are equivalent:

$(selector).coveo('get')
$(selector).coveo()

Get the result bound to an HTML element

Coveo JavaScript Search Framework 1.0.273 (December 2015)

The following coveo extension call retrieves the result bound to an element. If the selector matches more than one element, only the result bound to the first one is returned.

$(selector).coveo('result')

Execute a query

To trigger a new search.

$(selector).coveo('executeQuery')

Pass options before init

It’s sometimes useful to be able to pass options before the call to init is made (as described in Components). 

$('#search').coveo('options', {
    SearchInterface: {
        autoTriggerQuery: false
    }
})
 
[...]
 
// Here, the search interface would be initialized and wouldn't trigger the first query
$('#search').coveo('init')

Other available extensions

  • Logging custom analytics event (see Analytics Component).

  • Set or get attributes on the interface state (see State).

Component method calls

Methods of component objects can be called directly from the coveo extension.

The following code calls the displayMoreResults method on the component bound to the HTML element with the id myResultList:

 $('#myResultList').coveo('displayMoreResults', 10)

Monkey patching component methods

Sometimes, it can be useful to override the behavior of a component method. This can be easily done in JavaScript via a process commonly referred to as Monkey Patching. The Coveo jQuery Extension allows patching a method of an instance of one or several components using the patch method, as shown in the following code sample:

$('.MyComponents').coveo('patch', 'methodName', function() {
  // Here is the code of the new method.
});

Inside the new method, you can call the original implementation using __methodName, as shown in the following code sample:

$('.MyComponents').coveo('patch', 'myMethod', function(someArg) {
  this.__myMethod(someArg);
});

Using the jQuery extension on an HTML element when there’s more than one component

If you want to use a component that’s bound to an HTML element with many components, the Coveo jQuery Extension needs to know which component you’re trying to access on this element.

Let’s say that the root of your search interface has 4-5 other components bound to it. Using the following jQuery selector would result in the following error (in your browser console):

"More than one component is bound to this element. You need to specify the component type."

$('#mySearchInterface').coveo('get')

To solve this problem, use the following code:

$('#mySearchInterface').coveo(Coveo.SearchInterface, 'get')

To patch a method of an instance of a component that’s bound to an element with other components bound to it, use the following code:

$('.MyComponents').coveo('patch', 'MyComponent.myMethod', function(someArg) {
  this.__myMethod(someArg);
});