Skip to end of metadata
Go to start of metadata

The Coveo JavaScript Search Framework exposes several events that allow external code to interact with the framework.

Naturally, these events seem to follow a perfectly sequential flow (component initialization, query preparation, query execution, results rendering). However, this does not imply that the flow of execution of events is a sequential process. As a matter of fact, the execution of some events overlap, and certain "previous" events are still executing by the time some "later" events start their own execution process.

Several events have no association with any particular component. These are global events. For instance, initialization events, as well as events you trigger when executing a query, are global events.

End user interaction with the Coveo JavaScript Search Framework components is the main trigger of events (see Triggers and Lifecycle Traces for examples). Some components such as  Analytics and Breadcrumb  use events to interact with other components, or with external code.

Attaching Event Handlers

The events triggered by the Coveo JavaScript Search Framework are regular DOM events, and you can attach any handler to them as for any other event. In particular, we recommend using jQuery's  on call to register handlers, like in the following example:

The first argument passed to the handler is the standard jQuery Event Object containing various information about the event. The second argument is provided by the Coveo JavaScript Search Framework and contains information about the event as well as objects allowing external code to integrate with the action being processed (see QueryBuilder).

Most of the time, events can be listened to via the root HTML element of the search interface. That element is referenced in the selector passed to the $ jQuery function - - generally referred as $('#search). Global events are typically raised directly on this element. Some components will also raise events on their own HTML elements, but since those events bubble up, a handler registered on the root element will also catch them.

Embedding Event Handlers

There may come some use cases where it is needed to adapt the sequential flow of events.  In order to exercise some control you can embed subsequent events in the sequence.  This ensures that a handler - outside of its standard processing - will have a guaranteed timely execution strictly when the handler in which it is embedded has successfully completed its execution.  

Icon

Embedding handlers becomes the practice to enforce strict sequential execution of events

The event deferredQuerysuccess will have an execution only once afterComponentsInitialization will be completed as shown in this example.

Strict Sequential Execution

 

Initialization Events

Components are attached to HTML elements decorated by well-known CSS classes during initialization. Thus, to use a component, a developer only needs to insert an HTML tag in the page with the appropriate CSS class.  

Where to use initialization events

Icon

What triggers initialization is a call to: $('#search').coveo('init');
Therefore, it is required to handle initialization events before the required call to $('#search').coveo('init'). Handlers declared afterwards won't partake in the first initialization of the search page as shown by the dotted lines in the flow diagram.

 

This parses thru the HTML body and substitutes any declared Coveo Component by its respective DOM element for rendering. Upon instigating this call you can make more specific component initialization, for example:

 

beforeInitialization

Triggered before components are initialized.

This event does not provide custom event data.

afterComponentsInitialization

Triggered after the components are initialized, but before their state is set from the hash portion of the URL (e.g. http://mysearchinterface#q=myQuery ). See the enableHistory option on the SearchInterface Component.

This event does not provide custom event data.  

Icon

Intent of use is to provide an opportunity for external code to alter the components before they are rendered. 

afterInitialization

Triggered after the UI is fully initialized. This event is triggered before the first query is launched, if the autoTriggerQuery option is enabled on the SearchInterface Component.

This event does not provide custom event data.

Initialization Code Examples

Query Events

Icon

Most query events - represented by a unique or multiple handlers - will be executed in sequence when written before the required call to $('#search').coveo('init'). When a search page triggers an automatic query these events will disregard handlers written after the initialization. On subsequent queries, the events will execute in sequence whether declared before or after.

The exceptions are duringQuery, querySuccess and deferredQuerySuccess. They will execute in sequence on all occasions. The event querySuccess will have a unique behavior as a handler written after the initialization call will instigate itself only once newResultsDisplayed is completed.

newQuery

Triggered when a new query is to be performed.

This event provides the following event data:  

NameDescription
cancel

If an handler sets this flag to true , the query will be cancelled.

Available in: June 2015 Release

Components listening to this event: DidYouMean, Facet and Pager.

buildingQuery

Triggered when a new query is being performed in order to build the QueryBuilder for the query.

This event provides the following event data:

NameDescription
queryBuilder

The QueryBuilder object for the query being prepared.

cancel

If an handler sets this flag to true , the query will be cancelled.

Available in: June 2015 Release

Components listening to this event: DidYouMean, Facet and Pager.

doneBuildingQuery

Triggered after the buildingQuery event, once the QueryBuilder is fully built.

NameDescription
queryBuilder
The QueryBuilder object for the query being prepared.
cancel

If an handler sets this flag to true , the query will be cancelled.

Available in: June 2015 Release

Components listening to this event: Facet.

duringQuery

Triggered to signal that a query is currently being executed on the server.

NameDescription
queryBuilder
The QueryBuilder object for the query.
queryThe Query object for the query.
deferredThe jQuery Deferred that will be resolved once the query is finished executing.

Components listening to this event: Facet.

Different scenarios can occur after the reception of the JSON response.  Some events may run sub-queries to inject related content within the current context that the initial query did not provide.  In such cases, the execution of the sub-query has a deferred impact on the flow of events and will provoke a re-entry into the event, instigating the asynchronous query call as is the case for the newResultDisplayed event in the illustration: 

Another scenario is having embedded events. As illustrated below, the querySuccess event has been embedded in multiple other events.  Executions of these strictly declared events can vary, but will mainly be executed either before or after their execution within a standard sequence (see  Triggers and Lifecycle Traces  to test other examples).         

preprocessResults

Triggered after a query executed successfully but before the querySuccess events. Intent of use is to provide an opportunity for external code to alter the results before they are processed by other components.

NameDescription
queryBuilder
The QueryBuilder object for the query.
queryThe Query  object for the query.
resultsThe Results object containing the results returned by the server.

Components listening to this event: Folding.

preprocessMoreResults

Available since: December 2015 Release

Triggered after a query from a ResultFolding Component executed successfully. Intent of use is to provide an opportunity for external code to alter the results before they are processed by other components.

NameDescription
resultsThe Results object containing the results returned by the server.

noResults

Triggered after a query executed successfully but returned no results. This event provides an opportunity for external code to alter the query and request for it to be executed again.

NameDescription
queryBuilder
The QueryBuilder object for the query.
queryThe Query  object for the query.
resultsThe Results  object returned by the server.
retryTheQueryIf an handler sets this flag to true, the query will be executed again.

Components listening to this event: DidYouMean and Pager.

querySuccess

Triggered when a query has finished executing successfully.

NameDescription
queryBuilder
The QueryBuilder object for the query.
queryThe Query  object for the query.
resultsThe Results  object containing the results returned by the server.
searchAsYouTypeBoolean flag that signifies if the query was a "Search as you type"

Components listening to this event: DidYouMean and Pager.

It is important to take note that the querySuccess event will not sequentially execute handler counterparts.  Any handler declared after the initialization will be executed after the newResultsDisplayed event. 

deferredQuerySuccess

Triggered when a query has finished executing successfully.  This is the event listened by the Facet Component rather than the querySuccess.  This specific design is mainly to optimized mobile device for performance reasons as it allows the ResultList Component to be rendered in priority.

NameDescription
queryBuilder
The QueryBuilder object for the query.
queryThe Query object for the query.
resultsThe Results object containing the results returned by the server.

Components listening to this event: Facet.

queryError

Triggered when a query encounters an error during execution.

NameDescription
queryBuilder
The QueryBuilder  object for the query.
queryThe Query object for the query.
errorThe Error object containing information about the error.
endpointThe Coveo.SearchEndpoint Class that was used for this query
searchAsYouTypeBoolean flag that signifies if the query was a "Search as you type"

Components listening to this event: Pager.

Omnibox Events

Icon
See the Omnibox Component and Providing Suggestions for the Omnibox for more information.

Icon
Will be executed in sequence when written before or after the required call to $('#search').coveo('init').

openOmnibox

Triggered when the Omnibox is opening.

This event does not provide custom event data.

closeOmnibox

Triggerred when the Omnibox is closing

This event does not provide custom event data.

populateOmnibox

Triggered when the Omnibox is requesting data to populate itself

NameDescription
populateOmniBoxObjectThe PopulateOmniBoxObject that provides an interface for the Omnibox.

ResultList Events

Icon
Will be executed in sequence when written before or after the required call to $('#search').coveo('init').

newResultsDisplayed

Triggered when the result list has been rendered after a new query.

This event does not provide custom event data.

newResultDisplayed

Triggered when the result list has been rendered after a new query.

This event provide custom event data.

NameDescription
itemThe HTML Element rendered by the result list.
resultThe result's data.

Breadcrumb Events

Icon
See the Breadcrumb Component for more information.

Icon
Will be executed in sequence when written before or after the required call to $('#search').coveo('init').

populateBreadcrumb

Triggered when the breadcrumb needs to update its content. External code can use this event to provide bits of HTML that should be included in the breadcrumb.

This event provides the following event data:

NameDescription
breadcrumbsArray of breadcrumb items (HTML elements) to include in the breadcrumb. Adding entries in this array will cause them to be displayed within the breadcrumb.

clearBreadcrumb

Triggered when the user clicks the Clear All button in the breadcrumb. When this event is raised, every filter that is included in the breadcrumb should be removed.

This event does not provide custom event data.

Analytics Events

changeAnalyticsCustomData

Triggered before the custom data and metadata is sent to the service, allowing external user to modify and customize what is about to be sent.

NameDescription
typeThe event type that is being logged. Can be SearchEvent, ClickEvent or CustomEvent
metaObjectThe custom event metadata. Any key/value set on this object will be reported as custom metadata to the Coveo Analytics Platform and can then be used as custom dimension in analytics reports.
languageThe language of the current search page.
originLevel1The name of the current search hub.
originLevel2The name of the current search interface.
originLevel3

A specification on the name of the current search interface or search hub. 

Available since: December 2015 Release

resultData

On ClickEvents, an additional parameter is available on the event object (first parameter of the callback function).  

You can take advantage of the resultData object to push more analytics data from the results that have been clicked.  

Example:

You want to include in the pushed analytics data the value of the product field for the clicked result:

UserAction Event

openQuickView

Triggered when the user opens a Quick View. You can use this event to modify the terms to highlight.

This event provides the following event data:

NameDescription
termsToHighlightA list of of the terms that will be highlighted in the Quick View.
Example:

The following code highlights the terms test and another_test in the Quick View.

  • No labels

2 Comments

  1. Is there an event that fires when the "infinite page scroll" request to loads more items?  I'm finding that "buildQuery" fires once on the initial query, but not the content streams in.  Thanks!

    1. There is no event fired on the fetch more method. There are events triggered when new results are displayed though.