JavaScript Search Framework Tutorial 2 - Interacting With the Search Interface and Component Instances

The Coveo JavaScript Search Framework offers several high-level functions and methods that you can use to interact with the interface and each of its individual components.

In this tutorial, you will learn how to execute a query, get a component instance, and execute a method on this instance.

You will also have the opportunity to put what you have learned in practice by doing exercises.

If you have significantly modified the ./bin/index.html page in the previous tutorial, you can undo these changes by rebuilding the project. To do so, run the following command line from the root of the tutorial project folder:

npm run build

Execute a Query

Consider the following markup in an HTML page:

<body id="search" class='CoveoSearchInterface'>
  [ ... ]
</body>

Using the Coveo JavaScript Search Framework, you could trigger a new query using pure JavaScript, as such:

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

You can also use the Dom helper class (see Class Dom), this way:

var rootElement = Coveo.$$(document).find('#search');
Coveo.executeQuery(rootElement);

Finally, you can use jQuery to interact with the framework:

$('#search').coveo('executeQuery');

Why three different ways to trigger a query?

For historical reasons, the Coveo JavaScript Search Framework was initially designed primarily as a jQuery extension. Consequently, lots of examples and code samples in the reference documentation use the jQuery extension. Over time, however, the jQuery extension became more of an “add-on” to the framework. It is no longer considered “core”.

Internally, the framework does not use jQuery at all. It instead uses the Dom helper class.

The jQuery extension is still available for developers who might feel more comfortable with it.

The three ways to trigger a query are perfectly equivalent and execute the exact same underlying code. It is up to the developer to choose which one they prefer.

Get a Component Instance

Consider the following markup in an HTML page:

<body id="search" class='CoveoSearchInterface'>
  [ ... ]
  <div class="CoveoFacet" data-title="Source" data-field="@source" data-tab="All"></div>
  [ ... ]
</body>

You could get the Facet component instance using pure JavaScript, as such:

var facetElement = document.querySelector('.CoveoFacet[data-title="Source"]');
var facetInstance = Coveo.get(facetElement);

You can also use the Dom helper class (see Class Dom), this way:

var facetElement = Coveo.$$(document).find('.CoveoFacet[data-title="Source"]');
var facetInstance = Coveo.get(facetElement);

Finally, you can use jQuery to interact with the framework:

var facetInstance = $('.CoveoFacet[data-title="Source"]').coveo('get');

The rest of this tutorial step will only show examples using the Dom helper class.

Execute a Method on a Component Instance

Consider the following markup in an HTML page:

<div id="search" class='CoveoSearchInterface'>
  <div class="CoveoSearchbox" data-enable-omnibox="true"></div>
  <div class="CoveoFacet" data-title="Source" data-field="@source" data-tab="All"></div>
</div>

You can select the YouTube - bbcnews value from the Facet instance like this:

var facetElement = Coveo.$$(document).find('.CoveoFacet[data-title="Source"]');
var facetInstance = Coveo.get(facetElement);
facetInstance.selectValue('YouTube - bbcnews');

Then, you could call the reset method from the Facet instance like this:

facetInstance.reset();

More Information on Available Functions and Methods

This section contains answers to some of the most frequently asked questions about available functions and methods in the Coveo JavaScript Search Framework.

Q: How can I know what global functions, such as executeQuery, are available in the framework?
- A: In the reference documentation index, you can find a Functions section in which all function calls available under the Coveo namespace have been listed (see Coveo JavaScript Search Framework - Reference Documentation).
  
  You can use the state global function to get the state object, which will be discussed later in this tutorial (See JavaScript Search Framework Tutorial 8 - Interacting With Component States).
Q : How can I know what methods are available for a specific component, such as the selectValue or reset methods of the Facet component?
- A : In the reference documentation, you can find all publicly exposed methods for any component by consulting the documentation of that component.
  
  isElementIncludedInTab and select are exposed methods of the Tab component.

Exercises

All exercises in this section should be done by modifying the tutorial search page under ./bin/index.html. The exercises should not be done by modifying the original search page under ./pages/index.html.
To actually see the results in your demo page, you must be running a webpack-dev-server (See JavaScript Search Framework Tutorial 0 - Environment Setup).

In your search interface, add a new button that triggers a query when clicked.

Solution

 <head>
  
 [ ... ]
   <script>
     document.addEventListener('DOMContentLoaded', function () {
       Coveo.SearchEndpoint.configureSampleEndpointV2();
       Coveo.init(document.body);
       // The following lines should be added.
       var buttonElement = document.querySelector('button');
       buttonElement.addEventListener('click', function() {
         Coveo.executeQuery(document.body);
       })
     })
   </script>
 </head>
  
 <body id="search" class='CoveoSearchInterface' data-enable-history="true">
   <!-- The following button should be added. -->
   <button>Click</button>
  
   [ ... ]
  
 </body>

Select a new tab after initialization.

Remember that you are using Lazy loading (see Lazy Versus Eager Component Loading).

Solution

 <head>
  
   [ ... ]
   <script>
     document.addEventListener('DOMContentLoaded', function () {
       Coveo.SearchEndpoint.configureSampleEndpoint();
       Coveo.init(document.body);
       // The following lines should be added.
       Coveo.load("Tab").then(function(Tab) {
         var secondTabElement = Coveo.$$(document).find(".CoveoTab[data-id='ANewTab']")
         var secondTabInstance = Coveo.get(secondTabElement);
         secondTabInstance.select();
       });
     })
   </script>
 </head>
  
 <body id="search" class='CoveoSearchInterface' data-enable-history="true">
   <div class="coveo-tab-section">
     <a class="CoveoTab" data-id="All" data-caption="All Content"></a>
     <!-- The following tab should be added. -->
     <a class="CoveoTab" data-id="ANewTab" data-caption="A New Tab"></a>
   </div>
  
   [ ... ]
  
 </body>

What’s Next?

You should now proceed to JavaScript Search Framework Tutorial 3 - Understanding the Event System.