The HeaderBanner-ATGCategory cartridge displays the header banner defined for the currently selected category on category pages.

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 HeaderBanner-ATGCategory cartridge, located in <ATG10dir>/CommerceReferenceStore/Store/Storefront/deploy/cartridge_templates/HeaderContent-HeaderBanner-ATGCategory.xml, sets the cartridge’s content type to HeaderContent and its ID to HeaderBanner-ATGCategory. There are no editable properties defined for the HeaderBanner-ATGCategory cartridge; all of its content is dynamically generated by the handler.

Content Item and Handler

The atg.projects.store.assembler.cartridge.CategoryHeaderBannerContentItem class represents the content item that the HeaderBanner-ATGCategory cartridge returns to the renderer. The CategoryHeaderBannerContentItem class has three properties:

The /atg/endeca/assembler/cartridge/handler/CategoryHeaderBanner component, which is of class atg.projects.store.assembler.cartridge.handler.CategoryHeaderBannerHandler, is the cartridge handler responsible for creating and populating the CategoryHeaderBannerContentItem object. The CategoryHeaderBannerHandler class is an extension of the com.endeca.infront.cartridge.NavigationCartridgeHandler class with an overridden process() method. The process() method retrieves the current navigation state from the /atg/endeca/assembler/cartridge/manager/NavigationState component and creates a new CategoryHeaderBannerContentItem object. A call to the CategoryHeaderBannerHandler.loadBannerItemDetails() method populates the CategoryHeaderBannerContentItem object with data from the catalog repository and returns it to the JSP renderer.

The process() method also calls the CategoryHeaderBannerHandler.validateItem() method, which applies the CollectionObjectValidator components listed in the validators property to the hero image item and the promotional content item to validate them. By default, the validators property is set to the /atg/store/collections/validator/StartEndDateValidator component.

To populate the content item, the loadBannerItemDetails() method uses the /atg/endeca/assembler/cartridge/StoreCartridgeTools component to retrieve the currently chosen category and its associated top-level category from the atg.projects.store.catalog.CatalogNavigationService class. The loadBannerItemDetails() method sets the content item’s headerTitle property to the current category’s displayName value. It also sets the backgroundBannerURL and promotionalContentId content item properties using the values specified for the top-level category’s heroImage and feature properties.

Note: A category’s feature and myFeature properties work together to ensure that a promotional content item is always returned for a category. For more information on these properties, see the Product Catalog chapter.

Note: If the CatalogNavigationService class returns null for the current category and top-level category IDs, it means that the CategoryHeaderBanner has been incorrectly placed on a browse page and the cartridge should not be rendered. The CategoryHeaderBanner component tests for this situation and handles it appropriately.

To do its tasks, the CategoryHeaderBanner component has two configurable properties:

The CategoryHeaderBanner component also inherits a number of properties from the /atg/endeca/assembler/cartridge/handler/NavigationCartridgeHandler component, through a $basedOn property configuration. Specifically, CategoryHeaderBanner inherits a reference to the /atg/endeca/assembler/cartridge/manager/NavigationState component that provides information on the shopper’s current navigation state.

JSP Renderer

The store.war/cartridges/HeaderBanner-ATGCategory/HeaderBanner-ATGCategory.jsp page renders the content in the CategoryHeaderBannerContentItem object. This renderer retrieves the headerTitle and headerBannerURL values from the CategoryHeaderBannerContentItem object and uses these values to render the display name and background image for the banner. HeaderBanner-ATGCategory.jsp also retrieves the promotionalContentId value and passes it to the /atg/commerce/promotional/PromotionalContentLookup component to render the promotional content item. This component is of class atg.commerce.catalog.custom.CatalogItemLookupDroplet and it specifies the catalog repository as the repository to be searched and promotionalContent as the item type to search for.

When a promotional content item that includes a link is clicked, it takes the shopper to the page specified in the promotional content item’s associatedCategory property. The link for this page must be constructed using an Endeca URL. To satisfy this requirement, the template used to render promotional content items, store.war/promo/gadgets/linkedImage.jsp, uses the <crs:promotionalContentWrapper.tag>. This tag calls the /atg/commerce/endeca/cache/DimensionValueCacheDroplet servlet bean to retrieve the correct URL for the associatedCategory and then it associates that URL value with the link reference.

Note: See the ATG-Endeca Integration Guide for information about the DimensionValueCacheDroplet servlet bean and the cache.