Integrate a search page into your commerce solution

This is for:

Developer

This article serves as an introduction and high-level guide to creating a search interface with the Coveo Atomic library.

Important

This section provides information on how to implement search interfaces that interact with the Coveo Search API, which is no longer recommended for Coveo for Commerce implementations.

New Coveo for Commerce implementations should use the Coveo for Commerce API, which provides a more efficient and flexible way to interact with the Coveo Platform. See Build commerce interfaces for documentation on how to build commerce interfaces using the Coveo for Commerce API.

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>
    <!-- ... -->
    <script
        type="module"
        src="https://static.cloud.coveo.com/atomic/v2/atomic.esm.js">
    </script>
    <link
    rel="stylesheet"
    href="https://static.cloud.coveo.com/atomic/v2/themes/coveo.css"/>
    <script>
        (async () => {
        await customElements.whenDefined('atomic-search-interface');
        const searchInterface = document.querySelector('#search');

        await searchInterface.initialize({
            accessToken:'<ACCESS_TOKEN>',
            // Replace with an API key or search token that grants the privileges to execute queries and push usage analytics data.
            organizationId: '<ORGANIZATION_ID>',
            // Replace with your actual organization ID.
        });

        searchInterface.executeFirstSearch();
        })();
    </script>
    <!-- ... -->
    </head>
    <body>
        <atomic-search-interface search-hub="<SEARCH_HUB>">
            <atomic-search-layout mobile-breakpoint="800px">
                <atomic-layout-section section="search">
                    <atomic-search-box></atomic-search-box>
                </atomic-layout-section>

                <atomic-layout-section section="facets">
                    <atomic-facet-manager>
                        <atomic-facet field="cat_gender" label="Gender"></atomic-facet>
                        <atomic-facet field="store_name" label="Store"></atomic-facet>
                        <!-- ... -->
                    </atomic-facet-manager>
                </atomic-layout-section>

                <atomic-layout-section section="main">
                    <!-- ... -->
                    <atomic-layout-section section="results">
                        <atomic-result-list image-size="large" display="grid">
                            <atomic-result-template>
                                .
                                .
                                .
                            </atomic-result-template>
                        </atomic-result-list>
                    </atomic-layout-section>
                    <atomic-layout-section section="pagination" style="flex-direction: column">
                        <atomic-results-per-page choices-displayed="3,5,8,10"></atomic-results-per-page>
                        <atomic-load-more-results></atomic-load-more-results>
                    </atomic-layout-section>
                </atomic-layout-section>
            </atomic-search-layout>
        </atomic-search-interface>
    </body>
</html>

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

Including the Atomic library resources

To use the Atomic library, link the following two files in the <head> of the page (see install the Atomic library):

<script
    type="module"
    src="https://static.cloud.coveo.com/atomic/v2/atomic.esm.js">
</script> 1
<link
    rel="stylesheet"
    href="https://static.cloud.coveo.com/atomic/v2/themes/coveo.css"/> 2
1 The main Atomic script.
2 The default Atomic stylesheet. While this import is optional, if you don’t import it you’ll need to define its variables yourself.

Initializing the Atomic search interface

Before you can begin searching content, you must connect your search page to your Coveo organization. Do so within the <head> tag of the search page.

<head>
  <!-- ... -->
  <script>
    (async () => {
      await customElements.whenDefined('atomic-search-interface');
      const searchInterface = document.querySelector('#search');

      await searchInterface.initialize({
        accessToken: '<ACCESS_TOKEN>', 1
        organizationId: '<ORGANIZATION_ID>', 2
        renewAccessToken: <CALLBACK>, 3
      });
​
      searchInterface.executeFirstSearch();
    })();
  </script>
  <!-- ... -->
</head>
1 <ACCESS_TOKEN> (string) is a search token or an API key that grants the Allowed access level on the Execute Queries domain and the Push access level on the Analytics Data domain in the target organization.
Important

We strongly recommend that the access token enforces a searchHub value. See Defining the search hub in the authentication for more details.
2 <ORGANIZATION_ID> (string) is the unique identifier of your Coveo organization (for example, mycoveoorganizationa1b23c).
3 <CALLBACK> (function) returns a new access token, usually by fetching it from a backend service that can generate search tokens. The engine will automatically run this function when the current access token expires (that is, when the engine detects a 419 Authentication Timeout HTTP code).
Note

You don’t need to specify a renewAccessToken callback if your application is using API key authentication. This is typically not recommended, but can be legitimate in some scenarios.

Building your search interface

A Coveo Atomic search interface builds search pages by attaching components to target HTML elements. These components add functionality to your search interface. Some of the important components are highlighted in the example below.

Atomic components illustration 
<body>
    <atomic-search-interface search-hub="<SEARCH_HUB>"> 1
      <atomic-search-layout mobile-breakpoint="800px">
        <atomic-layout-section section="search">
          <atomic-search-box></atomic-search-box> 2
        </atomic-layout-section>

        <atomic-layout-section section="facets">
          <atomic-facet-manager> 3
            <atomic-facet field="cat_gender" label="Gender"></atomic-facet>
            <atomic-facet field="store_name" label="Store"></atomic-facet>
            <!-- ... -->
          </atomic-facet-manager>
        </atomic-layout-section>

        <atomic-layout-section section="main">
          <!-- ... -->
          <atomic-layout-section section="results">
            <atomic-result-list image-size="large" display="grid">
                <atomic-result-template> 4
                    .
                    .
                    .
                </atomic-result-template>
            </atomic-result-list>
          </atomic-layout-section>
          <atomic-layout-section section="pagination" style="flex-direction: column">
            <atomic-results-per-page choices-displayed="3,5,8,10"></atomic-results-per-page> 5
            <atomic-load-more-results></atomic-load-more-results> 6
          </atomic-layout-section>
        </atomic-layout-section>
      </atomic-search-layout>
    </atomic-search-interface>
</body>

Some essential components include:

Atomic component Description

1. atomic-search-interface

The parent of all other atomic components in the search page.

<atomic-search-interface></atomic-search-interface>

Notice that this is where you would define a <SEARCH-HUB> to name your component (for example, my search hub). This value is used as your interface’s identifier and will be sent along with each queries and usage analytics events originating from this component. See About the search hub for more information on search hubs.

2. atomic-search-layout

Helps organize elements on the search page. Has the mobileBreakpoint property which specifies when layout switches from mobile to desktop.

<atomic-search-layout></atomic-search-layout>

3. atomic-layout-section

Allows the identification of various sections of an Atomic page. Acts as a container

<atomic-layout-section section="search"></atomic-layout-section>

4. atomic-facet-manager

Helps reorder facets. Acts as a container for facet components.

<atomic-facet-manager></atomic-facet-manager>

5. atomic-facet

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

<atomic-facet field="author" label="Authors"></atomic-facet>

6. atomic-result-list

Responsible for displaying query results.

<atomic-result-list></atomic-result-list>

There’s another essential functionality which isn’t visible in the search interface example provided above: Atomic Usage Analytics. Atomic records usage analytics events performed in the search interface to feed Coveo Machine Learning (Coveo ML) models and to create UA reports.

For more details, to customize or send your own UA events, see Atomic Usage Analytics.

What’s next?

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

You may want to follow up by going through the Coveo Atomic tutorial 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 ecommerce solution or website.

For more examples, have a look at the interactive ones below: