ProductListing (Commerce Engine)

This is for:

Developer
Note

This component was introduced in version 2.63.5.

Example implementation

product-listing.fn.tsx

import {ProductListing as HeadlessProductListing} from '@coveo/headless/commerce';
import {useEffect, useState, FunctionComponent} from 'react';
 
interface ProductListingProps {
  controller: HeadlessProductListing;
}
 
export const ProductListing: FunctionComponent<ProductListingProps> = (
  props
) => {
  const {controller} = props;
  const [state, setState] = useState(controller.state);
 
  useEffect(() => controller.subscribe(() => setState(controller.state)), []);
 
  if (!state.products.length) {
    return <button onClick={() => controller.refresh()}>Refresh</button>;
  }
 
  return (
    <ul>
      {state.products.map(({ec_name, clickUri, permanentid}) => (
        <li key={permanentid}>
          <a href={clickUri}>{ec_name}</a>
        </li>
      ))}
    </ul>
  );
};
 
// usage
 
/**
 * ```tsx
 * const controller = buildProductListing(engine);
 *
 * <ProductListing controller={controller} />;
 * ```
 */

The ProductListing controller exposes a method for retrieving product listing content in a commerce interface.

Methods

executeFirstRequest

Executes the first request if it has not been executed yet.

promoteChildToParent

Finds the specified parent product and the specified child product of that parent, and makes that child the new parent. The children and totalNumberOfChildren properties of the original parent are preserved in the new parent.

This method is useful when leveraging the product grouping feature to allow users to select nested products.

For example, if a product has children (such as color variations), you can call this method when the user selects a child to make that child the new parent product, and re-render the product as such in the storefront.

Note: In the controller state, a product that has children will always include itself as its own child so that it can be rendered as a nested product, and restored as the parent product through this method as needed.

Parameters

  • child: Omit<BaseProduct, 'children' | 'totalNumberOfChildren'>

    The child product that will become the new parent.

refresh

Fetches the product listing.

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.

Creates a BreadcrumbManager sub-controller.

Returns BreadcrumbManager: A BreadcrumbManager sub-controller.

facetGenerator

Creates a FacetGenerator sub-controller.

Returns FacetGenerator: A FacetGenerator sub-controller.

parameterManager

Creates a ParameterManager sub-controller with the specified properties.

Parameters

Returns ParameterManager<P>: A ParameterManager sub-controller.

sort

Creates a Sort sub-controller.

Parameters

  • props: SortProps

    Optional properties for the Sort sub-controller.

Returns Sort: A Sort sub-controller.

urlManager

Creates a UrlManager sub-controller with the specified properties.

Parameters

Returns UrlManager: A UrlManager sub-controller.

interactiveProduct

Creates an InteractiveProduct sub-controller.

Parameters

  • props: Omit<InteractiveProductCoreProps, 'responseIdSelector'>

    The properties for the InteractiveProduct sub-controller.

Returns InteractiveProduct: An InteractiveProduct sub-controller.

pagination

Creates a Pagination sub-controller.

Parameters

  • props: PaginationProps

    The optional properties for the Pagination sub-controller.

Returns Pagination: A Pagination sub-controller.

summary

Creates a Summary sub-controller.

Returns Summary<S>: A Summary sub-controller.

Attributes

state

A scoped and simplified part of the headless state that is relevant to the ProductListing controller.

Properties

  • error: CommerceAPIErrorStatusResponse | null

  • isLoading: boolean

  • products: Product[]

  • responseId: string

Initialize

buildProductListing

Creates a ProductListing controller instance.

Parameters

  • engine: CommerceEngine

    The headless commerce engine.

Returns ProductListing

Sub-controllers

FacetGenerator

Properties

  • facets: GeneratedFacetControllers

    The facet sub-controllers created by the facet generator. Array of RegularFacet, DateRangeFacet, NumericFacet, and CategoryFacet.

  • state: string[]

    The ordered list of facet IDs for which sub-controllers will be created and returned when the facets getter is called.

  • deselectAll: function

    Deselects all values in all facets.

  • subscribe: function

    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.

Pagination

Properties

  • state: PaginationState

    A scoped and simplified part of the headless state that is relevant to the Pagination sub-controller.

  • fetchMoreProducts: function

    Fetches the next page of products, and appends them to the current list of products.

  • nextPage: function

    Navigates to the next page.

  • previousPage: function

    Navigates to the previous page.

  • selectPage: function

    Navigates to a specific page.

    Parameters

    • page: number

      The page to navigate to.

  • setPageSize: function

    Sets the page size.

    Parameters

    • pageSize: number

      The page size.

  • subscribe: function

    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.

ParameterManager<P>

Properties

  • state: ParameterManagerState<T>

    The state relevant to the ParameterManager sub-controller.

  • synchronize: function

    Updates the parameters in the state with the specified parameters and fetches results. Unspecified keys are reset to their initial values.

    Parameters

    • parameters: T

      The parameters to synchronize.

  • subscribe: function

    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.

Sort

Properties

  • state: SortState

    A scoped and simplified part of the headless state that is relevant to the Sort sub-controller.

  • isAvailable: function

    Verifies whether the specified sort criterion is available.

    Parameters

    • criterion: SortByRelevance | SortByFields

      The sort criterion to look for.

      Returns boolean: true if the specified sort criterion is available; false otherwise.

  • isSortedBy: function

    Verifies whether the specified sort criterion is the currently active one.

    Parameters

    • criterion: SortByRelevance | SortByFields

      The sort criterion to evaluate.

      Returns boolean: true if the specified sort criterion is the currently active one; false otherwise.

  • sortBy: function

    Updates the sort criterion and executes a new query.

    Parameters

    • criterion: SortByRelevance | SortByFields

      The new sort criterion.

  • subscribe: function

    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.

Summary<S>

Properties

  • state: State

    A scoped and simplified part of the headless state that is relevant to the SearchSummary sub-controller.

  • subscribe: function

    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.

UrlManager

Properties

  • state: UrlManagerState

    The state relevant to the UrlManager controller.

  • synchronize: function

    Updates the search parameters in state with those from the url and launches a search.

    Parameters

    • fragment: string

      The part of the url that contains search parameters. For example: q=windmill&f[author]=Cervantes.

  • subscribe: function

    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.

HighlightKeyword

Properties

  • length: number

    The length of the offset.

  • offset: number

    The 0 based offset inside the string where the highlight should start.

InteractiveProduct

Properties

  • warningMessage?: string

  • beginDelayedSelect: function

    Prepares to select the result after a certain delay, sending analytics if it was never selected before.

In a DOM context, it’s recommended to call this method on the touchstart event.

  • cancelPendingSelect: function

    Cancels the pending selection caused by beginDelayedSelect.

In a DOM context, it’s recommended to call this method on the touchend event.

  • select: function

    Selects the result, logging a UA event to the Coveo Platform if the result wasn’t selected before.

In a DOM context, it’s recommended to call this method on all of the following events:

  • contextmenu * click * mouseup * mousedown

PaginationProps

Properties

  • options?: Omit<CorePaginationOptions, 'slotId'>

PaginationState

Properties

  • page: number

  • pageSize: number

  • totalEntries: number

  • totalPages: number

ParameterManagerInitialState<T>

Properties

  • parameters: T

    The parameters affecting the response.

ParameterManagerProps<P>

Properties

ParameterManagerState<T>

Properties

  • parameters: T

    The parameters affecting the response.

Product

Properties

  • position: number

    The 1-based product’s position across the non-paginated result set.

    For example, if the product is the third one on the second page, and there are 10 products per page, its position is 13 (not 3).

  • additionalFields: Record<string, unknown>

    The requested additional fields for the product.

  • children: Omit<BaseProduct, 'children' | 'totalNumberOfChildren'>

    The child products of the product, fetched through product grouping.

  • clickUri: string

    The URL of the product.

  • ec_brand: string | null

    The brand of the product.

    From the ec_brand field.

  • ec_category: string[]

    The category of the product (for example, "Electronics;Electronics|Televisions;Electronics|Televisions|4K Televisions").

    From the ec_category field.

  • ec_color: string | null

    The color of the product.

  • ec_description: string | null

    The description of the product.

    From the ec_description field.

  • ec_gender: string | null

    The gender the product is intended for.

  • ec_images: string[]

    The URLs of additional product images.

    From the ec_images field.

  • ec_in_stock: boolean | null

    Whether the product is currently in stock.

    From the ec_in_stock field.

  • ec_item_group_id: string | null

    The ID used for the purpose of product grouping.

    From the ec_item_group_id field.

  • ec_listing: string | null

    The listing that the product belongs to.

  • ec_name: string | null

    The name of the product.

    From the ec_name field.

  • ec_price: number | null

    The base price of the product.

    From the ec_price field.

  • ec_product_id: string | null

    The product ID.

  • ec_promo_price: number | null

    The promotional price of the product.

    From the ec_promo_price field.

  • ec_rating: number | null

    The product rating, from 0 to 10.

    From the ec_rating field.

  • ec_shortdesc: string | null

    A short description of the product.

    From the ec_shortdesc field.

  • ec_thumbnails: string[]

    The URLs of the product image thumbnails.

    From the ec_thumbnails field.

  • permanentid: string

    The SKU of the product.

  • totalNumberOfChildren: number | null

    The total number of child products fetched through product grouping.

  • excerpt?: string | null

    The contextual excerpt generated for the product.

  • excerptsHighlights?: HighlightKeyword[]

    The length and offset of each word to highlight in the product excerpt string.

  • nameHighlights?: HighlightKeyword[]

    The length and offset of each word to highlight in the product name.

SortInitialState

Properties

  • criterion?: SortByRelevance | SortByFields

    The initial sort criterion to register in state.

SortProps

Properties

  • initialState?: SortInitialState

    The initial state that should be applied to this Sort sub-controller.

SortState

Properties

  • appliedSort: SortByRelevance | SortByFields

    The current sort criterion.

  • availableSorts: SortByRelevance | SortByFields

    The available sort criteria.

Unsubscribe

Call signatures

  • (): void;

UrlManagerInitialState

Properties

  • fragment: string

    The part of the url that contains search parameters. For example: q=windmill&f[author]=Cervantes.

UrlManagerProps

Properties

UrlManagerState

Properties

  • fragment: string

    The part of the url that contains search parameters. For example: q=windmill&f[author]=Cervantes.