Although a catalog is usually structured hierarchically, the hierarchical structure is not rigid. A category or product can be the child of more than one category, so there can be multiple paths to any catalog item. In addition, your pages may have links to related products that enable users to jump from one part of the hierarchy to another, and other navigational aids such as search facilities.
ATG Commerce provides components that you can use to keep track of the path a customer follows when moving around your site. This tracking method, called historical navigation, enables you to construct a list of the items the customer has visited, and create and display links to these items, so the customer can easily get back to them.
The atg.commerce.catalog.CatalogNavHistory class tracks the customer’s path through the catalog. CatalogNavHistory is a subclass of atg.repository.servlet.NavHistory, which can be used to track navigation history over any set of pages that display repository content. ATG Commerce includes a session-scoped CatalogNavHistory component at /atg/commerce/catalog/CatalogNavHistory.
CatalogNavHistory maintains a stack of locations the customer has visited, consisting of the actual repository items the customer viewed. It stores these locations (items) in the navHistory property.
CatalogNavHistory tracks the customer’s path across all possible actions:
When the customer navigates down the hierarchy by clicking a navigational link, an item is pushed onto the stack.
When the customer navigates up the hierarchy by clicking a navigational link or the Back button, the appropriate item is removed from the stack, and the new item is pushed onto the stack.
When the customer jumps to an unrelated area of the site, whether by a global navigation or some other link, the path jumps to that area. If there is a default navigation path to the new page, as in a hierarchical structure,
CatalogNavHistoryuses that default path.
To add and remove items in the navHistory array, use the CatalogNavHistoryCollector servlet bean, which is of class atg.repository.servlet.NavHistoryCollector. This servlet bean takes the following input parameters:
item- The repository item currently being viewed.navAction- The operation to be performed on the stack. Options are push, pop, and jump. A blanknavActionis treated as push.navCount- Used to detect use of the Back button. ThenavCountparameter should be passed in with any link that leads to a page that uses breadcrumbs. It must be embedded in a link to enable the target page to detect Back button usage. For example:<dsp:getvalueof id="templateUrl" idtype="String"
param="element.template.url">
<dsp:a page="<%=templateUrl%>">
<dsp:param name="id" param="element.repositoryId"/>
<dsp:param name="navAction" value="push"/>
<dsp:param name="navCount"
bean="/atg/commerce/catalog/CatalogNavHistory.navCount"/>
<dsp:valueof param="element.displayName"/>
</dsp:a>
</dsp:getvalueof>The
navCountparameter can be used to prevent errors in thenavHistorycaused by the of the use of the Back button. ThenavCountparameter can be used to detect when Back button is used and theCatalogNavHistoryCollectorresets the stack appropriately.For example, if you open a page that displays links to categories, each category link should have an embedded
navCountparameter withnavCount=1. If you browse the catalog for a while and then use the Back button to return to the original page, you are given the page that was cached by your browser. The page isn’t rendered again by ATG Commerce. The category links in that page still havenavCount=1. If you click one of those links, theCatalogNavHistoryCollectorin the target page compares the stalenavCountpage parameter that was passed with the link to thecurrentvalueof/atg/commerce/catalog/CatalogNavHistory.navCount. These values won’t match because the parameter from the link is stale, so theCatalogNavHistoryCollectorknows that the Back button was used and rebuilds thenavHistory.
Collecting the Customer’s History
Use the navAction push operation to collect a user’s navigation history. In the first part of our example, below, the JSP code adds an item to the navHistory stack when the customer clicks the link to CategoryPage.jsp, permitting you to track their path.
<dsp:droplet name="/atg/targeting/TargetingForEach"> <dsp:param bean="/atg/registry/RepositoryTargeters/ProductCatalog /RootCategories" name="targeter"/> <dsp:oparam name="output"> <p> <! ATTENTION: Here we set up the navCount and navAction parameters which will indicate to the next page how it should update its CatalogNavHistory collector. In particular, to set the navCount, we query the CatalogNavHistory component, asking it for a number that identifies its current state. !> %> <dsp:a href="CategoryPage.jsp"> <dsp:valueof param="element.displayName"/> <dsp:param param="element.repositoryId" name="itemId"/> <dsp:param bean="/atg/commerce/catalog/CatalogNavHistory.navCount" name="navCount"/> <dsp:param value="push" name="navAction"/> </dsp:a> </dsp:oparam> </dsp:droplet>
Rendering the Customer’s Path
This second half of our example shows how to render a list of the locations the customer has visited. First, update CatalogNavHistory with the current location, using the category, navAction, and navCount parameters passed to the page that embeds this fragment, along with the CatalogNavHistoryCollector component, which updates CatalogNavHistory.
If the Back button is detected, CatalogNavHistory clears the stack and generates a new one for the current page, using the default parent property of the catalog.
<dsp:droplet name="/atg/commerce/catalog/CatalogNavHistoryCollector"> <dsp:param param="categoryObj" name="item"/> <dsp:param param="navAction" name="navAction"/> <dsp:param param="navCount" name="navCount"/> </dsp:droplet>
Then use a servlet bean such as the following to display the user’s trail. The servlet bean lists the names of each category held by the CatalogNavHistory component and creates a link to the Category page that displays them, . The following parameters are passed:
itemId- holds the categoryrepositoryIdnavAction- set with the value of “pop,” indicating that theCatalogNavHistoryshould clear its stack and rebuild it using the default parent category propertynavCount- holds the index for each category element from theCatalogNavHistory.navHistoryarray
The pageType parameter passed to this servlet bean indicates what type of page is calling it. If the servlet bean is called from a category page, the last category entry in CatelogNavHistory component is not made into a link. However, if the servlet bean is called from a product page, the last entry is made into a link, because it represents the product’s parent category.
<dsp:droplet name="/atg/dynamo/droplet/ForEach"> <dsp:param bean="/atg/commerce/catalog/CatalogNavHistory.navHistory" name="array"/> <dsp:oparam name="output"> <dsp:droplet name="/atg/dynamo/droplet/Switch"> <dsp:param param="count" name="value"/> <dsp:getvalueof id="nameval1" param="size" idtype="java.lang.String"> <dsp:oparam name="<%=nameval1%>"> <dsp:droplet name="/atg/dynamo/droplet/Switch"> <dsp:param param="pageType" name="value"/> <dsp:oparam name="product"> <dsp:a href="CategoryPage.jsp"> <dsp:param param="element.repositoryId" name="itemId"/> <dsp:param value="pop" name="navAction"/> <dsp:param param="index" name="navCount"/> <dsp:valueof param="element.displayName"/> </dsp:a> </dsp:oparam> <dsp:oparam name="default"> <dsp:valueof param="element.displayName"/> </dsp:oparam> </dsp:droplet> </dsp:oparam> </dsp:getvalueof> <dsp:oparam name="default"> <dsp:a href="CategoryPage.jsp"> <dsp:param param="element.repositoryId" name="itemId"/> <dsp:param value="pop" name="navAction"/> <dsp:param param="index" name="navCount"/> <dsp:valueof param="element.displayName"/> </dsp:a> > </dsp:oparam> </dsp:droplet> </dsp:oparam> </dsp:droplet>
Tracking Location Jumps
This more generic example shows how to track customer navigation outside of normal history collection, such as with a hard-coded link that deviates from hierarchical navigation.
<a href="param:featuredProduct.template.url"> <param name="id" value="param:featuredProduct.repositoryId"> <param name="navAction" value="jump"> <param name="navCount" value="property:/atg/commerce/catalog/CatalogNavHistory.navCount"> link text </a>
