From 76ff7318f49d2218142c756e18e89cda2c212ab9 Mon Sep 17 00:00:00 2001 From: Erik Marr Date: Tue, 19 May 2026 12:51:17 -0500 Subject: [PATCH 1/2] Updating as per PREX-2204 --- .../containers/product-list.mdx | 48 +++++++++++++++--- .../product-recommendations.mdx | 49 +++++++++++++++---- 2 files changed, 80 insertions(+), 17 deletions(-) diff --git a/src/content/docs/dropins/recommendations/containers/product-list.mdx b/src/content/docs/dropins/recommendations/containers/product-list.mdx index 0fdadc9e9..1be265409 100644 --- a/src/content/docs/dropins/recommendations/containers/product-list.mdx +++ b/src/content/docs/dropins/recommendations/containers/product-list.mdx @@ -1,12 +1,13 @@ --- title: ProductList container -description: Show Adobe Commerce product recommendations for the active SKU using routing callbacks plus recId and placement configuration. +description: Show Adobe Commerce product recommendations using recId, optional currentProduct context, routing callbacks, and placement configuration. --- import Diagram from '@components/Diagram.astro'; import OptionsTable from '@components/OptionsTable.astro'; +import Aside from '@components/Aside.astro'; -The `ProductList` container manages and displays a list of recommended products based on the current product. Its behavior is driven by configuration options such as `currentSku`, `recId`, and `routing` through `routeProduct` callbacks. +The `ProductList` container manages and displays a list of recommended products based on the current product. Its behavior is driven by configuration options such as `currentProduct`, `recId`, and routing through `routeProduct` callbacks. ![ProductList container](@images/dropins/recommendations/product-list.png) @@ -21,7 +22,8 @@ The `ProductList` container provides the following configuration options: options={[ ['Option', 'Type', 'Req?', 'Description'], ['recId', 'string', 'Yes', 'Unique identifier for the recommendation unit.'], - ['currentSku', 'string', 'Yes', 'Current SKU for recommendation context.'], + ['currentProduct', 'object', 'No', 'Current product context (`{ sku: string; price?: number }`). See [Product context](#product-context).'], + ['currentSku', 'string', 'No', 'Deprecated as of v4.0.3. Use `currentProduct` instead.'], ['cartSkus', 'string[]', 'No', 'Cart SKUs for recommendation context.'], ['userPurchaseHistory', 'any[]', 'No', 'User Purchase History for recommendation context.'], ['userViewHistory', 'any[]', 'No', 'User View History for recommendation context.'], @@ -33,12 +35,44 @@ The `ProductList` container provides the following configuration options: ]} /> + + +## Product context + +Pass product context with the optional `currentProduct` prop: + +```ts +currentProduct?: { sku: string; price?: number }; +``` + +How context is supplied depends on where the unit is rendered: + +- **PDP pages**: The Commerce boilerplate block reads `currentProduct` from the Adobe Client Data Layer (ACDL) product context. You do not need to pass `currentProduct` in block configuration. +- **Non-PDP pages**: Set `currentsku` and/or `currentprice` in the [product-recommendations block configuration](/merchants/content-customizations/product-recommendations/#configuration) table to provide product context explicitly. +- **Context-free units**: If neither `currentsku` nor ACDL product context is available, `currentProduct` is `undefined`. The dropin still renders as long as `recId` is provided. + +## Query routing + +The container selects a GraphQL query based on the `currentProduct` shape: + +- When `currentProduct.price` is present (**Adobe Commerce Optimizer and Adobe Commerce as a Cloud Service only**): uses `GetRecommendationsByUnitIdsWithCurrentProduct`, which supports dynamic price filter operators. +- When only `currentProduct.sku` is present, or `currentProduct` is absent: uses `GetRecommendationsByUnitIds`, which is compatible with all backend types including PaaS. + The `ProductListProps` interface has the following shape: ```ts export interface ProductListProps extends HTMLAttributes { recId: string; - currentSku: string; + currentProduct?: { + sku: string; + price?: number; + }; + /** @deprecated As of v4.0.3. Use `currentProduct` instead. */ + currentSku?: string; initialData?: { recommendations?: { results: RecommendationUnitModel[]; @@ -148,7 +182,7 @@ Each slot receives context data relevant to its purpose, allowing for highly cus ## Example configuration -The following example demonstrates how to render the `ProductList` container with the `recId`, `currentSku`, and `routeProduct` callbacks with different slots: +The following example demonstrates how to render the `ProductList` container with `recId`, `currentProduct`, and `routeProduct` callbacks with different slots: ```js @@ -156,7 +190,7 @@ The following example demonstrates how to render the `ProductList` container wit provider.render(ProductList, { recId: 'recommendation-unit-1', routeProduct: (item) => `/products/${item.urlKey}`, - currentSku: 'ADB150', + currentProduct: { sku: 'ADB150', price: 49.99 }, hideHeading: false, slots: { // Example of how to prepend or append to the default Heading @@ -227,7 +261,7 @@ provider.render(ProductList, { ## Key Features -- **Automatic Data Fetching**: Fetches recommendations based on `currentSku` and other context +- **Automatic Data Fetching**: Fetches recommendations based on `currentProduct` (or legacy `currentSku`) and other context - **Intersection Observer**: Automatically tracks when recommendations are viewed - **Event Publishing**: Publishes render and view events for analytics - **Loading States**: Handles loading states during data fetching diff --git a/src/content/docs/merchants/content-customizations/product-recommendations.mdx b/src/content/docs/merchants/content-customizations/product-recommendations.mdx index b3ab9ae99..3c57aa412 100644 --- a/src/content/docs/merchants/content-customizations/product-recommendations.mdx +++ b/src/content/docs/merchants/content-customizations/product-recommendations.mdx @@ -23,24 +23,31 @@ Add this table to your document to configure the block: product-recommendations -currentSku +recId +2ed7ea09-d9bd-4691-91c3-2c0a6d4fd869 (example) + + +currentsku crz-eco-tr-std-2017 (example) -recId -2ed7ea09-d9bd-4691-91c3-2c0a6d4fd869 (example) +currentprice +49.99 (example) -- **recId**: Recommendation ID for targeting specific recommendation types. Required for all pages. No default value. +- **recId**: Recommendation unit ID from the Admin. Required for all pages. + +- **currentsku**: Current product SKU. Required for non-PDP pages only. On PDP pages, the boilerplate reads this automatically from the product context (Adobe Client Data Layer). -- **currentSku**: Current product SKU for recommendation context. Required for non-PDP pages only. Not needed for product detail pages. No default value. +- **currentprice**: Current product price (numeric). Required on non-PDP pages when using dynamic price filter operators (Adobe Commerce Optimizer and Adobe Commerce as a Cloud Service only). On PDP pages, the boilerplate reads this automatically from the product context. @@ -123,9 +130,9 @@ You can configure each page to display a specific recommendation unit by setting :::note - PDP pages require only the `recId` to be set as shown above. + PDP pages require only `recId`, as shown above. - Other pages require both the `recId` and `currentSku` to be set. For example: + Other pages that need product context require `recId` and `currentsku`. For example: @@ -133,13 +140,35 @@ You can configure each page to display a specific recommendation unit by setting - + + + + + + +
product-recommendations
currentSkurecId2ed7ea09-d9bd-4691-91c3-2c0a6d4fd869
currentsku crz-eco-tr-std-2017
+ + When the unit uses dynamic price filter operators on Adobe Commerce Optimizer or Adobe Commerce as a Cloud Service, also set `currentprice` on non-PDP pages: + + + + + + + + + + + + + +
product-recommendations
recId 2ed7ea09-d9bd-4691-91c3-2c0a6d4fd869
currentskucrz-eco-tr-std-2017
currentprice49.99
From 04ef64848ffb7becdc31bc95c0db26c7e6a85b8d Mon Sep 17 00:00:00 2001 From: Erik Marr <45772211+erikmarr@users.noreply.github.com> Date: Thu, 28 May 2026 09:58:09 -0500 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Bruce Denham --- .../docs/dropins/recommendations/containers/product-list.mdx | 4 ++-- .../content-customizations/product-recommendations.mdx | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/dropins/recommendations/containers/product-list.mdx b/src/content/docs/dropins/recommendations/containers/product-list.mdx index 1be265409..509a49bd6 100644 --- a/src/content/docs/dropins/recommendations/containers/product-list.mdx +++ b/src/content/docs/dropins/recommendations/containers/product-list.mdx @@ -59,8 +59,8 @@ How context is supplied depends on where the unit is rendered: The container selects a GraphQL query based on the `currentProduct` shape: -- When `currentProduct.price` is present (**Adobe Commerce Optimizer and Adobe Commerce as a Cloud Service only**): uses `GetRecommendationsByUnitIdsWithCurrentProduct`, which supports dynamic price filter operators. -- When only `currentProduct.sku` is present, or `currentProduct` is absent: uses `GetRecommendationsByUnitIds`, which is compatible with all backend types including PaaS. +- When `currentProduct.price` is present (**Adobe Commerce Optimizer and Adobe Commerce as a Cloud Service only**), the container uses `GetRecommendationsByUnitIdsWithCurrentProduct`, which supports dynamic price filter operators. +- When only `currentProduct.sku` is present, or `currentProduct` is absent, the container uses `GetRecommendationsByUnitIds`, which is compatible with all backend types, including PaaS. The `ProductListProps` interface has the following shape: diff --git a/src/content/docs/merchants/content-customizations/product-recommendations.mdx b/src/content/docs/merchants/content-customizations/product-recommendations.mdx index 3c57aa412..69399695a 100644 --- a/src/content/docs/merchants/content-customizations/product-recommendations.mdx +++ b/src/content/docs/merchants/content-customizations/product-recommendations.mdx @@ -39,7 +39,7 @@ Add this table to your document to configure the block: - **recId**: Recommendation unit ID from the Admin. Required for all pages. -- **currentsku**: Current product SKU. Required for non-PDP pages only. On PDP pages, the boilerplate reads this automatically from the product context (Adobe Client Data Layer). +- **currentsku**: Current product SKU. Required on non-PDP pages when the recommendation unit needs product context. On PDP pages, the boilerplate reads this automatically from the product context (Adobe Client Data Layer). - **currentprice**: Current product price (numeric). Required on non-PDP pages when using dynamic price filter operators (Adobe Commerce Optimizer and Adobe Commerce as a Cloud Service only). On PDP pages, the boilerplate reads this automatically from the product context. @@ -150,7 +150,7 @@ You can configure each page to display a specific recommendation unit by setting - When the unit uses dynamic price filter operators on Adobe Commerce Optimizer or Adobe Commerce as a Cloud Service, also set `currentprice` on non-PDP pages: + When using dynamic price filter operators on Adobe Commerce Optimizer or Adobe Commerce as a Cloud Service, set `currentprice` on non-PDP pages: