Support Menu

Coveo component Facet

The Facet component displays a facet of the results for the current query. A facet consists of a list of values for a given field occurring in the results, ordered using a configurable criteria.

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

The Facet component allows the user to drill down inside results by restricting them 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 different configuration options.

See also FacetRange and HierarchicalFacet (which extend this component), and FacetSlider (which does not properly extend this component, but is very similar).

Index

Component Options

additionalFilter

additionalFilter: string

Specifies an additional query expression (query override) to add to each IGroupByRequest that this Facet performs.

Example: @date>=2014/01/01

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

allowedValues

allowedValues: Array<string>

Specifies an explicit list of IGroupByRequest.allowedValues in the IGroupByRequest.

This will whitelist the Facet content to some specific values.

Example: ["File", "People"].

Markup configuration example(s) :
data-allowed-values='foo,foo2'

availableSorts

availableSorts: Array<"occurrences" | "score" | "alphaascending" | "alphadescending" | "computedfieldascending" | "computedfielddescending" | "chisquare" | "nosort"> | Array<string>

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

Possible values are:

  • "occurrences"
  • "score"
  • "alphaAscending"
  • alphaDescending
  • "computedfieldascending"
  • "computedfielddescending"
  • "custom"

Default value is "occurrences,score,alphaAscending,alphaDescending".

Markup configuration example(s) :
data-available-sorts='occurrences'
data-available-sorts='occurrences,score'
data-available-sorts='occurrences,score,alphaascending'
data-available-sorts='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 Facet.options.computedFieldOperation, Facet.options.computedFieldFormat and Facet.options.computedFieldCaption.

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

computedFieldCaption

computedFieldCaption: string

Specifies what the caption of the Facet.options.computedField should be in the settings menu for sorting.

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

Default value is the localized string for "ComputedField".

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

computedFieldFormat

computedFieldFormat: string

Specifies how to format the values resulting from a Facet.options.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".

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

computedFieldOperation

computedFieldOperation: string

Specifies the type of aggregate operation to perform on the Facet.options.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".

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

customSort

customSort: Array<string>

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

For example, you could use this to specify a logical order for support tickets, such as customSort : ["New","Opened","Feedback","Resolved","Feedback"]

Markup configuration example(s) :
data-custom-sort='foo,foo2'

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 is the same as its field.

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'

dropdownHeaderLabel

dropdownHeaderLabel: string

If Facet.options.enableResponsiveMode is true for all facets and FacetSlider.options.enableResponsiveMode is also true for all sliders, specifies the label of the dropdown button that allows to display the facets when in responsive mode.

If more than one Facet or FacetSlider in the search interface specifies a value for this option, then the framework uses the first occurrence of the option.

Default value is Filters.

Markup configuration example(s) :
data-dropdown-header-label='foo'

enableCollapse

enableCollapse: boolean

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

Default value is 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 values.

See also Facet.options.facetSearchDelay, Facet.options.facetSearchIgnoreAccents, Facet.options.numberOfValuesInFacetSearch.

Default value is 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 Facet.options.pageSize.

Default value is true.

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

enableResponsiveMode

enableResponsiveMode: boolean

Specifies whether to enable responsive mode for facets. Setting this options to false on any Facet or FacetSlider in a search interface disables responsive mode for all other facets in the search interface.

Responsive mode displays all facets under a single dropdown button whenever the width of the HTML element which the search interface is bound to reaches or falls behind a certain threshold (see SearchInterface.responsiveComponents).

See also Facet.options.dropdownHeaderLabel.

Default value is true.

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

enableSettings

enableSettings: boolean

Specifies whether to display the Facet Settings menu.

See also Facet.options.enableSettingsFacetState, Facet.options.availableSorts and Facet.options.enableCollapse.

Default value is true.

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

enableSettingsFacetState

enableSettingsFacetState: boolean

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

Default value is 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.

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

facetSearchDelay

facetSearchDelay: number

If Facet.options.enableFacetSearch 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 means results will arrive faster. However, chances of having to cancel many requests sent to the server will increase as the user keeps on typing new characters.

Default value is 100. Minimum value is 0.

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

facetSearchIgnoreAccents

facetSearchIgnoreAccents: boolean

If Facet.options.enableFacetSearch is true, specifies whether to ignore accents in the Facet search box.

Default value is 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.

This requires the given field to be configured correctly in the index as a Facet field (see Adding Fields to a Source).

Specifying a value for this option is required for the Facet 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 in the page.

Default value is the Facet.options.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 Facet.options.numberOfValuesInBreadcrumb.

Default value is true.

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

injectionDepth

injectionDepth: number

Specifies the injection depth to use for the IGroupByRequest 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 0.

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

isMultiValueField

isMultiValueField: boolean

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

Default value is false.

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

numberOfValues

numberOfValues: number

Specifies the maximum number of field values to display by default in the Facet before the user clicks More.

Default value is 5. Minimum value is 0.

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

numberOfValuesInBreadcrumb

numberOfValuesInBreadcrumb: number

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

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

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

numberOfValuesInFacetSearch

numberOfValuesInFacetSearch: number

If Facet.options.enableFacetSearch is true, specifies the number of values to display in the Facet search results popup.

Default value is 15. Minimum value is 1.

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

paddingContainer

paddingContainer: HTMLElement

Specifies the parent container of the facets.

Used by the Facet.options.preservePosition.

Default value is element.parentElement.

pageSize

pageSize: number

If Facet.options.enableMoreLess is true, specifies the number of additional results to fetch when clicking on the More button in the Facet.

Default value is 10. Minimum value is 1.

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 Facet.options.paddingContainer and Facet.options.scrollContainer.

Default value is 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 Facet.options.preservePosition.

Default value is document.body.

sortCriteria

sortCriteria: string

Specifies the criteria to use to sort the Facet values.

See IGroupByRequest for the list of possible values.

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

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

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 documents 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, documents must have at least one of the selected values to match the query.

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

valueCaption

valueCaption: IStringMap<string>

Specifies a JSON object describing a mapping of Facet values to their desired captions.

You can only set this option in the init call of your search interface. You cannot set it directly in the markup as an HTML attribute.

Example:

// Using a Facet for file types
var myValueCaption = {  "txt": "Text files","html": "Web page", [ etc ... ]};

// You can set the option in the 'init' call using 'pure' JavaScript:
Coveo.init(document.querySelector('#search'), {
   Facet : {
     valueCaption: myValueCaption
   }
})

// Or  the jQuery extension
$("#search").coveo("init", {
   Facet: {
     valueCaption: myValueCaption
   }
})

Methods

collapse

  • collapse(): void

debugInfo

  • debugInfo(): any

deselectMultipleValues

  • deselectMultipleValues(values: FacetValue[]): void

deselectValue

  • Deselects a single value.

    Does not trigger a query automatically.

    Parameters

    • value: FacetValue

      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). Component 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[]): void

excludeValue

  • Excludes a single value.

    Does not trigger a query automatically.

    Parameters

    • value: FacetValue

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

    Returns void

expand

  • expand(): void

getBindings

getDisplayedFacetValues

getDisplayedValues

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

    Returns string[]

    The currently displayed values.

getEndpoint

  • getEndpoint(): ISearchEndpoint

getExcludedValues

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

    Returns string[]

    The currently excluded values.

getSelectedValues

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

    Returns string[]

    The currently selected values.

getValueCaption

hideWaitingAnimation

  • hideWaitingAnimation(): void

reset

  • reset(): void
  • Resets the Facet by un-selecting all values, une-xcluding all values, and redrawing the Facet.

    Returns void

selectMultipleValues

  • selectMultipleValues(values: FacetValue[]): void

selectValue

  • Selects a single value.

    Does not trigger a query automatically.

    Parameters

    • value: FacetValue

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

    Returns void

showLess

  • showLess(): void

showMore

  • showMore(): void
  • Shows the next page of results in the Facet.

    Triggers a query if needed, or displays the already available values.

    Returns void

showWaitingAnimation

  • showWaitingAnimation(): void

switchToAnd

  • switchToAnd(): void

switchToOr

  • switchToOr(): void

toggleExcludeValue

  • 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

  • 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[]): void

unexcludeValue

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 differents component. Mainly used by ResultLink.

componentStateModel

componentStateModel: ComponentStateModel

Contains the state of different component (enabled vs disabled). Allows to get/set values. Trigger 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.

usageAnalytics

usageAnalytics: IAnalyticsClient

A reference to the Analytics.client.

Static ID

ID: string

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

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