Coveo Facet Component (CoveoFacet)

The Facet component displays a facet of the results for the current query. A facet is a list of values for a certain field occurring in the results, ordered using a configurable criteria (e.g., number of occurrences).

The list of values is obtained using a GroupByRequest operation performed at the same time as the main query.

The Facet component allows the end user to drill down inside a result set by restricting the result to certain field values. It also allows filtering out values from the facet itself, and can provide a search box to look for specific values inside larger sets.

This is probably the most complex component in the Coveo JavaScript Search Framework and as such, it allows for many configuration options.

See also the FacetRange and TimespanFacet components (which extend this component), and the FacetSlider and CategoryFacet components (which do not extend this component, but are very similar).

Index

Methods

collapse

  • collapse(): void

debugInfo

  • debugInfo(): any

deselectMultipleValues

  • deselectMultipleValues(values: FacetValue[] | string[]): void
  • Deselects multiple values.

    Does not trigger a query automatically.

    Parameters

    • values: FacetValue[] | string[]

      Can be an array of FacetValue or an array of strings.

    Returns void

deselectValue

  • Deselects a single value.

    Does not trigger a query automatically.

    Parameters

    • value: FacetValue | string

      Can be a FacetValue or a string (e.g., deselectValue('foobar') or deselectValue(new FacetValue('foobar'))).

    Returns void

disable

  • disable(): void
  • Disable the component. Normally this means that the component will not execute handlers for the framework events (query events, for example). Components are enabled by default on creation.

    Returns void

enable

  • enable(): void
  • Enable the component. Normally this means that the component will execute handlers for the framework events (query events, for example). Components are enabled by default on creation.

    Returns void

excludeMultipleValues

  • excludeMultipleValues(values: FacetValue[] | string[]): void
  • Excludes multiple values.

    Does not trigger a query automatically.

    Parameters

    • values: FacetValue[] | string[]

      Can be an array of FacetValue or an array of strings.

    Returns void

excludeValue

  • Excludes a single value.

    Does not trigger a query automatically.

    Parameters

    • value: FacetValue | string

      Can be a FacetValue or a string (e.g., excludeValue('foobar') or excludeValue(new FacetValue('foobar'))).

    Returns void

expand

  • expand(): void

getBindings

getCaptionForStringValue

  • getCaptionForStringValue(value: string): string
  • Returns the configured caption for a desired facet value.

    Parameters

    • value: string

      The string facet value whose caption the method should return.

    Returns string

getDisplayedFacetValues

  • getDisplayedFacetValues(): FacetValue[]

getDisplayedValues

  • getDisplayedValues(): string[]
  • Returns the currently displayed values as an array of strings.

    Returns string[]

    The currently displayed values.

getEndpoint

  • getEndpoint(): ISearchEndpoint
  • Returns the endpoint for the facet.

    Returns ISearchEndpoint

    The endpoint for the facet.

getExcludedValues

  • getExcludedValues(): string[]
  • Returns the currently excluded values as an array of strings.

    Returns string[]

    The currently excluded values.

getSelectedValues

  • getSelectedValues(): string[]
  • Returns the currently selected values as an array of strings.

    Returns string[]

    The currently selected values.

getValueCaption

hasSelectedValue

  • hasSelectedValue(value: string): boolean
  • Determines whether the specified value is selected in the facet.

    Parameters

    • value: string

      The name of the facet value to verify.

    Returns boolean

hideWaitingAnimation

  • hideWaitingAnimation(): void

reset

  • reset(): void
  • Resets the facet by un-selecting all values, un-excluding all values, and redrawing the facet.

    Returns void

selectMultipleValues

  • selectMultipleValues(values: FacetValue[] | string[]): void
  • Selects multiple values.

    Does not trigger a query automatically.

    Parameters

    • values: FacetValue[] | string[]

      Can be an array of FacetValue or an array of strings.

    Returns void

selectValue

  • Selects a single value.

    Does not trigger a query automatically.

    Parameters

    • value: FacetValue | string

      Can be a FacetValue or a string (e.g., selectValue('foobar') or selectValue(new FacetValue('foobar'))).

    Returns void

showLess

  • showLess(): void

showMore

  • showMore(): void

showWaitingAnimation

  • showWaitingAnimation(): void

switchToAnd

  • switchToAnd(): void

switchToOr

  • switchToOr(): void

toggleExcludeValue

  • toggleExcludeValue(value: FacetValue | string): void
  • Toggles the exclusion state of a single value (excludes the value if it is not already excluded; un-excludes the value if it is already excluded).

    Does not trigger a query automatically.

    Parameters

    Returns void

toggleSelectValue

  • toggleSelectValue(value: FacetValue | string): void
  • Toggles the selection state of a single value (selects the value if it is not already selected; un-selects the value if it is already selected).

    Does not trigger a query automatically.

    Parameters

    Returns void

unexcludeMultipleValues

  • unexcludeMultipleValues(values: FacetValue[] | string[]): void
  • Unexcludes multiple values.

    Does not trigger a query automatically.

    Parameters

    • values: FacetValue[] | string[]

      Can be an array of FacetValue or an array of strings.

    Returns void

unexcludeValue

  • unexcludeValue(value: FacetValue | string): void

updateSort

  • updateSort(criteria: string): void

Static get

  • get(element: HTMLElement, componentClass?: any, noThrow?: boolean): BaseComponent
  • Get the bound component to the given HTMLElement. Throws an assert if the HTMLElement has no component bound, unless using the noThrow argument.
    If there is multiple component bound to the current HTMLElement, you must specify the component class.

    Parameters

    • element: HTMLElement

      HTMLElement for which to get the bound component.

    • Optional componentClass: any

      Optional component class. If the HTMLElement has multiple components bound, you must specify which one you are targeting.

    • Optional noThrow: boolean

      Boolean option to tell the method to not throw on error.

    Returns BaseComponent

Properties

bind

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

type

{Coveo.ComponentEvents}

componentOptionsModel

componentOptionsModel: ComponentOptionsModel

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

componentStateModel

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

disabled: boolean

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

type

{boolean}

facetSearch

facetSearch: FacetSearch

Renders and handles the facet Search part of the component.

facetSettings

facetSettings: FacetSettings

Renders and handles the facet Settings part of the component

logger

logger: Logger

Allows component to log in the dev console.

queryController

queryController: QueryController

Contains the singleton that allows to trigger queries.

queryStateModel

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

root: HTMLElement

A reference to the root HTMLElement (the SearchInterface).

searchInterface

searchInterface: SearchInterface

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

Static ID

ID: string

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

Accessors

usageAnalytics

Component Options

additionalFilter

additionalFilter: string

Specifies an additional query expression (query override) to add to each GroupByRequest that this facet performs.

Example: @date>=2014/01/01

Not supported in

Coveo for Salesforce Free

Markup configuration example(s) :
data-additional-filter='foo'

allowedValues

allowedValues: string[]

Specifies an explicit list of allowedValues in the GroupByRequest.

If you specify a list of values for this option, the facet uses only these values (if they are available in the current result set).

Example:

The following facet only uses the Contact, Account, and File values of the @objecttype field. Even if the current result set contains other @objecttype values, such as Message, or Product, the facet does not use those other values.


<div class="CoveoFacet" data-field="@objecttype" data-title="Object Type" data-tab="All" data-allowed-values="Contact,Account,File"></div>

Default value is undefined, and the facet uses all available values for its field in the current result set.

availableSorts

availableSorts: string[] | ("occurrences" | "score" | "alphaascending" | "alphadescending" | "computedfieldascending" | "computedfielddescending" | "chisquare" | "nosort")[]

If the enableSettings option is true, specifies the sort criteria options to display in the facet Settings menu.

Possible values are:

  • "occurrences"
  • "score"
  • "alphaascending"
  • "alphadescending"
  • "computedfieldascending"
  • "computedfielddescending"
  • "custom"

See IGroupByRequest.sortCriteria for a description of each possible value.

Notes:

  • The FacetRange component does not support this option.
  • Using value captions will disable alphabetical sorts (see the valueCaption option).

Default value is occurrences,score,alphaascending,alphadescending.

Only effective when

enableSettings is truthy

Default

[occurrences, score, alphaascending, alphadescending]

computedField

computedField: IFieldOption

Specifies the name of a field on which to execute an aggregate operation for all distinct values of the facet field.

The facet displays the result of the operation along with the number of occurrences for each value.

You can use this option to compute the sum of a field (like a money amount) for each listed facet value.

Works in conjunction with the computedFieldOperation, computedFieldFormat, and computedFieldCaption options.

Not supported in

Coveo for Salesforce Free

Markup configuration example(s) :
data-computed-field='@foo'

computedFieldCaption

computedFieldCaption: string

Specifies what the caption of the computedField should be in the facet Settings menu for sorting.

For example, setting this option to "Money" will display "Money Ascending" for computed field ascending.

Note:

The FacetRange component does not support this option.

Default value is the localized string for ComputedField.

Not supported in

Coveo for Salesforce Free

Markup configuration example(s) :
data-computed-field-caption='foo'

computedFieldFormat

computedFieldFormat: "c0" | "n0" | "n2"

Specifies how to format the values resulting from a computedFieldOperation.

The Globalize library defines all available formats (see Globalize).

The most commonly used formats are:

  • c0 - Formats the value as a currency.
  • n0 - Formats the value as an integer.
  • n2 - Formats the value as a floating point with 2 decimal digits.

Default value is "c0".

Not supported in

Coveo for Salesforce Free

Default

c0

computedFieldOperation

computedFieldOperation: "sum" | "average" | "minimum" | "maximum"

Specifies the type of aggregate operation to perform on the computedField.

The possible values are:

  • sum - Computes the sum of the computed field values.
  • average - Computes the average of the computed field values.
  • minimum - Finds the minimum value of the computed field values.
  • maximum - Finds the maximum value of the computed field values.

Default value is sum.

Not supported in

Coveo for Salesforce Free

Default

sum

customSort

customSort: string[]

Specifies a custom order by which to sort the facet values.

Example:

You could use this option to specify a logical order for support tickets, such as:

<div class="CoveoFacet" data-field="@ticketstatus" data-title="Ticket Status" data-tab="All" data-custom-sort="New,Opened,Feedback,Resolved"></div>

Note:

The FacetRange component does not support this option.

dependsOn

dependsOn: string

Specifies whether this facet only appears when a value is selected in its "parent" facet.

To specify the parent facet, use its id.

Remember that by default, a facet id value is the same as its field option value.

Examples:

First case: the "parent" facet has no custom id:

<!-- "Parent" Facet: -->
<div class='CoveoFacet' data-field='@myfield' data-title='My Parent Facet'></div>

<!-- The "dependent" Facet must refer to the default `id` of its "parent" Facet, which is the name of its field. -->
<div class='CoveoFacet' data-field='@myotherfield' data-title='My Dependent Facet' data-depends-on='@myfield'></div>

Second case: the "parent" facet has a custom id:

<!-- "Parent" Facet: -->
<div class='CoveoFacet' data-field='@myfield' data-title='My Parent Facet' data-id='myParentCustomId'></div>

<!-- The "dependent" Facet must refer to the custom `id` of its "parent" Facet, which is 'myParentCustomId'. -->
<div class='CoveoFacet' data-field='@myotherfield' data-title='My Dependent Facet' data-depends-on='myParentCustomId'></div>

Default value is undefined

Markup configuration example(s) :
data-depends-on='foo'

dependsOnCondition

dependsOnCondition: IDependentFacetCondition

A function that verifies whether the current state of the dependsOn facet allows the dependent facet to be displayed.

If specified, the function receives a reference to the resolved dependsOn facet component instance as an argument, and must return a boolean. The function's argument should typically be treated as read-only.

By default, the dependent facet is displayed whenever one or more values are selected in its dependsOn facet.

Only effective when

dependsOn is truthy

Additional documentation

Defining Dependent Facets

enableCollapse

enableCollapse: boolean

If the enableSettings option is true, specifies whether the Collapse \ Expand menu option is available in the facet Settings menu.

Note:

The FacetRange component does not support this option.

Default value is true.

Only effective when

enableSettings is truthy

Default

true

Markup configuration example(s) :
data-enable-collapse='true'
data-enable-collapse='false'

enableFacetSearch

enableFacetSearch: boolean

Specifies whether to display a search box at the bottom of the facet for searching among the available facet field values.

See also the facetSearchDelay, facetSearchIgnoreAccents, and numberOfValuesInFacetSearch options.

Note:

The FacetRange component does not support this option.

Default value is true.

Default

true

Markup configuration example(s) :
data-enable-facet-search='true'
data-enable-facet-search='false'

enableMoreLess

enableMoreLess: boolean

Specifies whether to enable the More and Less buttons in the Facet.

See also the pageSize option.

Note:

The FacetRange component does not support this option.

Default value is true.

Default

true

Markup configuration example(s) :
data-enable-more-less='true'
data-enable-more-less='false'

enableSettings

enableSettings: boolean

Specifies whether to display the facet Settings menu.

See also the enableSettingsFacetState, availableSorts, and enableCollapse options.

Note:

The FacetRange component does not support this option.

Default value is true.

Default

true

Markup configuration example(s) :
data-enable-settings='true'
data-enable-settings='false'

enableSettingsFacetState

enableSettingsFacetState: boolean

If the enableSettings option is true, specifies whether the Save state menu option is available in the facet Settings menu.

Note:

The FacetRange component does not support this option.

Default value is false.

Only effective when

enableSettings is truthy

Default

false

Markup configuration example(s) :
data-enable-settings-facet-state='true'
data-enable-settings-facet-state='false'

enableTogglingOperator

enableTogglingOperator: boolean

Specifies whether to allow the user to toggle between the OR and AND modes in the facet.

Setting this option to true displays an icon in the top right corner of the facet. The user can click this icon to toggle between between the two modes.

Default value is false.

Default

false

Markup configuration example(s) :
data-enable-toggling-operator='true'
data-enable-toggling-operator='false'

facetSearchDelay

facetSearchDelay: number

If the enableFacetSearch option is true, specifies the delay (in milliseconds) before sending a search request to the server when the user starts typing in the facet search box.

Specifying a smaller value makes results appear faster. However, chances of having to cancel many requests sent to the server increase as the user keeps on typing new characters.

Note:

The FacetRange component does not support this option.

Default value is 100. Minimum value is 0.

Only effective when

enableFacetSearch is truthy

Minimum

0

Default

100

Markup configuration example(s) :
data-facet-search-delay='10'

facetSearchIgnoreAccents

facetSearchIgnoreAccents: boolean

If the enableFacetSearch option is true, specifies whether to ignore accents in the facet search box.

Note:

The FacetRange component does not support this option.

Default value is false.

Only effective when

enableFacetSearch is truthy

Default

false

Markup configuration example(s) :
data-facet-search-ignore-accents='true'
data-facet-search-ignore-accents='false'

field

Specifies the index field whose values the facet should use.

The field must of the string type.

This requires the given field to be configured correctly in the index as a Facet field (see Add or Edit Fields).

Specifying a value for this option is required for the Facet component to work.

Required

Specifying a value for this option is required for the component to work

Markup configuration example(s) :
data-field='@foo'

id

id: string

Specifies a unique identifier for the facet. Among other things, this identifier serves the purpose of saving the facet state in the URL hash.

If you have two facets with the same field on the same page, you should specify an id value for at least one of those two facets. This id must be unique among the facets.

Non-word characters except - @ $ _ . + ! ' ( ) , , ( `^a-zA-Z0-9-@$_.+!'(),,]+) are automatically removed from theid` value.

Default value is the field option value.

Markup configuration example(s) :
data-id='foo'

includeInBreadcrumb

includeInBreadcrumb: boolean

Specifies whether the facet should push data to the Breadcrumb component.

See also the numberOfValuesInBreadcrumb option.

Default value is true.

Default

true

Markup configuration example(s) :
data-include-in-breadcrumb='true'
data-include-in-breadcrumb='false'

includeInOmnibox

includeInOmnibox: boolean

Specifies whether the Facet should push data to the Omnibox component.

See also Facet.options.numberOfValuesInOmnibox.

Default value is false.

deprecated

This option is exposed for legacy reasons. It is not recommended to use this option.

Default

false

Markup configuration example(s) :
data-include-in-omnibox='true'
data-include-in-omnibox='false'

injectionDepth

injectionDepth: number

Specifies the injection depth to use for the GroupByRequest operation.

The injection depth determines how many results to scan in the index to ensure that the facet lists all potential facet values. Increasing this value enhances the accuracy of the listed values at the cost of performance.

Default value is 1000. Minimum value is 1000.

Not supported in

salesforcefree

Minimum

1000

Default

1000

Markup configuration example(s) :
data-injection-depth='1500'

isMultiValueField

isMultiValueField: boolean

Specifies whether the facet field is configured in the index as a multi-value field (semicolon separated values such as abc;def;ghi).

Default value is false.

Default

false

Markup configuration example(s) :
data-is-multi-value-field='true'
data-is-multi-value-field='false'

lookupField

lookupField: IFieldOption

Specifies the field whose values the Facet should display.

deprecated

This option is exposed for legacy reasons. It is not recommended to use this option.

Markup configuration example(s) :
data-lookup-field='@foo'

numberOfValues

numberOfValues: number

Specifies the maximum number of field values to display by default in the facet before the user clicks the arrow to show more.

See also the enableMoreLess option.

Minimum

0

Default

5

Markup configuration example(s) :
data-number-of-values='10'

numberOfValuesInBreadcrumb

numberOfValuesInBreadcrumb: number

If the includeInBreadcrumb option is true, specifies the maximum number of values that the facet should display in the Breadcrumb before outputting a more... button.

Default value is 5 on a desktop computer and 3 on a mobile device. Minimum value is 0.

Only effective when

includeInBreadcrumb is truthy

Minimum

0

Markup configuration example(s) :
data-number-of-values-in-breadcrumb='10'

numberOfValuesInFacetSearch

numberOfValuesInFacetSearch: number

If the enableFacetSearch option is true, specifies the number of v alues to display in the facet search results popup.

Note:

The FacetRange component does not support this option.

Default value is 15. Minimum value is 1.

Minimum

1

Default

15

Markup configuration example(s) :
data-number-of-values-in-facet-search='10'

numberOfValuesInOmnibox

numberOfValuesInOmnibox: number

When Facet.options.includeInOmnibox is true, specifies the number of values to populate the Breadcrumb with.

Default value is 5 on desktop computer and 3 on a mobile device. Minimum value is 0.

deprecated

This option is exposed for legacy reasons. It is not recommended to use this option.

Only effective when

includeInOmnibox is truthy

Minimum

0

Markup configuration example(s) :
data-number-of-values-in-omnibox='10'

paddingContainer

paddingContainer: HTMLElement

Specifies the parent container of the facets.

Used by the preservePosition option.

Default value is element.parentElement.

pageSize

pageSize: number

If the enableMoreLess option is true, specifies the number of additional results to fetch when clicking the More button.

Note:

The FacetRange component does not support this option.

Default value is 10. Minimum value is 1.

Only effective when

enableMoreLess is truthy

Minimum

1

Default

10

Markup configuration example(s) :
data-page-size='10'

preservePosition

preservePosition: boolean

Specifies whether the facet should remain stable in its current position in the viewport while the mouse cursor is over it.

Whenever the value selection changes in a facet, the search interface automatically performs a query. This new query might cause other elements in the page to resize themselves (typically, other facets above or below the one the user is interacting with).

This option is responsible for adding the <div class='coveo-topSpace'> and <div class='coveo-bottomSpace'> around the Facet container. The Facet adjusts the scroll amount of the page to ensure that it does not move relatively to the mouse when the results are updated.

In some cases, the facet also adds margins to the scrollContainer, if scrolling alone is not enough to preserve position.

See also the paddingContainer, and scrollContainer options.

Default value is true.

Default

true

Markup configuration example(s) :
data-preserve-position='true'
data-preserve-position='false'

scrollContainer

scrollContainer: HTMLElement

Specifies the HTML element (through a CSS selector) whose scroll amount the facet should adjust to preserve its position when results are updated.

Used by the preservePosition option.

Default value is document.body.

sortCriteria

sortCriteria: "occurrences" | "score" | "alphaascending" | "alphadescending" | "computedfieldascending" | "computedfielddescending" | "chisquare" | "nosort"

Specifies the criteria to use to sort the facet values.

See IGroupByRequest.sortCriteria for the list and description of possible values.

Default value is the first sort criteria specified in the availableSorts option, or occurrences if no sort criteria is specified.

title

title: string

Specifies the title to display at the top of the facet.

Default value is the localized string for NoTitle.

Markup configuration example(s) :
data-title='foo'

useAnd

useAnd: boolean

Specifies whether to use the AND operator in the resulting filter when multiple values are selected in the facet.

Setting this option to true means that items must have all of the selected values to match the resulting query.

Default value is false, which means that the filter uses the OR operator. Thus, by default, items must have at least one of the selected values to match the query.

Default

false

Markup configuration example(s) :
data-use-and='true'
data-use-and='false'

useWildcardsInFacetSearch

useWildcardsInFacetSearch: boolean

Specifies whether [wildcards]{@link AllowedValuesPatternType.wildcards} are used as the allowedValuesPatternType in the groupBy for the facet search.

Enabling this option returns results that end with the entered value. For example, searching for veo would match with Coveo.

Note:

If you are experiencing slow facet search and/or timeouts when this option is set to true, consider enabling the Use cache for nested queries option on your facet field in the Coveo Cloud Admninistration Console (see Add or Edit Fields).

Default

false

Markup configuration example(s) :
data-use-wildcards-in-facet-search='true'
data-use-wildcards-in-facet-search='false'

valueCaption

valueCaption: IStringMap<string>

Specifies a JSON object describing a mapping of facet values to their desired captions. See Normalizing Facet Value Captions.

Examples:

You can set the option in the 'init' call:

var myValueCaptions = {
  "txt" : "Text files",
  "html" : "Web page",
  [ ... ]
};

Coveo.init(document.querySelector("#search"), {
  Facet : {
    valueCaption : myValueCaptions
  }
});

Or before the init call, using the 'options' top-level function:

Coveo.options(document.querySelector("#search"), {
  Facet : {
    valueCaption : myValueCaptions
  }
});

Or directly in the markup:

<!-- Ensure that the double quotes are properly handled in data-value-caption. -->
<div class='CoveoFacet' data-field='@myotherfield' data-value-caption='{"txt":"Text files","html":"Web page"}'></div>

Note:

Using value captions will disable alphabetical sorts (see the availableSorts option).

Constructors

constructor

  • new Facet(element: HTMLElement, options: IFacetOptions, bindings?: IComponentBindings, facetClassId?: string): Facet
  • Creates a new Facet component. Binds multiple query events as well.

    Parameters

    • element: HTMLElement

      The HTMLElement on which to instantiate the component.

    • options: IFacetOptions

      The options for the Facet component.

    • Optional bindings: IComponentBindings

      The bindings that the component requires to function normally. If not set, these will be automatically resolved (with a slower execution time).

    • Default value facetClassId: string = Facet.ID

      The ID to use for this facet (as Facet inherited from by other component (e.g., FacetRange). Default value is Facet.

    Returns Facet

Implements

  • IFieldValueCompatibleFacet