The ProductSpotlight-ATGCategoryRelatedProducts cartridge displays any related products, or cross-sells, defined for the currently selected category on category pages. Out of the box, this cartridge is not used by Commerce Reference Store but Commerce Reference Store’s deployment template does make it available for selection in Experience Manager.

Note: This cartridge should only be used on category pages. If you place it on a browse page, it will not render any content. See Category Pages versus Browse Pages for more details on the differences between the two page types.

Template

The XML template for the ProductSpotlight-ATGCategoryRelatedProducts cartridge, located in <ATG10dir>/CommerceReferenceStore/Store/Storefront/deploy/cartridge_templates/MainContent-ProductSpotlight-ATGCategoryRelatedProducts.xml, sets the cartridge’s content type to MainContent and its ID to ProductSpotlight-ATGCategoryRelatedProducts. The XML template defines one editable property, numberOfRecords, that specifies the number of cross-sell products to show for the current category. By default, numberOfRecords is set to 4.

Content Item and Handler

The atg.projects.store.assembler.cartridge.CategoryRelatedProductsContentItem class represents the content item that the ProductSpotlight-ATGCategoryRelatedProducts cartridge returns to the renderer. The CategoryRelatedProductsContentItem class has three properties:

The /atg/endeca/assembler/cartridge/handler/CategoryRelatedProducts component, which is of class atg.projects.store.assembler.cartridge.handler.CategoryRelatedProductsHandler, is responsible for creating and populating the CategoryRelatedProductsContentItem object. The CategoryRelatedProductsHandler class is an extension of the com.endeca.infront.cartridge.NavigationCartridgeHandler class.

The CategoryRelatedProducts component uses the methods provided by the /atg/endeca/assembler/cartridge/StoreCartridgeTools component to get the ID for the current category. Once it has the ID, CategoryRelatedProducts can retrieve the list of related products for the correct category from the catalog repository. To do this, CategoryRelatedProducts uses its relatedProductsProperties property to determine which category item properties contain related products (out of the box, this property is set to a single repository item property, relatedProducts). CategoryRelatedProducts then retrieves the related products from those properties. The number of products retrieved is limited by the numberOfRecords value specified in the cartridge configuration.

CategoryRelatedProducts may also apply an ATG filter to the list of products it retrieves, for example, to filter out products that are not appropriate for the current site context. The filter to apply is configured by the CategoryRelatedProducts.filter property. Out of the box, CategoryRelatedProducts.filter is set to /atg/store/collections/filter/CatalogItemFilter, which filters out products based on their start and end dates.

The CategoryRelatedProducts component has the following configurable properties:

JSP Renderer

The store.war/cartridges/ProductSpotlight-ATGCategoryRelatedProducts/ProductSpotlight-ATGCategoryRelatedProducts.jsp page renders the content in the CategoryRelatedProductsContentItem object. This renderer retrieves the list of products from the content item’s relatedProducts property. If this list is empty, either because no related products exist for the category or because the ProductSpotlight-ATGCategoryRelatedProducts cartridge was inadvertently placed on a browse page instead of a category page, then the products and the label that introduces them are not rendered.

The “Related Items” label that appears above the product spotlight row in the main content area, along with its translated versions, is stored in the StoreText repository in the product_spotlight_categoryRelatedProductsTitle item and may be edited in the Business Control Center.