DateFacet (Search engine) (Deprecated)
DateFacet (Search engine) (Deprecated)
|
|
Headless v1 has been deprecated. We recommend using the latest version of the Coveo Headless library. |
Example implementation
date-facet.fn.tsx
import {DateFacet as HeadlessDateFacet, DateFacetValue} from '@coveo/headless';
import {useEffect, useState, FunctionComponent} from 'react';
import {parseDate} from './date-utils';
interface DateFacetProps {
controller: HeadlessDateFacet;
}
export const DateFacet: FunctionComponent<DateFacetProps> = (props) => {
const {controller} = props;
const [state, setState] = useState(controller.state);
useEffect(() => controller.subscribe(() => setState(controller.state)), []);
function getKeyForRange(value: DateFacetValue) {
return `[${value.start}..${value.end}]`;
}
function format(dateStr: string) {
return parseDate(dateStr).format('MMMM D YYYY');
}
if (
!state.values.filter(
(value) => value.state !== 'idle' || value.numberOfResults > 0
).length
) {
return <div>No facet values</div>;
}
return (
<ul>
{state.values.map((value) => (
<li key={getKeyForRange(value)}>
<input
type="checkbox"
checked={controller.isValueSelected(value)}
onChange={() => controller.toggleSelect(value)}
disabled={state.isLoading}
/>
{format(value.start)} to {format(value.end)} ({value.numberOfResults}{' '}
{value.numberOfResults === 1 ? 'result' : 'results'})
</li>
))}
</ul>
);
};
// usage
/**
* ```tsx
* const controller = buildDateFacet(engine, {
* options: {
* field: 'created',
* generateAutomaticRanges: false,
* currentValues: [ // Must be specified when `generateAutomaticRanges` is false.
* buildDateRange({
* start: new Date(2015, 1),
* end: new Date(2018, 1),
* }),
* buildDateRange({
* start: new Date(2018, 1),
* end: new Date(2020, 1),
* }),
* buildDateRange({
* start: new Date(2020, 1),
* end: new Date(2021, 1),
* }),
* ],
* },
* });
*
* <DateFacet controller={controller} />;
* ```
*/
relative-date-facet.fn.tsx
import {
DateFacet,
DateFacetValue,
deserializeRelativeDate,
} from '@coveo/headless';
import {useEffect, useState, FunctionComponent} from 'react';
interface RelativeDateFacetProps {
controller: DateFacet;
}
export const RelativeDateFacet: FunctionComponent<RelativeDateFacetProps> = (
props
) => {
const {controller} = props;
const [state, setState] = useState(controller.state);
useEffect(() => controller.subscribe(() => setState(controller.state)), []);
function getKeyForRange(value: DateFacetValue) {
return `[${value.start}..${value.end}]`;
}
function format(value: string) {
const relativeDate = deserializeRelativeDate(value);
return relativeDate.period === 'now'
? relativeDate.period
: `${relativeDate.period} ${relativeDate.amount} ${relativeDate.unit}`;
}
if (
!state.values.filter(
(value) => value.state !== 'idle' || value.numberOfResults > 0
).length
) {
return <div>No facet values</div>;
}
return (
<ul>
{state.values.map((value) => (
<li key={getKeyForRange(value)}>
<input
type="checkbox"
checked={controller.isValueSelected(value)}
onChange={() => controller.toggleSingleSelect(value)}
disabled={state.isLoading}
/>
{format(value.start)} to {format(value.end)} ({value.numberOfResults}{' '}
{value.numberOfResults === 1 ? 'result' : 'results'})
</li>
))}
</ul>
);
};
// usage
/**
* ```tsx
* const controller = buildDateFacet(engine, {
* options: {
* field: 'created',
* generateAutomaticRanges: false,
* currentValues: [
* buildDateRange({
* start: {period: 'past', unit: 'day', amount: 1},
* end: {period: 'now'},
* }),
* buildDateRange({
* start: {period: 'past', unit: 'week', amount: 1},
* end: {period: 'now'},
* }),
* ],
* },
* });
*
* <DateFacet controller={controller} />;
* ```
*/
The DateFacet controller makes it possible to create a facet with date ranges.
Methods
deselectAll
Deselects all facet values.
disable
Disables the facet. In other words, prevents it from filtering results.
enable
Enables the facet. In other words, undoes the effects of disable.
isSortedBy
Checks whether the facet values are sorted according to the specified criterion.
Parameters
-
criterion:
'ascending' | 'descending'The criterion to compare.
Returns boolean: Whether the facet values are sorted according to the specified criterion.
isValueSelected
Checks whether the specified facet value is selected.
Parameters
-
selection:
DateFacetValueThe facet value to check.
Returns boolean: Whether the specified facet value is selected.
sortBy
Sorts the facet values according to the specified criterion.
Parameters
-
criterion:
'ascending' | 'descending'The criterion by which to sort values.
toggleSelect
Toggles the specified facet value.
Parameters
-
selection:
DateFacetValueThe facet value to toggle.
toggleSingleSelect
Toggles the specified facet value, deselecting others.
Parameters
-
selection:
DateFacetValueThe facet value to toggle.
subscribe
Adds a callback that’s invoked on state change.
Parameters
-
listener:
() => voidA callback that’s invoked on state change.
Returns Unsubscribe: A function to remove the listener.
Attributes
state
The state of the DateFacet controller.
Properties
-
enabled:
booleanWhether the facet is enabled and its values are used to filter search results.
-
facetId:
stringThe facet ID.
-
hasActiveValues:
booleantrueif there’s at least one non-idle value andfalseotherwise. -
isLoading:
booleantrueif a search is in progress andfalseotherwise. -
sortCriterion:
'ascending' | 'descending'The active sortCriterion of the facet.
-
values:
DateFacetValue[]The values of the facet.
Initialize
buildDateFacet
Creates a DateFacet controller instance.
Parameters
-
engine:
SearchEngineThe headless engine.
-
props:
DateFacetPropsThe configurable
DateFacetcontroller properties.
Returns DateFacet
DateFacetProps
The configurable DateFacet controller properties.
Properties
-
options:
DateFacetOptionsThe options for the
DateFacetcontroller.
DateFacetOptions
The options for the DateFacet controller.
Properties
-
field:
stringThe field whose values you want to display in the facet.
-
generateAutomaticRanges:
booleanWhether the index should automatically create range values.
Tip: If you set this parameter to true, you should ensure that the 'Use cache for numeric queries' option is enabled for this facet’s field in your index in order to speed up automatic range evaluation.
-
currentValues?:
DateRangeRequest[]The values displayed by the facet in the search interface at the moment of the request.
If
generateAutomaticRangesis false, values must be specified. IfgenerateAutomaticRangesis true, automatic ranges are going to be appended after the specified values.Default:
[] -
facetId?:
stringA unique identifier for the controller. By default, a unique random identifier is generated.
-
filterFacetCount?:
booleanWhether to exclude folded result parents when estimating the result count for each facet value.
Default:
true -
injectionDepth?:
numberThe maximum number of results to scan in the index to ensure that the facet lists all potential facet values.
Note: A high injectionDepth may negatively impact the facet request performance.
Minimum:
0Default:
1000 -
numberOfValues?:
numberThe number of values to request for this facet. Also determines the number of additional values to request each time this facet is expanded, and the number of values to display when this facet is collapsed.
Minimum:
1Default:
8 -
rangeAlgorithm?:
'even' | 'equiprobable'The algorithm that’s used for generating the ranges of this facet when they aren’t manually defined. The default value of
"even"generates equally sized facet ranges across all of the results. The value"equiprobable"generates facet ranges which vary in size but have a more balanced number of results within each range.Default:
even -
sortCriteria?:
'ascending' | 'descending'The sort criterion to apply to the returned facet values.
Default:
ascending
Utils
buildDateRange
Creates a DateRangeRequest.
Parameters
-
config:
DateRangeOptionsThe options with which to create a
DateRangeRequest.
Returns DateRangeRequest: The options defining a value to display in a DateFacet.
Related types
DateFacetValue
Properties
-
end:
stringThe ending value for the date range, formatted as
YYYY/MM/DD@HH:mm:ssor the Relative date format "period-amount-unit" -
endInclusive:
booleanWhether the end value is included in the range.
-
numberOfResults:
numberThe number of results that have the facet value.
-
start:
stringThe starting value for the date range, formatted as
YYYY/MM/DD@HH:mm:ssor the Relative date format "period-amount-unit" -
state:
'idle' | 'selected'The state of the facet value, indicating whether it is filtering results (
selected) or not (idle).
DateRangeOptions
Properties
-
end:
AbsoluteDate | RelativeDateThe ending value for the date range. A date range can be either absolute or relative.
-
start:
AbsoluteDate | RelativeDateThe starting value for the date range. A date range can be either absolute or relative.
-
dateFormat?:
string -
endInclusive?:
booleanWhether to include the end value in the range.
Default:
false -
state?:
'idle' | 'selected'The current facet value state.
Default:
idle -
useLocalTime?:
booleanIf
true, the date will be returned unshifted. Iffalse, the date will be adjusted to UTC time.
DateRangeRequest
Properties
-
end:
stringThe ending value for the date range, formatted as
YYYY/MM/DD@HH:mm:ssor the Relative Date format "period-amount-unit". -
endInclusive:
booleanWhether to include the
endvalue in the range. -
start:
stringThe starting value for the date range, formatted as
YYYY/MM/DD@HH:mm:ssor the Relative Date format "period-amount-unit". -
state:
'idle' | 'selected'The current facet value state.
Unsubscribe
Call signatures
-
(): void