Integrate a Search Page Into Your Commerce Solution

This article serves as an introduction and high-level guide to creating a search interface with the Javascript Search Framework. For more in-depth implementation guidelines, see Leveraging the Coveo JavaScript Search Framework.

Example Code

You can quickly build a minimal search interface using just a few dozen lines of HTML code:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>My Basic Search Page</title>
    <link rel="stylesheet" href="https://static.cloud.coveo.com/searchui/+++v2.10103+++/css/CoveoFullSearch.css"/>
    <script src="https://static.cloud.coveo.com/searchui/+++v2.10103+++/js/CoveoJsSearch.Lazy.min.js"></script>
    <script src="https://static.cloud.coveo.com/searchui/+++v2.10103+++/js/templates/templates.js"></script>
    <script>
    document.addEventListener("DOMContentLoaded", function () {
      // Replace with your actual organization ID.
      const organizationId = "<ORGANIZATION_ID>";
      // Replace with an API key or search token that grants the privileges to execute queries and write usage analytics events.
      const accessToken = "<ACCESS_TOKEN>";
      Coveo.SearchEndpoint.configureCloudV2Endpoint(organizationId, accessToken);
      Coveo.init(document.getElementById("search"));
    })
    </script>
  </head>
    <body id="search" class="CoveoSearchInterface" data-results-per-page="2">
        <div class="CoveoAnalytics"></div>
        <div class="coveo-tab-section">
            <a class="CoveoTab" data-id="All" data-caption="All Content"></a>
        </div>
        <div class="coveo-search-section">
            <div class="CoveoSearchbox"></div>
        </div>
        <div class="coveo-main-section">
            <div class="coveo-facet-column">
                <div class="CoveoDynamicHierarchicalFacet" data-title="Category" data-field="@categoriesh" data-tab="All"></div>
            </div>
            <div class="coveo-results-column">
        <div class="CoveoResultList" data-layout="card">
            <script class="result-template" type="text/html">
                <div class="coveo-result-frame">
                    <div class="coveo-result-row">
                        <div class="CoveoImageFieldValue" data-field="@gallery_image" data-width="350"></div>
                    </div>
                    <div class="coveo-result-row">
                        <div class="CoveoFieldValue" data-field="@brand"></div>
                    </div>
                    <div class="coveo-result-row">
                        <div class="CoveoFieldValue" data-field="@title"></div>
                    </div>
                    <div class="coveo-result-row">
                        <div class="CoveoFieldValue" data-field="@price" data-helper="currency"></div>
                    </div>
                </div>
            </script>
        </div>
            <div class="CoveoPager"></div>
            </div>
        </div>
    </body>
</html>

The rest of this article dissects and analyzes the various sections of the above code sample.

Including the JavaScript Search Framework Resources

To use the Coveo JavaScript Search Framework, link the following three files in the <head> of the page (see JavaScript Search Framework CDN Links):

  1. The stylesheet containing all of the Coveo styling classes used to structure your search interface (see Styling the Coveo JavaScript Search Framework).

    <link rel="stylesheet" href="https://static.cloud.coveo.com/searchui/+++v2.10103+++/css/CoveoFullSearch.css"/>
  2. The main framework that handles search interface interactions and populates the Coveo namespace.

    <script src="https://static.cloud.coveo.com/searchui/+++v2.10103+++/js/CoveoJsSearch.Lazy.min.js"></script>
  3. The prebuilt result templates for constructing simple result lists.

    <script src="https://static.cloud.coveo.com/searchui/+++v2.10103+++/js/templates/templates.js"></script>

Initializing the Javascript Search Framework

Before you can begin searching content, you must connect your search page to your Coveo organization using an endpoint.

Configure your endpoint after the page finishes loading by using the DOMContentLoaded event.

<head>
  ...
  <script>
  document.addEventListener("DOMContentLoaded", function () {
    // Replace with your actual organization ID.
    const organizationId = "<ORGANIZATION_ID>";
    // Replace with an API key or search token that grants the privileges to execute queries and write usage analytics events.
    const accessToken = "<ACCESS_TOKEN>";
    Coveo.SearchEndpoint.configureCloudV2Endpoint(organizationId, accessToken);
    Coveo.init(document.getElementById("search"));
  })
  </script>
</head>

Once the endpoint is configured, you can call the init function, which attempts to initialize all HTML elements on your page with a Coveo-prefixed class (i.e., CoveoDynamicFacet) as a Coveo component.

The most common authentication method for a commerce application is with a public API Key.

Endpoints must be authenticated with either a search token or the API key for Search you created for your catalog. This will let you retrieve results for search pages, product listings, or recommendations.

Before you start, ensure you’re aware of the leading practices regarding API keys. To create an API key for Search:

  1. On the Catalogs (platform-eu | platform-au) page, click the catalog for which you want to create an API key, and then click Create API Key in the Action bar.

  2. Select an API key for Search.

  3. Click Create Key.

Important

The created API key value is unique. It’s impossible to view the value more than once.

If you fail to get the value, delete the lost key and create a new one.

Building Your Search Interface

A Coveo-powered search interface is typically composed of a number of framework components. These components add functionality to your search interface.

jsui-overview

Some essential components include:

Framework component Description

CoveoSearchInterface

Acts as the container for all Coveo components.

<body id="search" class="CoveoSearchInterface"></body>

CoveoTab

Allows end users to select a specific subinterface. Selecting a tab will typically apply a specific query filter (e.g., to only consider a certain subset of items). Certain search interface elements may also only be visible when a given tab is selected.

<a class="CoveoTab" data-id="All" data-caption="All Content"></a>

CoveoSearchBox

Allows end users to enter keywords that update the result list by modifying the basic query expression (q).

<div class="CoveoSearchbox"></div>

CoveoFacet

Displays a list of values for a specific field occurring in the results.

<div class="CoveoFacet" data-title="Category" data-field="@categoriesh"></div>

CoveoResultList

Displays query results by applying one or more result templates.

<div class="CoveoResultList"></div>

CoveoPager

Allows end users to navigate through the different result pages.

<div class="CoveoPager"></div>

There’s another essential component which isn’t visible in a search interface; the CoveoAnalytics component. This component logs user actions performed in the search interface and sends them to Usage Analytics Write API.

<div class="CoveoAnalytics"></div>

What’s Next?

You now have a general understanding of how to configure a Coveo-powered search interface.

You may want to follow up by going through the JavaScript Search Framework Tutorials to better familiarize yourself with its concepts, components, functions, and methods.

You may also want to create a standalone search box to provide relevant search throughout your commerce solution or website.