Integrating a Search Interface Into Your Commerce Solution or Website

Now that you have created a source to index your website data (see Indexing Website Content Instructions), you need to create a Coveo search interface in your website to get results from your index.

This article explains how to do this using the recommended JavaScript Search Framework, which is a very simple and fast path to a full featured search interface providing ML-ready usage analytics.

When using the JavaScript Search Framework is not an option, developers can achieve the same results using the APIs, but with significantly more work (see Building Custom Search Integrations Using Coveo Cloud PaaS).

Step 1 - Setting up an Environment with the Coveo JavaScript Search Framework

Setting up a working environment is the recommended way of obtaining and using the Coveo JavaScript Search Framework. Proceed as indicated in this section to obtain a working environment including:

  • the JavaScript Search Framework tutorial repository which contains the Framework itself
  • npm, the Node.js package manager, to install your project dependencies, build and run your project in a dev server

To set up your working environment, follow all the steps in the JavaScript Tutorial environment setup page, beginning at step Install Git up to the Run Server step inclusively.

When you run the server, the page displayed is the bin/index.html file in the repository. This Coveo demo search page is the starting point for your website search interface.

Step 2 - Create an API Key

Your Coveo search page needs an API key to connect to your cloud index.

To create an API key with the required privileges

  1. Log into the Coveo Cloud platform.

  2. In the administration console, create an API key (see API Keys). Provide the privileges below:

    • Execute queries
    • Analytics data (Push)

    Do not forget to copy your API key when it is provided in the dialog.

Step 3 - Create a New Search Endpoint in Your Search Page

Now that you have an API key, you can link your search page to your Cloud organization in order to query your index.

To link your search page to your cloud index

  1. Open file bin/index.html in your development environment source code editor.
  2. In the <head> section of the file, locate the following initialization <script> block:

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

    Replace this block with the one below.

    <script>
       document.addEventListener('DOMContentLoaded', function () {
         var root = document.body;
         Coveo.SearchEndpoint.endpoints['default'] = new Coveo.SearchEndpoint({
           restUri: 'https://platform.cloud.coveo.com/rest/search',
           accessToken: '[paste your API key here]'
         });
         Coveo.init(root);
       })
    </script>
    
  3. Paste your API key as the accessToken value in the initialization script block.
  4. Save your changes. You should now have a functional Coveo search page connected to your Cloud organization index.
  5. Try your search page:
    1. If necessary, run the dev server by typing the following command:

      npm run watch
      
    2. Open file index.html with your favorite browser at http://localhost:3000.
    3. Experiment with the search box and the facet(s) of your preliminary website search page.

Step 4 - Add the Analytics Component

Adding the Coveo Analytics component enables the logging of search and click events that feed Coveo Machine Learning.

To add the `Analytics` component

  1. Open file bin/index.html in your source code editor.
  2. Add the following <div> tag anywhere within the <body> section of the page.

    <div class='CoveoAnalytics'></div>
    
  3. Ensure that your search page events are sent properly:
    1. Open file index.html with your favorite browser.
    2. Type something in the search box and hit Return. In the developer tools, you should see that your browser sends a POST request.

Step 5 - Use Coveo Online Resources

To be able to move the index.html page freely, you need the index.html file to reference Coveo online resource files rather than the ones provided in the repository folder (see JavaScript Search Framework CDN Links). This amounts to editing five lines in the <head> section of the file.

To make `index.html` reference the Coveo online resource files

  1. Open file index.html in your source code editor.
  2. Locate the following lines in the <head> section:

     <link rel="stylesheet" href="./css/CoveoFullSearch.css"/>
     <script src="js/CoveoJsSearch.Lazy.js"></script>
     <script src="js/templates/templates.js"></script>
    
  3. Replace those lines with the following:

    <link rel="stylesheet" href="https://static.cloud.coveo.com/searchui/v2.4382/css/CoveoFullSearch.css"/>
    <script src="https://static.cloud.coveo.com/searchui/v2.4382/js/CoveoJsSearch.Lazy.js"></script>
    <script src="https://static.cloud.coveo.com/searchui/v2.4382/js/templates/templates.js"></script>
    
  4. In the URLs of those five lines, replace the 4382 4-digit version number sequence to match the latest JavaScript Search Framework version. You can find the 4-digit version number sequence of the latest JavaScript Search Framework release in the JavaScript Search V2 - Release Notes.

  5. Delete the <div> line below to remove the Hello World banner.

    <div class="CoveoHelloWorld"></div>
    
  6. Open index.html in your favorite browser and ensure that the search page is still working properly.

Step 6 - Inserting a Website-Wide Search Box in Your Page Headers

Instead of the current single search page setup, you might prefer having a search box in the header of your website pages and have queries in the those search boxes redirect to your search page. Since search boxes will appear throughout the website, you can also delete the search section container and its components from the index.html file and replace this container with the website-wide header search box. These changes essentially make the index.html file a search results page.

  1. In your source code editor, in the /bin folder of the project, create a file called searchbox.html.
  2. Go to the Creating a Standalone Search Box - Configuration - Example.
  3. Copy the basic standalone search box example code block and paste it in your searchbox.html file.
  4. Replace the JavaScript v2 version number in the resource file URLs, as you did in Step 5 - Use Coveo Online Resources.

  5. In the initialization script, replace the sample API key with your own, as illustrated below.

    SearchEndpoint.configureCloudV2Endpoint("", "[paste your API key here]");
    
  6. Add the Analytics component inside the <body> section of the file.

    <div class='CoveoAnalytics'></div>
    
  7. Ensure that your search box works properly:

    1. Open file searchbox.html with your favorite browser at http://localhost:3000/searchbox.html.
    2. Type something in the search box and hit Return. The search should redirect to your search results page.
    3. On the search results page, in the developer tools, you should see that your browser sends a POST request with a request payload originLevel3 value that indicates the page where the search event actually took place.

Step 7 - Integrate the Search Results Page and the Header Search Box into Your Website

You now have header search box code and a search results page that you can use in your website.

  1. Copy your search results page into your website content source folder. Change its filename if necessary.
  2. Ensure that your header search box initialization script accurately references the location of your website search results page.
  3. Integrate your search box code into the html file used to display your website pages header section.
  4. In the index.html file, locate the search section code block below. This is the code associated with the current search box section.

     <div class='coveo-search-section'>
       <div class="CoveoSettings"></div>
       <div class="CoveoSearchbox" data-enable-omnibox="true"></div>
     </div>
    
    1. Delete this code block.
    2. Integrate your website pages header section into your search results page.
  5. Ensure that your website search interface works properly.

Step 8 - Learn More About the Coveo JavaScript Search Framework

You now have a general understanding of how a Coveo search interface is configured.

You might now want to follow the JavaScript Search Framework Getting Started Tutorial to better familiarize yourself with the framework concepts, components, functions and methods to even further customize your website search interface.