-
Common Use Cases
- Provide Search Box Suggestions
- Create a Standalone Search Box
- Folding Results
- Change the Language of Your Search Interface
- Add ARIA Landmarks
- Send Custom Context Information
- Use Dynamic Facets
- Use Hierarchical Facets
- Normalize Facet Value Captions
- Request Specific Facet Range Values
- Define Dependent Facets
- Change the Behavior When a Result Link is Clicked
- Validate an Interface Is Machine Learning Ready
- Add Promoted Results Badges
Provide Search Box Suggestions
The JavaScript Search Framework supports different kinds of search box suggestions:
-
Coveo Machine Learning Query Suggestions (recommended)
-
Coveo JavaScript Search Framework 2.4094.8 (May 2018) Facet value suggestions
-
Field suggestions (not recommended)
Providing Coveo Machine Learning Query Suggestions
The Coveo Machine Learning (Coveo ML) Query Suggestions (QS) feature can recommend contextually relevant queries based on previously recorded usage analytics data.
To leverage this feature in a search interface:
-
Use the
Searchbox
component to initialize anOmnibox
.Unless you’re configuring a standalone search box, you should also initialize an
Analytics
component.<div id="search" class="CoveoSearchInterface"> <div class="CoveoAnalytics" data-search-hub="CommunitySearch"></div> <div class="coveo-search-section"> <div class="CoveoSearchbox"></div> </div> </div>
- Create a QS model.
-
Associate the QS model with the query pipeline which processes search requests originating from the search interface.
If the search box is still providing no query suggestions, ensure that enough usage analytics data is available to feed your QS model.
Requesting Query Suggestions Only When the Search Box Is Non-Empty
Coveo JavaScript Search Framework 2.6459 (July 2019)
By default, trending Coveo ML query suggestions are requested and rendered whenever focus is on the search box input.
To change this behavior, set the querySuggestCharacterThreshold
option of the Omnibox
component to a value greater than 0
.
The following configuration ensures that query suggestions only get rendered from the moment the end user starts entering a query in the search box.
<div class="CoveoSearchbox" data-query-suggest-character-threshold="1"></div>
Rendering Query Suggestion Result Previews
Pilot Feature in 2.7610 (December 2019)
In some search interfaces, particularly in the context of commerce, you may want to render previews of the most relevant results when focus is on a query suggestion.
To do so, your search interface must initialize a QuerySuggestPreview
component*.
*The QuerySuggestPreview
component is still a pilot feature, and it currently has some known issues:
-
It’s not compatible with field value suggestions.
-
Its default result template doesn’t work in Firefox (fixed in the March 2020 Release (v2.8521)).
-
It doesn’t support accessibility features (fixed in the March 2020 Release (v2.8521)).
With the following configuration, when focus is on a query suggestion for 200 milliseconds1, the QuerySuggestPreview
component requests the top three2 results matching the focused query, and renders those results using a simple default template3.
<!-- ... -->
<div class="CoveoQuerySuggestPreview"></div>
<div class="CoveoSearchbox"></div>
<!-- ... -->
</div>
1: See the executeQueryDelay
option.
2: See the numberOfPreviewResults
option.
3: See the Using Custom Query Suggest Preview Result Templates below.
Using Custom Query Suggest Preview Result Templates
To customize the way the QuerySuggestPreview
component visually renders results:
-
(Option 1) Use the
resultTemplate
option to specify a previously registered template to apply to all results.<div class="CoveoQuerySuggestPreview" data-result-template-id="qsp-template"></div> <!-- ... --> <script id="qsp-template" class="result-template" type="text/html"> <!-- ... --> </script>
OR
-
(Option 2) Embed a set of conditional templates inside the element bound to the
QuerySuggestPreview
component instance.This is essentially the same approach you would use to specify custom result templates for a
ResultList
component.If you use this approach, for each result to render, the first template whose condition is satisfied by the result will apply. Therefore, the last embedded template should typically have no condition, and be considered the default template.
<div class="CoveoQuerySuggestPreview"> <script id="qsp-template-products" class="result-template" type="text/html" data-field-documenttype="Product"> <!-- ... --> </script> <script id="qsp-template-services" class="result-template" type="text/html" data-field-documenttype="Service"> <!-- ... ---> </script> <script id="qsp-template-default" class="result-template" type="text/html"> <!-- ... --> </script> </div>
For more information on result templates, see JavaScript Search Framework Result Templates.
Providing Facet Value Suggestions
Coveo JavaScript Search Framework 2.4094.8 (May 2018)
You can use the FacetValueSuggestions
component to provide end users with scoped query suggestions based on the values of a specific facet-enabled field.
Basic Usage
The following code sample provides a minimal working example of a FacetValueSuggestions
component:
<!DOCTYPE html>
<html>
<head>
<!-- The component requires JS Search Framework v2.4094.8 or above -->
<link rel="stylesheet" href="https://static.cloud.coveo.com/searchui/v2.4094/css/CoveoFullSearch.css"/>
<script class="coveo-script" src="https://static.cloud.coveo.com/searchui/v2.4094/js/CoveoJsSearch.Lazy.min.js"></script>
<script>
document.addEventListener("DOMContentLoaded", () => {
Coveo.SearchEndpoint.configureSampleEndpointV2();
Coveo.init(document.getElementById("search"));
});
</script>
</head>
<body id="search" class="CoveoSearchInterface">
<div class="coveo-search-section">
<!-- See note 1 below -->
<div class="CoveoSearchbox">
<!-- See note 2 below -->
<div class="CoveoFacetValueSuggestions" data-field="@author"></div>
<!-- See note 3 below -->
<!-- <div class="CoveoFacetValueSuggestions"
data-field="@author"
data-use-query-suggestions="false"></div> -->
</div>
</div>
<div class="coveo-main-section">
<!-- See note 4 below -->
<div class="coveo-facet-column">
<div class="CoveoFacet" data-field="@author" data-title="Author"></div>
</div>
<div class="coveo-results-column">
<div class="CoveoResultList"></div>
</div>
</div>
<!-- See note 5 below -->
<!-- <div class="CoveoHiddenQuery"></div> -->
</body>
</html>
-
The
FacetValueSuggestions
component requires anOmnibox
to work. By default, theSearchbox
initializes anOmnibox
. -
Minimally, you must set the
field
option of aFacetValueSuggestions
component to the@
-prefixed name of a field whose Facet option is enabled (e.g.,data-field="@author"
). If the target field has high cardinality (i.e., if it has many possible values), you can enable its Use Cache for Nested Queries option to improve performance. You can initialize manyFacetValueSuggestions
components in the same search interface, as long as each instance references its own unique field. -
The
FacetValueSuggestions
component normally requires that theenableQuerySuggestAddon
option be set totrue
on theOmnibox
, which is the case by default. This implies that a Coveo ML QS model must be available in the target query pipeline. If these conditions aren’t satisfied, you must set theuseQuerySuggestions
option of eachFacetValueSuggestions
component tofalse
, or the components won’t work. -
While not mandatory, we recommend that you include a corresponding
Facet
for eachFacetValueSuggestions
component. This will allow end users to intuitively interact with the filters that apply when selecting a scoped query suggestion. -
If you can’t or don’t want to use facets in your search interface, include a
HiddenQuery
component instead. Otherwise, selecting a scoped query suggestion provided by aFacetValueSuggestions
component won’t have the desired effect, as no additional filter will be applied.
Providing Scoped Query Suggestions Based on a Multi-Value Field
Coveo JavaScript Search Framework 2.5395.12 (January 2019)
You can use the isCategoryField
and categoryFieldDelimitingCharacter
options of a FacetValueSuggestions
component to provide scoped query suggestions based on a field whose Multi-Value Facet option is enabled.
When you do so, we recommend that you include a corresponding CategoryFacet
in your search interface.
In your Coveo organization, you have created a source called Living Things. In that source, each item describes a specific plant or animal. The @simpletaxonomy
multi-value field gets populated by metadata representing the hierarchical categories to which each Living Things item belongs.
For example, the field value is:
-
Animals; Animals > Mammals;
for items describing dogs, cats, horses, etc. -
Animals; Animals > Birds;
for items describing parrots, eagles, crows, etc. -
Plants; Plants > Trees;
for items describing maples, oaks, firs, etc.
In your search interface, you configure a FacetValueSuggestions
component (and a CategoryFacet
) based on the @simpletaxonomy
field:
<div id="search" class="CoveoSearchInterface">
<div class="coveo-search-section">
<div class="CoveoSearchbox">
<div class="CoveoFacetValueSuggestions"
data-field="@simpletaxonomy"
data-is-category-field="true"
data-category-field-delimiting-character=" > "></div>
</div>
</div>
<div class="coveo-main-section">
<div class="coveo-facet-column">
<div class="CoveoCategoryFacet"
data-field="@simpletaxonomy"
data-title="Taxonomy"></div>
</div>
<div class="coveo-results-column">
<div class="CoveoResultList"></div>
</div>
</div>
</div>
Your Omnibox
can now provide scoped query suggestions similar to what’s shown in the following animation:
Using Custom Templates for Facet Value Suggestions (Not Recommended)
You can use the templateHelper
option of the FacetValueSuggestions
component to specify a custom template to apply when rendering scoped query suggestions in the Omnibox
.
You can’t set this option directly in the markup configuration of a FacetValueSuggestions
component; you must rather set it in the init
(or options
){:target=”_blank”} top-level function call (see Configuring Components).
When specified, the templateHelper
option must be set to a function that returns a string or template literal, and receives the following arguments:
-
A reference to the current
IFacetValueSuggestionRow
object. -
A reference to the
Omnibox
in which to render the scoped query suggestions.
Typically, the function should leverage some attributes of the first argument (e.g., keyword
, value
, etc.) to generate a template literal (which may contain HTML).
Consider the following markup:
<div id="search" class="CoveoSearchInterface">
<div class="CoveoHiddenQuery"></div>
<div class="coveo-search-section">
<div class="CoveoSearchbox">
<div id="authorFacetValueSuggestions" class="CoveoFacetValueSuggestions"
data-field="@author"
data-use-query-suggestions="false"></div>
<div id="filetypeFacetValueSuggestions" class="CoveoFacetValueSuggestions"
data-field="@filetype"
data-use-query-suggestions="false"></div>
</div>
</div>
</div>
You could specify a generic custom template function to execute when rendering suggestions for each FacetValueSuggestions
component:
Coveo.init(document.getElementById("search"), {
FacetValueSuggestions: {
templateHelper: (row, omnibox) => {
return `<strong>${row.keyword}</strong> where <strong>${row.field}=="${row.value}"</strong> (~${row.numberOfResults} results)`;
}
}
});
You could also specify a specific custom template function for each component instance by targeting its HTML id
attribute in the init
(or options
) top-level function call:
Coveo.init(document.getElementById("search"), {
authorFacetValueSuggestions: {
templateHelper: (row, omnibox) => {
return `<strong>${row.keyword}</strong> in items authored by <em>${row.value}</em>`;
}
},
filetypeFacetValueSuggestions: {
templateHelper: (row, omnibox) => {
const normalizedRowValues = {
"gmailmessage": "Gmail message",
"lithiummessage": "Khoros Community message",
"pdf": "PDF"
}
const normalizedRowValue = normalizedRowValues[row.value] || row.value;
return `<strong>${row.keyword}</strong> in ${normalizedRowValue}s`;
}
}
});
Providing Field Suggestions
Consider providing Coveo ML query suggestions rather than field suggestions, as the former yields better performance and relevance.
The FieldSuggestions
component can provide Omnibox
suggestions based on field values.
To enable basic field suggestions in a search interface:
-
Ensure that the search interface initializes an
Omnibox
component. -
Initialize a
FieldSuggestions
component in your search page, and set itsfield
option to the@
-prefixed name of the field on which you want to base the suggestions.
<div id="search" class="CoveoSearchInterface">
<div class="coveo-search-section"></div>
<div class="CoveoSearchbox"></div>
<div class="CoveoFieldSuggestions" data-field="@author"></div>
</div>
</div>
-
You can add several
FieldSuggestions
components in a search interface to provide query completion suggestions based on different fields. -
Ensure that the Facet option is enabled on each field you use to provide field suggestions (see Add or Edit a Field).