Coveo for Salesforce (V3.33) JavaScript Search component reference

In this article

Coveo for Salesforce comes with a set of JavaScript search user interface components. This article provides component API reference documentation that’s automatically generated from the source code.

Components

Components are the building blocks of the Coveo JavaScript Search Framework (see JavaScript Search Framework Components ).

AttachToCase Component

Component HTML element class: CoveoAttachToCase

The AttachToCase component is a Result Templates component that allows you to link a result to a Salesforce case.

When wanting to attach Knowledge articles, ensure that the sfkbid, sfkbversionnumber (legacy), sfversionnumber (express), and sflanguage fields are properly populated on the article (see Add/Edit Mapping for Cloud V2 and Managing Fields for a Source for Cloud V1).

<div class="CoveoAttachToCase"></div>

Options

Option

(type)

Description
displayText

(boolean)

Specifies if the component should include the Attach/Detach text. Default value is false.

<div data-display-text='true'/>
displayTooltip

(boolean)

Specifies if the component should include the Attach/Detach tooltip. Default value is false.

<div data-display-tooltip='true'/>
readonly

(boolean)

Specifies if the component should be in read only mode. When in read only mode, you cannot Attach or Detach results. The default value is false.

<div data-readonly='true'/>
recordType

Specified the current record type.

BoxdisplayText

(boolean)

Specifies if the component should include the Attach/Detach text. Default value is false.

<div data-display-text='true'/>
BoxdisplayTooltip

(boolean)

Specifies if the component should include the Attach/Detach tooltip. Default value is false.

<div data-display-tooltip='true'/>
Boxreadonly

(boolean)

Specifies if the component should be in read only mode. When in read only mode, you cannot Attach or Detach results. The default value is false.

<div data-readonly='true'/>
BoxrecordType

Specified the current record type.

Boxoptions

(object)

The possible options for AttachToCase

Boxoptions.displayText

(boolean)

Specifies if the component should include the Attach/Detach text. Default value is false.

<div data-display-text='true'/>
Boxoptions.displayTooltip

(boolean)

Specifies if the component should include the Attach/Detach tooltip. Default value is false.

<div data-display-tooltip='true'/>
Boxoptions.readonly

(boolean)

Specifies if the component should be in read only mode. When in read only mode, you cannot Attach or Detach results. The default value is false.

<div data-readonly='true'/>
Boxoptions.recordType

Specified the current record type.

Properties

Property

(type)

Description
bind

(ComponentEvents)

Allows the component to bind events and execute them only when it is enabled.

componentOptionsModel

(ComponentOptionsModel)

Contains the state of options for different components. Mainly used by ResultLink.

componentStateModel

(ComponentStateModel)

Contains the state of different components (enabled vs disabled). Allows to get/set values. Triggers component state event when modified. Each component can listen to those events.

disabled

(boolean)

A disabled component will not participate in the query, or listen to ComponentEvents.

logger

(Logger)

Allows component to log in the dev console.

queryController

(QueryController)

Contains the singleton that allows to trigger queries.

queryStateModel

(QueryStateModel)

Contains the state of the query. Allows to get/set values. Trigger query state event when modified. Each component can listen to those events.

root

(HTMLElement)

A reference to the root HTMLElement (the SearchInterface).

searchInterface

(SearchInterface)

A reference to the root of every component, the SearchInterface.

usageAnalytics

(IAnalyticsClient)

A reference to the Analytics.client.

ID

(string)

The static ID that each component need to be identified.
For example, SearchButton -> static ID : SearchButton -> className : CoveoSearchButton

constructor

Create a new Component. Resolve all IComponentBindings if not provided.
Create a new Logger for this component. Attach the component to the SearchInterface.

Boxbind

(ComponentEvents)

Allows the component to bind events and execute them only when it is enabled.

BoxcomponentOptionsModel

(ComponentOptionsModel)

Contains the state of options for different components. Mainly used by ResultLink.

BoxcomponentStateModel

(ComponentStateModel)

Contains the state of different components (enabled vs disabled). Allows to get/set values. Triggers component state event when modified. Each component can listen to those events.

Boxdisabled

(boolean)

A disabled component will not participate in the query, or listen to ComponentEvents.

Boxlogger

(Logger)

Allows component to log in the dev console.

BoxqueryController

(QueryController)

Contains the singleton that allows to trigger queries.

BoxqueryStateModel

(QueryStateModel)

Contains the state of the query. Allows to get/set values. Trigger query state event when modified. Each component can listen to those events.

Boxroot

(HTMLElement)

A reference to the root HTMLElement (the SearchInterface).

BoxsearchInterface

(SearchInterface)

A reference to the root of every component, the SearchInterface.

BoxusageAnalytics

(IAnalyticsClient)

A reference to the Analytics.client.

BoxID

(string)

The static ID that each component need to be identified.
For example, SearchButton -> static ID : SearchButton -> className : CoveoSearchButton

Boxconstructor

Create a new Component. Resolve all IComponentBindings if not provided.
Create a new Logger for this component. Attach the component to the SearchInterface.

Box Component

Component HTML element class: CoveoBox

The Box component represents the container that includes all the other box components. It inherits from a SearchInterface Component and supports all of its options.

<div class='CoveoBox'></div>

Options

Option

(type)

Description
enableAutomaticResponsiveMode

(boolean)

Whether the component should automatically adapt to the screen size. Default value is true.

<div data-enable-automatic-reponsive-mode="true"></div>
enableBoxStateHistory

(boolean)

Specifies if you wish to save and reload the Box state when the page is closed and reopened. This saves the current state of the current tab that is selected.

If set to false, the tab reverts to the default one on each page load.

If set to true, each time you reload the page, the last tab that you selected will be automatically selected.

Default value is true.

<div data-enable-box-state-history="true"></div>
excerptLength

(number)

Specifies the length (in characters) of the result text (excerpt) to display. Default value is 80.

Minimum value is 0.

<div data-excerpt-length="80"></div>
resultsPerPage

(number)

Specifies the number of results you want per page. Default value is 20.

Minimum value is 0.

<div data-results-per-page="20"></div>
useLocalStorageForBoxState

(boolean)

Specifies if you wish to use the local storage to save the box state. This means that the query state is only loaded on page load. Default value is true.

<div data-use-local-storage-for-box-state="true"></div>
withAnalytics

(boolean)

Specifies if the box should automatically include an analytics component. If you already have one on the page, then it is not added twice. However, setting it to false removes it from the page on initialization.

Default value is true.

<div data-with-analytics="true"></div>

Properties

Property

(type)

Description
disabled

(boolean)

A disabled component will not participate in the query, or listen to ComponentEvents.

logger

(Logger)

Allows component to log in the dev console.

responsiveComponents

(ResponsiveComponents)

Allows to get and set the different breakpoints for mobile and tablet devices. This is useful, amongst other, for Facet, Tab and ResultList

ID

(string)

The static ID that each component need to be identified.
For example, SearchButton -> static ID : SearchButton -> className : CoveoSearchButton

constructor

Creates a new SearchInterface. Initialize various singletons for the interface (e.g., usage analytics, query controller, state model, etc.). Binds events related to the query.

Coveo.ModalBUTTON

The button to use when creating a ModalBox

Coveo.ModalModalBox

Content of a ModalBox

Coveo.ModalModalbuttons

(HTMLElement)

The availables buttons (Ok, Apply, Cancel, etc.)

Coveo.ModalModalclose

The function that can be called to close the modal box. Note that this is also called by validation button such as APPLY, YES, etc.
Force close will close all open modalbox and skip the validation (if one was provided)

Coveo.ModalModalcontent

(HTMLElement)

The content itself

Coveo.ModalModalmodalBox

(HTMLElement)

The modalBox container itself

Coveo.ModalModaloverlay

(HTMLElement)

The overlay added on the body, which can be clicked to close the modalbox

Coveo.ModalModalwrapper

(HTMLElement)

The wrapper of the content

Coveo.ModalOptions

Possible options when creating a ModalBox

Coveo.ModalOptions.body

(HTMLElement)

Specify the content that you wish to put inside the modal box

Coveo.ModalOptions.buttons

(number)

The button you wish to create (Using BUTTON enum

Coveo.ModalOptions.className

(string)

Specify that you wish to add a prefix to the class name of the modal box container, to not clash with existing css in the page

Coveo.ModalOptions.fullscreen

(boolean)

Specify if you wish to open the modal box full screen. Default is false. If false, the modal box will fit the size of the content.

Coveo.ModalOptions.overlayClose

(boolean)

Specify if you wish to close the modal box when the overlay (black background) is clicked. Default is false.

Coveo.ModalOptions.sizeMod

The size for the modal box

Coveo.ModalOptions.title

Specify the title of the modal box

Coveo.ModalOptions.titleClose

(boolean)

Specify that you wish the modal box to close when the user click on the title. Default is false.

Coveo.ModalOptions.validation

Specify a validation function, which receives the button that was pressed.
If the validation function return true, the modal box closes, otherwise it stays open

BoxBody Component

Component HTML element class: CoveoBoxBody

The BoxBody component takes care of appending a ResultList Component and ensuring the correct CSS styles are applied so that infinite scrolling works properly. By default, the ResultList component is initialized with the following option:

enableInfiniteScroll: true;

When you wish to modify other options on the ResultList component, when initializing the framework, add the following code.

Remember to change #MyBox with the id of your CoveoBoxBody component, and 20 with the page size you wish to modify.

$('#MyBox').coveo('initBox', {
    BoxBody : {
        infiniteScrollPageSize : 20
    }
})

Use this component on your page this way:

<div class='CoveoBoxBody'></div>

Options

Option

(type)

Description
autoSelectFieldsToInclude

(boolean)

Specifies whether the ResultList should scan its result templates to discover which fields it must request to be able to render all results. Setting this option to true ensures that the Coveo Search API does not return fields that are unnecessary for the UI to function.

Default value is false, which means that for each result, the Coveo Search API returns all available fields (unless you specify a list of values in the fieldsToInclude option, in which case the Coveo Search API only returns those fields, if they are available).

Many interfaces created with the JavaScript Search Interface Editor explicitly set this option to true.

<div class="CoveoBoxBody" data-auto-select-fields-to-include="true"></div>
enableInfiniteScroll

(boolean)

Specifies whether the component should automatically load more results when the user has reached the bottom of the result list. Default value is true.

<div class="CoveoBoxBody" data-enable-infinite-scroll="true"></div>
enableInfiniteScrollWaitingAnimation

(boolean)

When the enableInfiniteScroll option is true, specifies whether to display the waitingAnimation while fetching additional results. Default value is true.

<div class="CoveoBoxBody" data-enable-infinite-scroll-waiting-animation="true"></div>
fieldsToInclude

(Object)

Specifies a list of fields to include in the query results. If you set the autoSelectFieldsToInclude option to true, the Coveo Search API returns the fields you specify for this option (if those fields are available) in addition to the fields which the ResultList automatically requests.

Otherwise, the Coveo Search API only returns the fields you specify for this option (if those fields are available), unless you leave this option undefined, in which case the Coveo Search API returns all available fields.

<div class="CoveoBoxBody" data-fields-to-include="@myFirstField,@mySecondField,@myNthField"></div>
infiniteScrollContainer

When the enableInfiniteScroll option is true, specifies the element that triggers fetching additional results when the end user scrolls down to its bottom. You can change the container by specifying its selector (e.g., data-infinite-scroll-container-selector='#someCssSelector').

By default, the framework uses the first vertically scrollable parent element it finds, starting from the ResultList element itself. A vertically scrollable element is an element whose CSS overflow-y attribute is scroll.

This implies that if the framework cannot find a scrollable parent, it uses the window itself as a scrollable container.

This heuristic is not perfect, for technical reasons. There are always some corner case CSS combination which the framework will not be able to correctly detect as 'scrollable'.

It is highly recommended that you manually set this option if you wish something else than the window to be the scrollable element.

<div class="CoveoBoxBody" data-infinite-scroll-container="myElement"></div>
infiniteScrollPageSize

(number)

If the enableInfiniteScroll option is true, specifies the number of additional results to fetch when the user scrolls down to the bottom of the infiniteScrollContainer. Default value is 10. Minimum value is 1.

<div class="CoveoBoxBody" data-infinite-scroll-page-size="10"></div>
resultContainer

(HTMLElement)

Specifies the element inside which to insert the rendered result templates. Performing a new query clears the content of this element.

You can change the container by specifying its selector (e.g., data-result-container-selector='#someCssSelector').

If you do not specify a value for this option, a div element will be dynamically created and appended to the result list. This element will then be used as a result container.

<div class="CoveoBoxBody" data-result-container="myElement"></div>
waitAnimation

(string)

Specifies the type of animation to display while waiting for a query to return. The possible values are:

  • fade: Fades out the current list of results while the query is executing.
  • spinner: Shows a spinning animation while the query is executing.
  • none: Use no animation during queries.

See also the waitAnimationContainer option.

Default value is none.

<div class="CoveoBoxBody" data-wait-animation="none"></div>
waitAnimationContainer

(HTMLElement)

Specifies the element inside which to display the waitAnimation. You can change this by specifying a CSS selector (e.g., data-wait-animation-container-selector='#someCssSelector').

Default value is the value of the resultContainer option.

<div class="CoveoBoxBody" data-wait-animation-container="myElement"></div>

Properties

Property

(type)

Description
bind

(ComponentEvents)

Allows the component to bind events and execute them only when it is enabled.

componentOptionsModel

(ComponentOptionsModel)

Contains the state of options for different components. Mainly used by ResultLink.

componentStateModel

(ComponentStateModel)

Contains the state of different components (enabled vs disabled). Allows to get/set values. Triggers component state event when modified. Each component can listen to those events.

disabled

(boolean)

A disabled component will not participate in the query, or listen to ComponentEvents.

logger

(Logger)

Allows component to log in the dev console.

queryController

(QueryController)

Contains the singleton that allows to trigger queries.

queryStateModel

(QueryStateModel)

Contains the state of the query. Allows to get/set values. Trigger query state event when modified. Each component can listen to those events.

root

(HTMLElement)

A reference to the root HTMLElement (the SearchInterface).

searchInterface

(SearchInterface)

A reference to the root of every component, the SearchInterface.

usageAnalytics

(IAnalyticsClient)

A reference to the Analytics.client.

ID

(string)

The static ID that each component need to be identified.
For example, SearchButton -> static ID : SearchButton -> className : CoveoSearchButton

constructor

Create a new Component. Resolve all IComponentBindings if not provided.
Create a new Logger for this component. Attach the component to the SearchInterface.

BoxCreateArticle Component

Component HTML element class: CoveoBoxCreateArticle

The BoxCreateArticle component allows the use of the Create Article button in the Coveo Insight Panel (see Adding a Create Article Button to the Insight Panel). Use this component inside the coveo-box-settings div.

<div class="coveo-box-settings">
    <a class="CoveoBoxCreateArticle" target="_blank">
    </a>
    ...
</div>

Options

Option

(type)

Description
articleTypeFilter

(Object)

Specifies the Knowledge Article types to offer as options when creating an article. By default, all the available Knowledge Article types are displayed.

<a class="CoveoBoxCreateArticle" data-article-type-filter="knowledge__kav,troubleshooting__kav"></a>
hidden

(boolean)

Specifies if the component should be hidden from the display. Default value is true.

<a class="CoveoBoxCreateArticle" data-hidden="true"></a>
openInPrimaryTab

(boolean)

Whether to open the created article in a primary tab or, when set to false, to open it in a sub tab. Default value is true.

<a class="CoveoBoxCreateArticle" data-open-in-primary-tab="false"></a>

Properties

Property

(type)

Description
bind

(ComponentEvents)

Allows the component to bind events and execute them only when it is enabled.

componentOptionsModel

(ComponentOptionsModel)

Contains the state of options for different components. Mainly used by ResultLink.

componentStateModel

(ComponentStateModel)

Contains the state of different components (enabled vs disabled). Allows to get/set values. Triggers component state event when modified. Each component can listen to those events.

disabled

(boolean)

A disabled component will not participate in the query, or listen to ComponentEvents.

logger

(Logger)

Allows component to log in the dev console.

queryController

(QueryController)

Contains the singleton that allows to trigger queries.

queryStateModel

(QueryStateModel)

Contains the state of the query. Allows to get/set values. Trigger query state event when modified. Each component can listen to those events.

root

(HTMLElement)

A reference to the root HTMLElement (the SearchInterface).

searchInterface

(SearchInterface)

A reference to the root of every component, the SearchInterface.

usageAnalytics

(IAnalyticsClient)

A reference to the Analytics.client.

ID

(string)

The static ID that each component need to be identified.
For example, SearchButton -> static ID : SearchButton -> className : CoveoSearchButton

constructor

Create a new Component. Resolve all IComponentBindings if not provided.
Create a new Logger for this component. Attach the component to the SearchInterface.

BoxCurrentSort Component

Component HTML element class: CoveoBoxCurrentSort

The BoxCurrentSort component is only meant as a utility to set the title on its BoxPopup Component container. Whenever the current sort changes, for instance when a user clicks on a new Sort Component, this component takes care of setting a new title on the BoxPopup Component. This component must be included inside a BoxPopup component.

<div class='CoveoBoxPopup'>
    <div class='CoveoBoxCurrentSort'></div>
    <div class="coveo-sort-section">
        [[sorts]]
    </div>
</div>

Properties

Property

(type)

Description
bind

(ComponentEvents)

Allows the component to bind events and execute them only when it is enabled.

componentOptionsModel

(ComponentOptionsModel)

Contains the state of options for different components. Mainly used by ResultLink.

componentStateModel

(ComponentStateModel)

Contains the state of different components (enabled vs disabled). Allows to get/set values. Triggers component state event when modified. Each component can listen to those events.

disabled

(boolean)

A disabled component will not participate in the query, or listen to ComponentEvents.

logger

(Logger)

Allows component to log in the dev console.

queryController

(QueryController)

Contains the singleton that allows to trigger queries.

queryStateModel

(QueryStateModel)

Contains the state of the query. Allows to get/set values. Trigger query state event when modified. Each component can listen to those events.

root

(HTMLElement)

A reference to the root HTMLElement (the SearchInterface).

searchInterface

(SearchInterface)

A reference to the root of every component, the SearchInterface.

usageAnalytics

(IAnalyticsClient)

A reference to the Analytics.client.

ID

(string)

The static ID that each component need to be identified.
For example, SearchButton -> static ID : SearchButton -> className : CoveoSearchButton

constructor

Create a new Component. Resolve all IComponentBindings if not provided.
Create a new Logger for this component. Attach the component to the SearchInterface.

BoxCurrentTab Component

Component HTML element class: CoveoBoxCurrentTab

The BoxCurrentTab component is only meant as a utility to set the title on its BoxPopup Component container. Whenever the current tab changes, for instance when a user clicks on a new Tab Component, this component takes care of setting a new title on the BoxPopup Component. This component must be included inside a BoxPopup component.

<div class='CoveoBoxPopup'>
    <div class='CoveoBoxCurrentTab'></div>
    <div class="coveo-tab-section">
        [[sorts]]
    </div>
</div>

Properties

Property

(type)

Description
bind

(ComponentEvents)

Allows the component to bind events and execute them only when it is enabled.

componentOptionsModel

(ComponentOptionsModel)

Contains the state of options for different components. Mainly used by ResultLink.

componentStateModel

(ComponentStateModel)

Contains the state of different components (enabled vs disabled). Allows to get/set values. Triggers component state event when modified. Each component can listen to those events.

disabled

(boolean)

A disabled component will not participate in the query, or listen to ComponentEvents.

logger

(Logger)

Allows component to log in the dev console.

queryController

(QueryController)

Contains the singleton that allows to trigger queries.

queryStateModel

(QueryStateModel)

Contains the state of the query. Allows to get/set values. Trigger query state event when modified. Each component can listen to those events.

root

(HTMLElement)

A reference to the root HTMLElement (the SearchInterface).

searchInterface

(SearchInterface)

A reference to the root of every component, the SearchInterface.

usageAnalytics

(IAnalyticsClient)

A reference to the Analytics.client.

ID

(string)

The static ID that each component need to be identified.
For example, SearchButton -> static ID : SearchButton -> className : CoveoSearchButton

constructor

Create a new Component. Resolve all IComponentBindings if not provided.
Create a new Logger for this component. Attach the component to the SearchInterface.