RecommendationList
RecommendationList
Example Implementation
recommendation-list.fn.tsx
import {
RecommendationList as HeadlessRecommendationList,
loadClickAnalyticsActions,
Result,
} from '@coveo/headless/recommendation';
import {useEffect, useState, FunctionComponent, useContext} from 'react';
import {AppContext} from '../../context/engine';
import {filterProtocol} from '../../utils/filter-protocol';
interface RecommendationListProps {
controller: HeadlessRecommendationList;
}
export const RecommendationList: FunctionComponent<RecommendationListProps> = (
props
) => {
const engine = useContext(AppContext).recommendationEngine;
const {controller} = props;
const [state, setState] = useState(controller.state);
useEffect(() => controller.subscribe(() => setState(controller.state)), []);
if (state.error) {
return (
<div>
<div>Oops {state.error.message}</div>
<code>{JSON.stringify(state.error)}</code>
<button onClick={() => controller.refresh()}>Try again</button>
</div>
);
}
if (!state.recommendations.length) {
return <button onClick={() => controller.refresh()}>Refresh</button>;
}
const logClick = (recommendation: Result) => {
if (!engine) {
return;
}
const {logRecommendationOpen} = loadClickAnalyticsActions(engine);
engine.dispatch(logRecommendationOpen(recommendation));
};
return (
<div>
<button onClick={() => controller.refresh()}>Refresh</button>
<ul style={{textAlign: 'left'}}>
{state.recommendations.map((recommendation) => (
<li key={recommendation.uniqueId}>
<article>
<h2>
{/* Make sure to log analytics when the recommendation is clicked. */}
<a
href={filterProtocol(recommendation.clickUri)} // Filters out dangerous URIs that can create XSS attacks such as `javascript:`.
onClick={() => logClick(recommendation)}
onContextMenu={() => logClick(recommendation)}
onMouseDown={() => logClick(recommendation)}
onMouseUp={() => logClick(recommendation)}
>
{recommendation.title}
</a>
</h2>
<p>{recommendation.excerpt}</p>
</article>
</li>
))}
</ul>
</div>
);
};
// usage
/**
* ```tsx
* const controller = buildRecommendationList(recommendationEngine, {
* options: {id: 'Recommendation'},
* });
*
* <RecommendationList controller={controller} />;
* ```
*/
The RecommendationList
controller retrieves information about the current recommendations by the search API, if there are any.
Methods
refresh
Gets new recommendations.
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
state
The state relevant to the RecommendationList
controller.
Properties
-
error:
ErrorPayload | null
The current error for the last executed query, or
null
if none is present. -
isLoading:
boolean
true
if a search is in progress andfalse
otherwise. -
recommendations:
Result[]
The recommendations based on the last executed query.
-
searchResponseId:
string
The unique identifier of the Search API response from which the recommendations were fetched.
Initialize
buildRecommendationList
Creates a RecommendationList
controller instance.
Parameters
-
engine:
RecommendationEngine
The headless engine.
-
props:
RecommendationListProps
The configurable
RecommendationList
properties.
Returns RecommendationList
RecommendationListProps
The configurable RecommendationList
properties.
Properties
-
options?:
RecommendationListOptions
RecommendationListOptions
Properties
-
id?:
string
The Recommendation identifier used by the Coveo platform to retrieve recommended documents.
Default:
Recommendation
-
numberOfRecommendations?:
number
The number of recommendations to return.
Related Types
HighlightKeyword
Properties
-
length:
number
The length of the offset.
-
offset:
number
The 0 based offset inside the string where the highlight should start.
Raw
Properties
-
[key: string]:
unknown
Custom keys that depend on the documents in the index.
Result
Properties
-
absentTerms:
string[]
The basic query expression terms which this query result item does not match. Note: This property is populated by terms from the query pipeline-processed q value (not from the original q value).
-
clickUri:
string
The hyperlinkable item URI. Notes: Use the clickUri value when you want to create hyperlinks to the item, rather than the uri or printableUri value.
-
excerpt:
string
The contextual excerpt generated for the item (see the excerptLength query parameter).
-
excerptHighlights:
HighlightKeyword[]
The length and offset of each word to highlight in the item excerpt string.
-
firstSentences:
string
The first sentences retrieved from the item (see the retrieveFirstSentences query parameter).
-
firstSentencesHighlights:
HighlightKeyword[]
The length and offset of each word to highlight in the item firstSentences string.
-
flags:
string
The flags that are set on the item by the index. Distinct values are separated by semicolons.
-
hasHtmlVersion:
boolean
Whether the index contains an HTML version of this item.
-
isRecommendation:
boolean
Whether the item score was boosted as a Coveo ML recommendation.
-
isTopResult:
boolean
Whether the item score was boosted by a featured result rule in the query pipeline.
-
isUserActionView:
boolean
Whether the result item has been previously viewed by one of the users specified in the
canSeeUserProfileOf
section of the search token generated to perform the search request. -
percentScore:
number
The item ranking score expressed as a percentage (see the sortCriteria and rankingFunctions query parameters).
-
printableUri:
string
The human readable item URI. Note: Avoid using the printableUri value to create hyperlinks to the item. Use the clickUri value instead.
-
printableUriHighlights:
HighlightKeyword[]
The length and offset of each word to highlight in the item printableUri string.
-
rankingInfo:
string | null
The raw debug information generated by the index to detail how the item was ranked. This property is null unless the debug query parameter is set to true.
-
raw:
Raw
The values of the fields which were retrieved for this item (see the fieldsToInclude and fieldsToExclude query parameters).
-
score:
number
The total ranking score computed for the item (see the sortCriteria and rankingFunctions query parameters).
-
summary:
null
The item summary (see the summaryLength query parameter).
-
summaryHighlights:
HighlightKeyword[]
The length and offset of each word to highlight in the item summary string.
-
title:
string
Contains the title of the item.
-
titleHighlights:
HighlightKeyword[]
The length and offset of each word to highlight in the item title string.
-
uniqueId:
string
The unique item identifier. You should consider the uniqueId value as an opaque string.
-
uri:
string
The item URI. Notes: Avoid using the uri value to create hyperlinks to the item. Use the clickUri value instead.
-
rankingModifier?:
string
If applicable, represents the type of ranking modification that was applied to this result.
Unsubscribe
Call signatures
-
(): void