Core concepts

This is for:

Developer

This article provides a quick overview of the various things you need to know in order to understand how the Coveo JavaScript Search Framework operates.

Components

The Coveo JavaScript Search Framework is based on a set of components. Each component provides a specific (and often visual) functionality that’s meant to be useful within a search interface (see Coveo JavaScript Search Framework - Reference Documentation). Components can be very simple, such as the SearchButton which triggers a new query when the user clicks its element, or quite complex, such as the Facet which allows drilling down within results using filters based on field values.

During initialization, components attach themselves to HTML elements having well-known CSS classes. Therefore, to instantiate and use a component, you need to insert an HTML tag in the page with the appropriate CSS class.

You can create a customized search interface by assembling the components you need within an HTML page. No single component is mandatory; you need only include the components you need to get the functionalities you’re looking for. All the visual parts of a search interface, such as the query box, the result list, the pager and so on, are in fact separate components that you can arrange and configure as you see fit.

See JavaScript Search Framework Tutorial 1: Basic Configuration, Options, and Markup.

Methods and events

Most interactions with the components that make up the Coveo JavaScript Search Framework are performed by calling methods and listening to events.

Methods are used to trigger actions such as performing a new search, selecting facet values, etc. Methods can easily be executed on components bound to an HTML element using the Coveo jQuery Extension (see jQuery extension). It’s also possible to execute methods on components using pure JavaScript or the Dom helper class (see JavaScript Search Framework Tutorial 2: Interact With the Search Interface and Component Instances).

Events are triggered to signal specific conditions and to allow external code to execute in order to customize the behavior of the search interface. The Coveo JavaScript Search Framework events are regular DOM events. Therefore, you can easily attach event handlers to them by using jQuery’s .on() or any other method that can add listeners to DOM events. Most of the time, you will want to listen to events on the root HTML tag of your search interface. Events typically provide event data that contains information about the event and provides ways to interact with the framework (see JavaScript Search Framework Tutorial 3: Understanding the Event System).

  • One particularly interesting event is buildingQuery. This event sends an object called queryBuilder, which allows components to add data to the outgoing query.

  • Another interesting event is querySuccess, which, as its name implies, sends an object called results, which any component can access and read data from.

See JavaScript Search Framework Tutorial 4: Modify the Query).

See the Events section for more information.

State

The search interface has a state comprised of, among other things, the current query in the query box and the currently selected facets. When browser history management is enabled (as is typically the case in a full search page), this state is persistent in the browser query string.

When the user performs an action such as clicking a facet value, the state is automatically updated to reflect the change. Also, if the state is changed through code or directly through the query string, the appropriate components will update their visual representation to reflect the change.

The jQuery extension provides an easy way to manipulate the state in external code. The same results can also be achieved using the state top level function (see JavaScript Search Framework Tutorial 7: Interact With Component States).

For more information, see the State section.

Tutorial

If you’re new to the Coveo JavaScript Search Framework, you should read the Getting Started Tutorial (see JavaScript Search Framework Getting Started Tutorial).

What’s next?

Articles in this section: