ATG Commerce Search Guide

Because facet selections are cumulative, it is necessary to keep track of each facet selection a customer has made so far. This is done through a facet trail, which is stored as an object of class atg.repository.search.refinement.FacetTrail.

A facet trail is similar to a navigational breadcrumb trail, where each entry consists of a facet and a selection value or range for that facet. For example, a facet trail might be rendered on the page like this:

The first time the page is displayed, you can set the facet trail explicitly, or leave it empty. When the user makes a facet selection, you append entries to or delete entries from the facet trail, and include the updated facet trail in the new search query.

You can update the facet trail using the CommerceFacetTrailDroplet. This servlet bean takes as input a string representation of the current FacetTrail object plus instructions for modifying the facet trail based on selections chosen by the customer. (Typically these inputs are passed through HTTP request query parameters.) From these inputs, the CommerceFacetTrailDroplet constructs a new FacetTrail object.

For example, suppose a site visitor navigates by first selecting the Televisions category, and then selecting the LCD Televisions subcategory. (This assumes that Category is defined as a facet; see the ATG Merchandising User Guide.) Next, she chooses the “$1000 to $2000” selection range for the price facet, and then chooses “Acme” as the selection value for the manufacturer facet. The facet trail string might now look something like this:

1:cat444323:1:cat333222:2:1000-2000:32:Acme

In this example, cat444323 is the repository ID of the Televisions category, and cat333222 is the repository ID of the LCD Televisions category. The example also assumes the following facets have been defined in ATG Merchandising:

1 = category
2 = price
32 = manufacturer

The number identifying the facet is the repository ID of the corresponding refinementElement in the refinement repository, which is also used as the ID of the refinementElement XML attribute in the refinement configuration.

Your pages should display the current facets and selections, along with links for removing the selections. (Typically a link for removing a facet is an image of an X, or the word “remove.”) Suppose the site visitor now clicks the link to remove the Televisions facet. When a category selection value is removed from the facet trail, all of that category’s subcategories are also removed, so in this case the LCD Televisions category is removed as well. (In addition, any category-specific facets and selection values that no longer apply are also removed. For example, if the Televisions category has a Screen Size facet associated with it, removing the Televisions facet from the trail also removes the Screen Size facet and selections.)

The new facet trail string is therefore:

2:1000-2000:32:Acme

The displayed search results now consist of all products priced between $1000 and $2000 whose manufacturer is Acme. So if Acme also manufactures stereo systems, the ones in this price range will now be displayed.

Last Range Indicator

If a site visitor chooses the last selection range for a facet, the facet trail must indicate this in some way. When a subsequent query is issued to ATG Search, this information is used in constructing the corresponding constraint.

Suppose in the example above the price facet has three selection ranges: $500 to $1000, $2000 to $3000, and $3000 to $4000. If the site visitor selects the $3000 to $4000 range, the facet trail string would look like this:

2:3000-4000|LAST:32:Acme

Note that although |LAST is included in the facet trail string (and therefore may appear in URLs), it is not part of the label for the selection range, and therefore does not appear on the page itself. Also, you do not need to code your JSPs in any special way to deal with this selection range.

For more information about CommerceFacetTrailDroplet, see Appendix A, Commerce Search Servlet Beans.