THIS IS ARCHIVED DOCUMENTATION

RecommendationList (Deprecated)

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 and false 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

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.

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.

  • 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