-
Tutorials
- 0: Environment Setup
- 1: Basic Configuration, Options, and Markup
- 2: Interact With the Search Interface and Component Instances
- 3: Understanding the Event System
- 4: Modify the Query
- 5: Result Templates
- 6: Usage Analytics
- 7: Interact With Component States
- 8: Configure Your Own Search Endpoint
- 9: Advanced Integration With Custom TypeScript Component (Configuration)
- 10: Advanced Integration With Custom TypeScript Component (Implementation)
JavaScript Search Framework Tutorial 1: Basic Configuration, Options, and Markup
In this tutorial, you’ll first review each individual section of the index.html
file to get a better understanding of how the Coveo JavaScript Search UI is configured.
Next, you’ll find answers to some of the most frequently asked questions about component options.
Finally, a few exercises will help you become more familiar with the most basic concepts behind the Coveo JavaScript Search Framework.
If you want to actively follow this tutorial, you should open the ./bin/index.html
file in the text editor or IDE of your choice.
Header Resources
The index.html
file header contains all required resources for the basic framework to operate, as well as a few extra JavaScript and CSS files that will be used only in this tutorial.
<!-- This is the default CSS offered by Coveo for the UI. -->
<link rel="stylesheet" href="css/CoveoFullSearch.css"/>
<!-- This is some extra CSS used only in this tutorial. -->
<link rel="stylesheet" href="css/coveoextension.css"/>
<!-- This is the JavaScript file that includes the entire framework. -->
<!-- It will populate the "Coveo" namespace in the browser. -->
<!-- Note that it's loading the Lazy version of the framework, not the Eager. -->
<!-- For more information on the differences between both, see https://docs.coveo.com/en/295/javascript-search-framework/lazy-versus-eager-component-loading. -->
<script src="js/CoveoJsSearch.Lazy.js"></script>
<!-- This is an extra JavaScript file used only in this tutorial. -->
<script src="js/coveo.extension.js"></script>
<!-- This is the "default" result template. -->
<!-- It will be used by the UI when no custom template has been specified. -->
<script src="js/templates.js"></script>
Initialization Script
This script initializes a working search interface by first configuring an endpoint (an index) against which to execute queries, and then by targeting a root element under which all search components should be placed.
<script>
// Wait until all resources have been loaded and page is ready before executing initialization.
document.addEventListener('DOMContentLoaded', function () {
// The Coveo JavaScript Search UI comes with a pre-configured public search endpoint
// (a public index against which to execute queries for demo purposes).
Coveo.SearchEndpoint.configureSampleEndpointV2();
// Initialize the UI by targeting a root element.
Coveo.init(document.body);
})
</script>
Some additional information about the initialization script follows.
-
The sample endpoint is a public Coveo Cloud endpoint for which we use a hardcoded API key. It comes fully configured with different source types. You’ll learn how to create and use your own search endpoint in JavaScript Search Framework Tutorial 8: Configure Your Own Search Endpoint).
A search endpoint is an object whose interface allows the JavaScript Search Framework to perform HTTP requests against the Search API (see REST Search API Home).
This tutorial will focus on using a cloud endpoint, as it’s the most frequent use case.
-
The
Coveo.init
method will target an element and scan for all available components. Each recognized component will then instantiate itself (i.e., its constructor function will be executed).Components are the base unit of your search interface. A component is typically responsible for a single concern or user-facing feature. Available components include the
Searchbox
, theResultList
, thePager
, etc.Each component can be added once or many times, or removed from your search interface.
A list of all available components can be found on the reference documentation site on GitHub (see Coveo JavaScript Search Framework - Reference Documentation).
Some components are straightforward and can easily be mapped to visual widgets in the interface. Some others are more subtle or advanced. You shouldn’t worry about understanding all available components for now.
Configuration Using HTML
You can configure each component using the HTML.
<!-- Each DOM element with a class starting with "Coveo" (uppercase) will instantiate a component. -->
<body id="search" class='CoveoSearchInterface'>
<!-- Each DOM element with a class starting with "coveo-" (lowercase) is for CSS or alignment purpose only. -->
<div class='coveo-search-section'>
<!-- Note that any Coveo component can be removed (or added); none is actually required for the page to load. -->
<div class="CoveoSearchbox"></div>
</div>
<!-- The "data-" attributes of each component allow you to set options for a specific instance of that component. -->
<div class="CoveoFacet" data-title="Author" data-field="@author" data-tab="All"></div>
<div class="CoveoFacet" data-title="Year" data-field="@year" data-tab="All"></div>
</body>
Here is some additional information about configuration through the HTML:
- Each time you see a DOM element with a class starting with
Coveo
(with a capital “C”), you can assume that this element will instantiate a component. You can be almost certain that after theCoveo.init
function has been called, the DOM element will be modified and will generate a different markup. - Each time you see a DOM element with a class starting with
coveo-
(lowercase “c”), you can assume that this element won’t instantiate a component. It will only be used by the base CSS file, which is included in the Coveo JavaScript Search UI. - If you want to change the position of any component within your page, you’ll most likely have to move the corresponding DOM elements.
- The
data-
attributes you see in some components are options for a specific instance of this component.
If you understand these concepts, you should also be able to roughly understand what happens when the Coveo.init
method is executed:
These steps describe how Lazy loading works. To learn how Eager loading works, see Lazy Versus Eager Component Loading.
- Starting from the root element specified in the
Coveo.init
call, the framework will scan the DOM for any DOM element that matches a well-known CSS class (e.g.,CoveoFacet
→ instantiate a Facet component,CoveoSearchbox
→ instantiate a Searchbox component, etc.) and download its appropriate code. - After having downloaded the code of a component, its constructor function is called. This is done asynchronously for each component detected on your page.
- Once a component has been initialized, the framework parses its
data-
attributes, and sets those option values to the component. - Each component will bind event handlers in their constructor function to interact with the event system of the framework (see JavaScript Search Framework Tutorial 3: Understanding the Event System).
More Information on Options
This section contains answers to some of the most frequently asked questions about component options.
-
Q: Where can I find a list of all possible options for each component?
-
A: Reference documentation for all components is available on GitHub (see Coveo JavaScript Search Framework - Reference Documentation). You shouldn’t try to understand all possible options for now. However, you should know that the reference documentation will prove to be an invaluable source of information when you’re looking for possible features to implement.
A
Facet
is one of the most complex components and it contains many different options, each of which is described in the reference documentation.
-
-
Q: How can an option name from the reference documentation be applied to a markup configuration?
-
A: The syntax is always the same: First, you have to add
data-
before the option name. Then, for each capital letter in the option name, make that letter lowercase and add a dash (-
) before it.The
enableFacetSearch
option of theFacet
component becomesdata-enable-facet-search
in the markup.
-
-
Q: How can I know the possible values for a specific option?
-
A: In the reference documentation, you can find which type is accepted by any given option. The following table shows the possible values for each type. It also displays examples of option component markup configuration.
Type Option Component Example Possible Values Markup Configuration Example boolean enableFacetSearch
option of theFacet
componenttrue
orfalse
data-enable-facet-search="true"
string title
option of theFacet
componentAny string of characters data-title="foo"
number numberOfValues
option of theFacet
componentAny integer of float number
data-number-of-values="1"
Array<T> allowedValues
option of theFacet
componentA comma separated list of values of type T (e.g., an Array<string> contains values of type string) data-allowed-values="foo,bar,baz"
HTMLElement resultContainer
option of theFacet
componentA CSS selector which allows targeting of a HTML element in the DOM data-result-container-selector="#A_HTML_ID"
-
Exercises
- All exercises in this section should be done by modifying the tutorial search page under
./bin/index.html
. The exercises shouldn’t be done by modifying the original search page under./pages/index.html
. - To actually see the results in your demo page, you must be running a webpack-dev-server (see JavaScript Search Framework Tutorial 0: Environment Setup).
-
In the
./bin/index.html
file, find theHelloWorld
component and remove it. Save your work and reload your demo page at http://localhost:3000. TheHello World
message should now be gone from the top of the page.Solution
[ ... ] <body id="search" class='CoveoSearchInterface' data-enable-history="true" data-design="new"> <!-- The following line should be removed. --> <div class="CoveoHelloWorld"></div> <div class="coveo-tab-section"> <a class="CoveoTab" data-id="All" data-caption="All Content"></a> </div> [ ... ]
-
Find the
coveo-facet-column
and add a newFacet
with"Source"
as a title and"@source"
as a field. Save your work and reload your demo page at http://localhost:3000. A new facet titledSource
should appear.Solution
[ ... ] <div class="coveo-facet-column"> <!-- The following line should be added. --> <div class="CoveoFacet" data-title="Source" data-field="@source" data-tab="All"></div> <div class="CoveoFacet" data-title="Type" data-field="@objecttype" data-tab="All"></div> <div class="CoveoFacet" data-title="FileType" data-field="@filetype" data-tab="All"></div> <div class="CoveoFacet" data-title="Author" data-field="@author" data-tab="All"></div> <div class="CoveoFacet" data-title="Year" data-field="@year" data-tab="All"></div> <div class="CoveoFacet" data-title="Month" data-field="@month" data-tab="All"></div> </div> [ ... ]
-
Modify the
Tab
component so that its caption becomes"Everything"
. Save your work and reload your demo page at http://localhost:3000. The tab should now contain a different caption.Solution
[ ... ] <div class="coveo-tab-section"> <!-- The following line should be modified --> <a class="CoveoTab" data-id="All" data-caption="Everything"></a> </div> [ ... ]
What’s Next?
You should now proceed to JavaScript Search Framework Tutorial 2: Interact With the Search Interface and Component Instances.