CategoryFacet (Product Listing Engine)
CategoryFacet (Product Listing Engine)
This is for:
DeveloperExample Implementation
category-facet.fn.tsx
import {
CategoryFacet as HeadlessCategoryFacet,
CategoryFacetValue,
} from '@coveo/headless';
import {useEffect, useState, FunctionComponent} from 'react';
import {CategoryFacetSearch} from './category-facet-search';
interface CategoryFacetProps {
controller: HeadlessCategoryFacet;
}
export const CategoryFacet: FunctionComponent<CategoryFacetProps> = (props) => {
const {controller} = props;
const [state, setState] = useState(controller.state);
useEffect(() => controller.subscribe(() => setState(controller.state)), []);
function getUniqueKeyForValue(value: CategoryFacetValue) {
return value.path.join('>');
}
function renderSearch() {
return (
<CategoryFacetSearch
controller={controller.facetSearch}
searchState={state.facetSearch}
/>
);
}
function renderClearButton() {
return (
<button onClick={() => controller.deselectAll()}>All categories</button>
);
}
function renderParents() {
return (
state.hasActiveValues && (
<div>
Filtering by: {renderClearButton()}
{state.parents.map((parentValue, i) => {
const isSelectedValue = i === state.parents.length - 1;
return (
<span key={getUniqueKeyForValue(parentValue)}>
→
{!isSelectedValue ? (
<button onClick={() => controller.toggleSelect(parentValue)}>
{parentValue.value}
</button>
) : (
<span>{parentValue.value}</span>
)}
</span>
);
})}
</div>
)
);
}
function renderActiveValues() {
return (
<ul>
{state.values.map((value) => (
<li key={getUniqueKeyForValue(value)}>
<button onClick={() => controller.toggleSelect(value)}>
{value.value} ({value.numberOfResults}{' '}
{value.numberOfResults === 1 ? 'result' : 'results'})
</button>
</li>
))}
</ul>
);
}
function renderCanShowMoreLess() {
return (
<div>
{state.canShowLessValues && (
<button onClick={() => controller.showLessValues()}>Show less</button>
)}
{state.canShowMoreValues && (
<button onClick={() => controller.showMoreValues()}>Show more</button>
)}
</div>
);
}
if (!state.hasActiveValues && state.values.length === 0) {
return <div>No facet values</div>;
}
return (
<ul>
<li>{renderSearch()}</li>
<li>
{renderParents()}
{renderActiveValues()}
{renderCanShowMoreLess()}
</li>
</ul>
);
};
// usage
/**
* ```tsx
* const options: CategoryFacetOptions = {field: 'geographicalhierarchy'};
* const controller = buildCategoryFacet(engine, {options});
*
* <CategoryFacet controller={controller} />;
* ```
*/
category-facet-search.tsx
import {
CategoryFacetSearch as HeadlessCategoryFacetSearch,
CategoryFacetSearchState,
} from '@coveo/headless';
import {FunctionComponent} from 'react';
export interface CategoryFacetSearchProps {
controller: HeadlessCategoryFacetSearch;
searchState: CategoryFacetSearchState;
}
export const CategoryFacetSearch: FunctionComponent<
CategoryFacetSearchProps
> = (props) => {
const onInput = (text: string) => {
props.controller.updateText(text);
props.controller.search();
};
return (
<div>
<input onInput={(e) => onInput(e.currentTarget.value)} />
<ul>
{props.searchState.values.map((value) => (
<li key={[...value.path, value.rawValue].join('>')}>
<button onClick={() => props.controller.select(value)}>
{value.displayValue} ({value.count} results)
</button>
</li>
))}
</ul>
</div>
);
};
The CategoryFacet
headless controller offers a high-level interface for designing a facet UI controller that renders values hierarchically.
Methods
deselectAll
Deselects all facet values.
disable
Disables the facet. I.e., prevents it from filtering results.
enable
Enables the facet. I.e., undoes the effects of disable
.
isSortedBy
Checks whether the facet values are sorted according to the specified criterion.
Parameters
-
criterion:
CategoryFacetSortCriterion
The criterion to compare.
Returns boolean
: Whether the facet values are sorted according to the specified criterion.
showLessValues
Sets the number of values displayed in the facet to the originally configured value.
showMoreValues
Increases the number of values displayed in the facet to the next multiple of the originally configured value.
sortBy
Sorts the facet values according to the specified criterion.
Parameters
-
criterion:
CategoryFacetSortCriterion
The criterion by which to sort values.
toggleSelect
Toggles the specified facet value.
Parameters
-
selection:
CategoryFacetValue
The facet value to toggle.
subscribe
Adds a callback that’s invoked on state change.
Parameters
-
listener:
() => void
A callback that’s invoked on state change.
Returns Unsubscribe
: A function to remove the listener.
Attributes
facetSearch
Provides methods to search the facet’s values.
clear
Resets the query and empties the values.
search
Performs a facet search.
select
Selects a facet search result.
Parameters
-
value:
CategoryFacetSearchResult
The search result to select.
showMoreResults
Shows more facet search results.
updateCaptions
Updates the facet value captions.
Parameters
-
captions:
Record<string, string>
A dictionary that maps index field values to facet value display names.
updateText
Updates the facet search query.
Parameters
-
text:
string
The facet search query.
state
The state of the Facet
controller.
Properties
-
facetSearch:
CategoryFacetSearchState
The state of the facet’s searchbox.
-
activeValue:
CategoryFacetValue | undefined
The facet’s selected value if any, undefined otherwise.
-
canShowLessValues:
boolean
Returns
true
if fewer values can be displayed, andfalse
if not. -
canShowMoreValues:
boolean
Returns
true
if there are more values to display and,false
if not. -
enabled:
boolean
Whether the facet is enabled and its values are used to filter search results.
-
facetId:
string
The facet ID.
-
hasActiveValues:
boolean
Returns
true
if there’s at least one non-idle value, andfalse
if not. -
isHierarchical:
boolean
Whether
valuesAsTree
contains hierarchical values (i.e. facet values with children), or only 'flat' values (i.e. facet values without children). -
isLoading:
boolean
Returns
true
if a search is in progress, andfalse
if not. -
parents:
CategoryFacetValue[]
The facet’s parent values.
-
selectedValueAncestry:
CategoryFacetValue[]
The selected facet values ancestry. The first element is the "root" of the selected value ancestry tree. The last element is the selected value itself.
-
sortCriteria:
CategoryFacetSortCriterion
The facet’s active
sortCriterion
. -
values:
CategoryFacetValue[]
The facet’s values.
-
valuesAsTrees:
CategoryFacetValue[]
The root facet values. Child values might be available in
valuesAsTrees[i].children[j]
Initialize
buildCategoryFacet
Creates a CategoryFacet
controller instance.
Parameters
-
engine:
ProductListingEngine
The headless engine.
-
props:
CategoryFacetProps
The configurable
CategoryFacet
properties.
Returns CategoryFacet
CategoryFacetProps
The configurable CategoryFacet
properties.
Properties
-
options:
CategoryFacetOptions
The options for the
CategoryFacet
controller.
CategoryFacetOptions
The options for the CategoryFacet
controller.
Properties
-
field:
string
The field whose values you want to display in the facet.
-
basePath?:
string[]
The base path shared by all values for the facet.
Default:
[]
-
delimitingCharacter?:
string
The character that specifies the hierarchical dependency.
Default:
;
-
facetId?:
string
A unique identifier for the controller. By default, a random unique ID is generated.
-
facetSearch?:
CategoryFacetSearchOptions
Facet search options.
-
filterByBasePath?:
boolean
Whether to filter the results using
basePath
.Default:
true
-
filterFacetCount?:
boolean
Whether to exclude the parents of folded results when estimating the result count for each facet value.
Default:
true
-
injectionDepth?:
number
The maximum number of results to scan in the index to ensure that the facet lists all of the potential facet values.
Note: A high
injectionDepth
may reduce facet request performance.Minimum:
0
Default:
1000
-
numberOfValues?:
number
The number of values to request for this facet. This option also determines the number of additional values to request each time this facet is expanded, as well as the number of values to display when this facet is collapsed.
Minimum:
1
Default:
5
-
sortCriteria?:
CategoryFacetSortCriterion
The criterion to use for sorting returned facet values.
Default:
occurrences
Related Types
CategoryFacetSearchOptions
Properties
-
captions?:
Record<string, string>
A dictionary that maps index field values to facet value display names.
-
numberOfValues?:
number
The maximum number of values to fetch.
Default:
10
-
query?:
string
The string to match.
CategoryFacetSearchResult
Properties
-
count:
number
An estimate of the number of result items that match both the current query and the filter expression which would be generated if the facet value were selected.
-
displayValue:
string
The custom facet value display name, as specified in the
captions
argument of the facet request. -
path:
string[]
The hierarchical path to the selected facet value.
-
rawValue:
string
The original facet value, as retrieved from the field in the index.
CategoryFacetSearchState
Properties
-
isLoading:
boolean
Returns
true
if the facet search is in progress, andfalse
if not. -
moreValuesAvailable:
boolean
Whether more values are available.
-
query:
string
The current query in the facet search box.
-
values:
CategoryFacetSearchResult[]
The facet search results.
CategoryFacetValue
Properties
-
children:
CategoryFacetValue[]
The children of this facet value.
-
isLeafValue:
boolean
When the hierarchical value has no children, this property is true.
-
moreValuesAvailable:
boolean
Whether more facet values are available.
-
numberOfResults:
number
The number of results that match the facet value.
-
path:
string[]
The hierarchical path to the facet value.
-
state:
'idle' | 'selected' | 'excluded'
Whether a facet value is filtering results (
selected
) or not (idle
). -
value:
string
The facet value.
Unsubscribe
Call signatures
-
(): void;