Components

This is for:

Developer

Components are the building blocks of a Coveo JavaScript Search Framework search interface. They render widgets such as a Searchbox (into which end users enter queries), or a Facet on a particular field (allowing end users to easily filter results). Some components are containers, such as the ResultList in which returned search results are displayed. Others appear only when triggered, such as FieldSuggestions, which appear below the Searchbox as end users type a query. You can build a search interface by arranging the components you want to use as you see fit.

During the initialization of the search interface, components are automatically attached to HTML elements that have a specific CSS class.

Most components have a variety of options, and many expose methods and events for further customization.

  • The SearchButton component can be used with any clickable element (such as an <a> tag or an <input type="button">). It causes a new query to be executed every time the end user clicks the element.

  • The Querybox component is used with a textbox element (such as <div type="text"/>). When a query is executed, it automatically adds the search keywords entered in the textbox to the query, which is then sent to the Search API.

Available components

The Coveo JavaScript Search Framework became an open source package in July 2016 and the reference documentation site is now generated from documentation embedded in the source code.

You can find the list of all available components and their associated documentation on GitHub.

Creating component instances

Automatic initialization

Most of the time, components are automatically created when the init function is invoked during the initialization of the search interface. At this point, all of the HTML elements under the specified root element are scanned, and the proper components are initialized for every element that has a CSS class associated with a component. The name of the CSS class is the component name prefixed with Coveo (for example, CoveoSearchButton).

When the init function is executed, the element <a class="CoveoSearchButton"> will create a SearchButton component and attach it to that element.

Manual initialization

Although it’s rarely necessary to do so, you can manually create components and bind them to HTML elements.

To do this, you can call the constructor of the component you want to instantiate, passing the HTML element(s) on which you want to bind this component as an argument. You can also pass configuration options as an argument when calling a component constructor.

You can also use the jQuery extension, calling the coveo extension on a selector matching the element(s) on which you want to create components, and passing the name of the desired component as an argument. You can also pass options as a second argument to this call.

Consider the following markup:

<div id="search" class="CoveoSearchInterface">
  <div class="coveo-tab-section">
    <a id="myElement"></a>
  </div>
</div>

Executing the following script instantiates a Tab component with Don't Panic as a caption, 42 as an id and @author=="Douglas Adams" as an expression on the element that matches the #myElement CSS selector:

const myElement = document.getElementById("myElement");
​
const options = {
  caption: "Don't Panic",
  id: "42",
  expression: "@author==\"Douglas Adams\""
};
​
new Coveo.Tab(myElement, options);

You can achieve the same result using the jQuery coveo extension:

$("#myElement").coveo("Tab", options);

When initializing a component manually in lazy mode, you must use the load top-level function to ensure that the component code is available (see Interacting with lazy components):

// ...
Coveo.load("Tab").then((Tab) => {
  new Coveo.Tab(myElement, options);
});

Configuring components

Most components have a number of options that can be passed during initialization.

Using attributes

You can specify options by using custom attributes on an HTML element that’s bound to a component.

The name of the attribute is the option name, in lower case, prefixed by data- and with each word separated by a dash.

On the HTML element of a Searchbox component, you can set the enableSearchAsYouType option to true using the data-enable-search-as-you-type attribute:

<input type="text" class="CoveoSearchbox" data-enable-search-as-you-type="true"/>

Passing component options in the init Call

You can configure a component by passing its options to the init top-level function call. You can also configure a specific component in the init call by referring to its HTML id attribute.

If you specify a component option in both the markup and the init call, the markup option overrides the one in the init call.

Consider the following markup:

<body id="search" class="CoveoSearchInterface">
  <div class="coveo-search-section">
    <div class="CoveoSearchbox"></div>
  </div>
  <div class="coveo-main-section">
    <div class="coveo-result-column">
      <div class="coveo-result-layout-section">
        <span class="CoveoResultLayoutSelector"></span>
      </div>
      <div class="CoveoResultList" data-layout="list" data-enable-infinite-scroll="false"></div>
      <div id="myCardResultList" class="CoveoResultList" data-layout="card"></div>
    </div>
  </div>
</body>

With the following script, the init function sets the enableSearchAsYouType option to true on the Searchbox it finds under the root element. It also sets the enableInfiniteScroll and autoSelectFieldsToInclude options to true on both of the ResultList components it finds.

Therefore, in the following example, the resulting enableInfiniteScroll option is false for the ResultList whose layout is list, whereas it’s true for the ResultList whose layout is card.

document.addEventListener("DOMContentLoaded", () => {
  Coveo.SearchEndpoint.configureSampleEndpointV2();

  const mainSearchInterface = document.getElementById("search");

  Coveo.init(mainSearchInterface, {
    Searchbox: {
      enableSearchAsYouType: true
    },
    ResultList: {
      enableInfiniteScroll: true,
      autoSelectFieldsToInclude: true
    }
  });
});

If you specify options for both a component type and a specific id that refers to a component of that type, the JavaScript Search Framework merges these options, prioritizing the options you specify by id.

In the following code sample, the resulting waitAnimation of the ResultList whose id is myCardResultList is spinner, its enableInfiniteScroll and autoSelectFieldsToInclude are both true, and its infiniteScrollPageSize is 15.

document.addEventListener("DOMContentLoaded", function() {
  Coveo.SearchEndpoint.configureSampleEndpointV2();
  const root = document.getElementById("search");
  Coveo.init(root, {
    ResultList: {
      enableInfiniteScroll: true,
      waitAnimation: "fade",
      autoSelectFieldsToInclude: true
    },
    myCardResultList: {
      waitAnimation: "spinner",
      infiniteScrollPageSize: 15
    }
  });
});

Passing component options before the init call

When you’re working on a hosted search page or Coveo for Salesforce search page, you can’t directly access the init call of your search interface. However, you can pass component configuration options before the init call by using the options top-level function.

Consider the following markup:

<div id="search" class="CoveoSearchInterface">
  <div id="fileTypeFilter" class="CoveoFacet" data-field="@filetype" data-title="File Type"></div>
</div>

The following script would make the fileTypeFilter facet display normalized facet value captions:

const root = document.getElementById("search");
const fileTypeFilterValueCaptions = {
  // ...
  "html": "Web pages",
  "txt": "Text files",
  "zip": "ZIP files"
};
Coveo.options(root, {
  fileTypeFilter: {
    valueCaption: fileTypeFilterValueCaptions
  }
});

Initializing components external to your CoveoSearchInterface

Sometimes, it can be useful to have a component that’s outside of your main search interface. For example, you may want to include a search box in your page header and bind it to a search interface in another section of your page.

Suppose you have the following two components:

<div class="CoveoSearchbox" id="myStandaloneSearchbox"></div>
<div class="CoveoSearchInterface" id="myMainSearchInterface"></div>

You could initialize your external search box as follows:

document.addEventListener("DOMContentLoaded", () => {
  Coveo.SearchEndpoint.configureSampleEndpointV2();

  const standaloneSearchbox = document.getElementById("myStandaloneSearchbox");
  const mainSearchInterface = document.getElementById("myMainSearchInterface");

  Coveo.init(mainSearchInterface, {
    externalComponents: [
      standaloneSearchbox
    ]
  });
});

Your search box would then be linked to your search interface. Note that the externalComponents option accepts an array of jQuery objects. Each component in this array will be initialized after components that are direct children of the search interface.

Using child elements

You can configure some components by using a child HTML element with a special CSS class. This is typically used for result templates.

You can specify options for the ResultList component using a template annotated with the result-template class.

<div class="CoveoResultList">
  <script id="myTemplate" type="text/html" class="result-template">
    <!-- ... -->
  </script>
</div>

Changing options after initialization

The JavaScript Search Framework doesn’t currently support changing options after component initialization.

Calling methods on components

Some components expose methods that you can use to perform certain actions. You can use the get top-level function to retrieve the component instance whose method you want to execute.

The ResultList component has a displayMoreResults method that causes it to fetch and display additional results after the ones that are already displayed.

You can call this method as follows:

const resultListElement = document.getElementById('#myResultList');
let resultListInstance = Coveo.get(resultListElement);
resultListInstance.displayMoreResults(10);

You can also achieve similar results using the jQuery extension:

$('#myResultList').coveo('displayMoreResults', 10);

  • The jQuery selector in the expression must match an element that’s bound to a component that exposes the requested method. The first argument to the coveo jQuery extension is the name of the method to invoke, followed by its arguments.

    The call to the jQuery extension returns the method return value, if one exists. If not, the selector itself is returned to allow method chaining, as is typical with jQuery.

  • If several elements match the selector, the method will be invoked on all of them, and the return value will be that of the first invocation.

What’s next?

Articles in this section: