Develop and Deploy Hosted Search Pages With Coveo Turbo

Creating a hosted search page that taps into the content you have indexed is the centerpiece of the Coveo implementation. Ultimately, you will insert, in an AEM page, the Coveo Hosted Search Page component whose role is to retrieve the HTML code of a hosted search page.

The Coveo Turbo CLI-based tool lets you develop locally and then deploy search pages to a Coveo organization as hosted search pages. Coveo Turbo is geared to be used with the Coveo Hosted Search Page component.

Coveo Turbo

If creating hosted search pages directly from the Coveo Platform in a trial organization, ensure you create a classic hosted search page as illustrated below. Otherwise, your hosted search page will be incompatible with Coveo Turbo and the Coveo Hosted Search Page component.

How to create a classic hosted search

Development Environment Setup

Before using Coveo Turbo for your Coveo search solution development, you need to set up your environment.

The content in this section assumes your developers will collaborate and push changes to their search pages into your Coveo sandbox organization (which should be a part of your UAT environment). This setup ensures optimal team productivity and access to representative indexed data, while limiting the extent to which the developers can access and modify content and configurations in the sandbox organization.

Accordingly, some preliminary setup steps below are specifically assigned to a lead developer or administrator having administrator privileges in the sandbox organization (and hereafter referred to as the Administrator).

Installing Node JS and NPM

To install Coveo Turbo, you need a Node JS environment with npm. You can download and install both from the node.js website. Coveo Turbo requires at least version 12 of Node.js.

Installing the Coveo Turbo CLI

To install the CLI, use the following command:

npm install --save-dev @coveops/cli

Creating an API Key in Your Coveo Sandbox Organization (Administrator)

To create the API key

  1. Access the API Keys page of the Coveo Administration Console.

  2. Click Add key.

  3. In the Add an API key panel, in the Configuration tab, provide a Key name.

  4. In the Privileges tab, provide the following access levels:

    Domain Resource Access level

    Content

    Fields

    View

    Content

    Sources

    View all

    Search

    Execute queries

    Allowed

    Search

    Search pages

    Edit all

  5. Click Add key.

Creating a Coveo Turbo Project With a Search Page (Administrator)

You can create a new Coveo Turbo project including a basic search page as follows:

  1. Open your preferred code editor.

  2. Create a new folder to serve as your Coveo Turbo project repository root folder.

  3. From the root of your Coveo Turbo repository, run:

    coveops create:project <NEW_COMPONENT_NAME> --create-component --with-styles --with-page

    Replace <NEW_COMPONENT_NAME> with your component name.

    An empty component definition is required by the create:project command to be able to deploy the search page later on in the process. We won’t use the component definition or make any changes to the generated .ts files for the remainder of the process.

    Coveo Turbo CLI commands may be invoked in a number of ways, whether the CLI is installed globally or as a dev dependency (see CLI command usage).

Among other items, the create:project command creates:

  • the necessary project files

  • a basic search page (pages\index.html)

  • a new component .ts file in the src

    and

  • the component stylesheet .scss files in the src\stylesheets folder

Contents of created project

Setting Project Environment Variables (Administrator)

Coveo Turbo lets you serve, browse, and test a local Coveo search page. Having representative items to work with eases the testing of your local Coveo-powered search page. To do so, you want your project to connect to your sandbox Coveo organization and to share connection configurations among developers.

  1. In the .env.dist file, set values for the COVEO_ORG_ID and COVEO_TOKEN environment variables. For Coveo organizations not in the US deployment region, additional environment variables must be initialized (see Deploy to Another Region or HIPAA).

  2. Copy the content of the .env.dist file into the .env file.

  3. In the .env file, change the SERVER_PORT value, if necessary.

To properly emulate a specific search interface, your developers will need to set the corresponding COVEO_SEARCH_HUB value in their .env file (see Set the Search Hub). Ensure you provide them with the necessary search interface search hub values.

It’s now time to set up a repository for the project to version control your search page and stylesheet code.

Search Page Development

Coveo Turbo is very convenient in the way it lets you add Coveo JavaScript Search Framework components to a search page, view, style, and test that search page locally.

Adding and Configuring Search Page Components

Adding and configuring a Coveo JavaScript Search Framework component to a search page, as you may see in the pages/index.html search page, is a matter of:

  • adding an HTML tag with the component-specific and Coveo-prefixed CSS class in the search page (e.g., <div class="CoveoSearchbox"></div>)

    and

  • configuring the component using element attributes whose names are the component option name, in lower case, prefixed by data- and with each word of the component option separated by a dash (e.g., <div class="CoveoSearchbox" data-enable-omnibox="true"></div>).

For the list of Coveo JavaScript Search Framework components and their component options, see Coveo JavaScript Search Framework - Reference Documentation. For general information on Coveo JavaScript Search Framework component usage, see JavaScript Search Framework Components

Should you want to create and edit other search pages, you can add a search page to your project using the Coveo Turbo Create a Page command.

Testing a Search Hub

Coveo search query results and their order in a result list depend on the search hub each search query is tagged with. To properly emulate and test a specific search interface, you need to set the corresponding COVEO_SEARCH_HUB value in your .env file (see Set the Search Hub). Your administrator should provide you with the necessary search hub value(s) and details as to expected search result patterns when targeting a given search hub.

Applying Stylesheets

For your search page stylesheets, Coveo Turbo lets you either:

  • target CSS files on your corporate website by adding <link rel="stylesheet"> tags in the search page <head> section

    or

  • add your search page styling in the src/stylesheets/<NEW_COMPONENT_NAME>.scss file.

There’s no need to add any CSS-related import statement to your component .ts file. The src/stylesheets/index.scss file handles this for you.

Configuring Result Templates

Hosted search pages let you use prebuilt Coveo JavaScript Search Framework result templates or design your own. You can assign conditions to result templates. For each result to a query, the Coveo JavaScript Search Framework uses its condition evaluation mechanism to determine which result template to use (see JavaScript Search Framework Result Templates).

Building the Project

Building the project creates a dist folder with the compiled .js and .css files.

coveops build <NEW_COMPONENT_NAME>

Replace <NEW_COMPONENT_NAME> with your component name.

Serving the Search Page Locally

The Coveo Turbo serve command starts a Node server designed to browse any of the HTML pages in the pages folder of your project. The compiled distributable may be used in those pages as a static resource.

EXAMPLE

The following command serves your project pages on http://localhost:<SERVER_PORT>/, where <SERVER_PORT> is the value of the SERVER_PORT variable specified in your .env file.

coveops serve

Deploying a Search Page to Your Sandbox Coveo Organization

Coveo Turbo HTML search pages may be deployed to a Coveo organization as hosted search pages. When running the deploy command, you should specify the source name (i.e., the file name of the search page in your project) and the target name (i.e., the name of the hosted search page in your Coveo organization) as arguments. If a hosted search page with the target name already exists in your Coveo organization, it gets overwritten.

EXAMPLE

The following command deploys the pages/index.html page in your project to create or update a hosted search page called newplatformpage in your Coveo organization.

coveops deploy index newplatformpage

You can ensure your search result hyperlink URLs reflect your public site DNS by having the host name part of your document URLs recomputed at query time. This requires a litte adjustment to your search page code.

To modify the hosted search page code in Coveo Turbo

  1. Open the HTML search page located under \pages in your preferred editor.

  2. Adjust the code triggered by the DOMContentLoaded event as follows:

      document.addEventListener("DOMContentLoaded", function() {
        const publicHostname = window.location.protocol + '//' + window.location.hostname;
        let publicItemUrl;
        root = document.querySelector("#search");
        Coveo.$$(root).on("preprocessResults", function(e, args) {
          args.results.results.forEach(function(result) {
            publicItemUrl = result.clickUri.replace("<HOSTNAME_TO_CHANGE>", publicHostname);(1)
            result.clickUri = publicItemUrl;
            result.printableUri = publicItemUrl;
          });
        });
        ...

    1 Replace "<HOSTNAME_TO_CHANGE>" with the protocol and host name of your indexed items (e.g., https://development). To target multiple host names, replace "<HOSTNAME_TO_CHANGE>" with a variable and set its value using the JavaScript regular expression match() method prior to this line.

You can also make this code adjustment directly in your Coveo Platform hosted search page.

To modify the hosted search page code in the Coveo Platform

  1. Open the hosted search page in the Interface Editor.

  2. At the top of the page, select the CODE VIEW tab.

  3. Add the following <script> block after the final closing </div> tag:

    <script>
      document.addEventListener("DOMContentLoaded", function() {
        const publicHostname = window.location.protocol + '//' + window.location.hostname;
        let publicItemUrl;
        root = document.querySelector("#search");
        Coveo.$$(root).on("preprocessResults", function(e, args) {
          args.results.results.forEach(function(result) {
            publicItemUrl = result.clickUri.replace("<HOSTNAME_TO_CHANGE>", publicHostname);(1)
            result.clickUri = publicItemUrl;
            result.printableUri = publicItemUrl;
          });
        });
      });
    </script>

    1 Replace "<HOSTNAME_TO_CHANGE>" with the protocol and host name of your indexed items (e.g., https://development). To target multiple host names, replace "<HOSTNAME_TO_CHANGE>" with a variable and set its value using the JavaScript regular expression match() method prior to this line.

Search Page Deployment to Your Production Coveo Organization (Administrator)

Once a search page has undergone the necessary testing in your User Acceptance Testing (UAT) environment, you can apply the changes to the corresponding search page in your production Coveo organization. To do this, you have a couple of options:

  • You can push the search page from your Coveo Turbo project to your production Coveo organization. This entails having an API key set up with the necessary privileges in that Coveo organization (see Create an API Key in Your Coveo Sandbox Organization).

  • To copy one or multiple sandbox Coveo organization search pages along with other sandbox Coveo organization resource configurations to your production Coveo organization, Coveo provides a handy resource snapshot feature (see Manage Resource Snapshots).

What’s Next?

You’re now ready to install the Coveo for AEM package and add the Coveo Hosted Search Page component in an AEM page.

What's Next for Me?