Collapses the facet.
Return the debug info about this component.
Deselects multiple values.
Does not trigger a query automatically.
Can be an array of FacetValue
or an array of strings.
Deselects a single value.
Does not trigger a query automatically.
Can be a FacetValue
or a string (e.g., deselectValue('foobar')
or
deselectValue(new FacetValue('foobar'))
).
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.
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.
Excludes multiple values.
Does not trigger a query automatically.
Can be an array of FacetValue
or an array of strings.
Excludes a single value.
Does not trigger a query automatically.
Can be a FacetValue
or a string (e.g., excludeValue('foobar')
or
excludeValue(new FacetValue('foobar'))
).
Expands the facet.
Return the bindings, or environment, for the current component.
Returns the configured caption for a desired facet value.
The string facet value whose caption the method should return.
Returns the currently displayed values as an array of FacetValue
.
The currently displayed values.
Returns the currently displayed values as an array of strings.
The currently displayed values.
Returns the endpoint for the facet.
The endpoint for the facet.
Returns the currently excluded values as an array of strings.
The currently excluded values.
Returns the currently selected values as an array of strings.
The currently selected values.
Returns the configured caption for the given FacetValue
.
The FacetValue
whose caption the method should return.
Determines whether the specified value is selected in the facet.
The name of the facet value to verify.
Hides the waiting animation in the facet header.
Resets the facet by un-selecting all values, un-excluding all values, and redrawing the facet.
Selects multiple values.
Does not trigger a query automatically.
Can be an array of FacetValue
or an array of strings.
Selects a single value.
Does not trigger a query automatically.
Can be a FacetValue
or a string (e.g., selectValue('foobar')
or
selectValue(new FacetValue('foobar'))
).
Shows less elements in the Facet (up to the original number of values).
See the enableMoreLess
, and
numberOfValues
options.
Shows the next page of results in the facet.
See the enableMoreLess
, and pageSize
options.
Triggers a query if needed, or displays the already available values.
Shows a waiting animation in the facet header (a spinner).
Switches the facet to AND
mode.
See the useAnd
, and
enableTogglingOperator
options.
Switches the facet to OR
mode.
See the useAnd
, and
enableTogglingOperator
options.
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.
Can be a FacetValue
or a string.
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.
Can be a FacetValue
or a string.
Unexcludes multiple values.
Does not trigger a query automatically.
Can be an array of FacetValue
or an array of strings.
Unexcludes a single value.
Does not trigger a query automatically.
Can be a FacetValue
or a string.
Changes the sort parameter for the facet.
See Facet.options.availableSorts for the list of possible values.
Also triggers a new query.
The new sort parameter for the facet.
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.
HTMLElement for which to get the bound component.
Optional component class. If the HTMLElement has multiple components bound, you must specify which one you are targeting.
Boolean option to tell the method to not throw on error.
Allows the component to bind events and execute them only when it is enabled.
Contains the state of options for different components. Mainly used by ResultLink.
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.
A disabled component will not participate in the query, or listen to ComponentEvents.
Renders and handles the facet Search part of the component.
Renders and handles the facet Settings part of the component
Allows component to log in the dev console.
Contains the singleton that allows to trigger queries.
Contains the state of the query. Allows to get/set values. Trigger query state event when modified. Each component can listen to those events.
A reference to the root HTMLElement (the SearchInterface).
A reference to the root of every component, the SearchInterface.
The static ID that each component needs in order to be identified.
For example, SearchButton -> static ID: SearchButton -> className: CoveoSearchButton
A reference to the Analytics.client.
Specifies an additional query expression (query override) to add to each
GroupByRequest
that this facet performs.
Example: @date>=2014/01/01
data-additional-filter='foo'
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.
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
.
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.
data-computed-field='@foo'
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
.
data-computed-field-caption='foo'
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"
.
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
.
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.
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
data-depends-on='foo'
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.
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
.
data-enable-collapse='true' data-enable-collapse='false'
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
.
data-enable-facet-search='true' data-enable-facet-search='false'
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
.
data-enable-more-less='true' data-enable-more-less='false'
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
.
data-enable-settings='true' data-enable-settings='false'
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
.
data-enable-settings-facet-state='true' data-enable-settings-facet-state='false'
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
.
data-enable-toggling-operator='true' data-enable-toggling-operator='false'
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
.
data-facet-search-delay='10'
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
.
data-facet-search-ignore-accents='true' data-facet-search-ignore-accents='false'
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.
data-field='@foo'
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 the
id` value.
Default value is the field
option value.
data-id='foo'
Specifies whether the facet should push data to the Breadcrumb
component.
See also the numberOfValuesInBreadcrumb
option.
Default value is true
.
data-include-in-breadcrumb='true' data-include-in-breadcrumb='false'
Specifies whether the Facet should push data to the Omnibox component.
See also Facet.options.numberOfValuesInOmnibox.
Default value is false
.
data-include-in-omnibox='true' data-include-in-omnibox='false'
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
.
data-injection-depth='1500'
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
.
data-is-multi-value-field='true' data-is-multi-value-field='false'
Specifies the field whose values the Facet should display.
data-lookup-field='@foo'
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.
data-number-of-values='10'
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
.
data-number-of-values-in-breadcrumb='10'
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
.
data-number-of-values-in-facet-search='10'
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
.
data-number-of-values-in-omnibox='10'
Specifies the parent container of the facets.
Used by the preservePosition
option.
Default value is element.parentElement
.
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
.
data-page-size='10'
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
.
data-preserve-position='true' data-preserve-position='false'
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
.
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.
Specifies the title to display at the top of the facet.
Default value is the localized string for NoTitle
.
data-title='foo'
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.
data-use-and='true' data-use-and='false'
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).
data-use-wildcards-in-facet-search='true' data-use-wildcards-in-facet-search='false'
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).
Creates a new Facet
component. Binds multiple query events as well.
The HTMLElement on which to instantiate the component.
The options for the Facet
component.
The bindings that the component requires to function normally. If not set, these will be automatically resolved (with a slower execution time).
The ID to use for this facet (as Facet
inherited from by other component
(e.g., FacetRange
). Default value is Facet
.
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
andTimespanFacet
components (which extend this component), and theFacetSlider
andCategoryFacet
components (which do not extend this component, but are very similar).