The product comparison system consists of the following four classes in the atg.commerce.catalog.comparison package:

ComparisonList

atg.commerce.catalog.comparison.ComparisonList provides a generic data structure to maintain an ordered list of items that the user may want to compare, as well as an associated set of sort directives to apply when displaying the items in the list. The objects in the list may be of any Java class. Like Java List classes, ComparisonList maintains the insertion order of items in the list. Unlike List classes, it prohibits duplicate entries in the list by ignoring requests to add items that compare equal to items already in the list.

The following table describes the ComparisonList methods used to maintain a list of items to compare. For additional methods and details, refer to the ATG API Reference.

Method

Description

addItem

Adds an item to the end of the comparison list if the item isn’t already present in the list.

clear

Removes all items from the comparison list.

containsItem

Returns true if the comparison list contains the specified item.

getItem(n)

Returns the item at the specified index in the comparison list.

getItems

Returns the list of items being compared.

indexOf

Returns the index of the specified item in the comparison list; returns -1 if the item does not appear in the list.

removeItem

Removes an item from the comparison list if it was present in the list.

size

Returns the number of items in the comparison list.

ComparisonList internally synchronizes operations on the list. This makes it possible for multiple request-scoped servlet beans and form handlers to operate safely on a shared session-scoped ComparisonList, as long as all changes to the list are made through the ComparisonList API. Note that if your application calls the getItems method to obtain a reference to the list, you should synchronize all operations on the list or call the java.util.Collections.synchronizedList method to obtain a thread-safe version of the list upon which to operate.

ComparisonList maintains a property of type atg.service.util.TableInfo as a convenience to the developer. In cases where the comparison information will be displayed as a table, this provides an easy way to associate default table display properties with a comparison list. ATG Commerce includes a session-scoped instance of TableInfo, located in Nucleus at /atg/commerce/catalog/comparison/TableInfo. For more information about the TableInfo component and how to use it to display sortable tables, see the Implementing Sortable Tables chapter in the ATG Page Developer’s Guide.

Use ComparisonList when you want to compare sets of simple Java beans, repository items, user profiles, or other self-contained objects. If you want to compare more complex objects, or sets of objects against each other, you’ll want to subclass ComparisonList to be able to manage application-specific objects.

ProductComparisonList

ProductComparisonList extends ComparisonList, providing an API designed to manage and compare products and SKUs. ProductComparisonList uses the items property to store a list of Entry objects, each of which represents a product or SKU that the user has added to her product comparison list. Entry is an inner class defined by ProductComparisonList; it combines category, product, SKU, and inventory information about a product into a single object.

You can configure additional instances of ProductComparisonList in Nucleus to provide multiple comparison lists (for example, a list to compare cameras, a different list to compare televisions, and so on).

The API for ProductComparisonList

The public API for ProductComparisonList can be divided broadly into the following four categories:

There are several different variations on the add, remove, and contains methods. The various methods take different sets of arguments to support a wide range of application behaviors. For example, there are remove methods to remove all entries for a specific product, to remove all entries for all products in a specified category, and to remove the entry for a particular category/product/SKU combination.

Additionally, several methods of ProductComparisonList take an optional catalogKey parameter. This String parameter is useful for applications using catalog localization because it enables you to specify the product catalog to use when operating on a product comparison list. Through the catalogKey parameter, you pass a key to CatalogTools, which then uses the given key and its key-to-catalog mapping to select a product catalog repository.

Refer to the ATG API Reference for additional information on the public API for ProductComparisonList. Also note that there is one important protected method:

Protected Entry createListEntry(RepositoryItem pCategory, RepositoryItem pProduct, RepositoryItem pSku)

The createListEntry method is called to create a new list entry with a given category, product, and SKU. By subclassing ProductComparisonList and overriding createListEntry, you can extend or replace the properties of the Entry object. See Extending the Product Comparison System for more information.

The Entry Inner Class

The public API for the Entry class exposes various properties that the page developer can display in a product comparison list or table. The default implementation includes the following properties:

Property Name

Property Type

Description

product

RepositoryItem

The product being compared.

category

RepositoryItem

The category of the product being compared. If the category is not set explicitly when the product is added to the list, then the product’s default parent category is used. If the product’s default parent category is unset, the category property is null.

sku

RepositoryItem

The product’s SKU. If the SKU is not set explicitly when the product is added to the list, then the first SKU in the product’s childSkus list is used. If the product has no child SKUs, then the sku property is null.

inventoryInfo

InventoryData

The InventoryData object that describes the inventory status for the given product and SKU. If the sku property is null or the inventory information isn’t available, then the inventoryInfo property is null. (See the next section for more information on the InventoryData object.)

productLink

String

An HTML fragment that specifies an anchor tag that links to the product’s page in the catalog. The default format for the link is <a href="product.template.url?id=product.repositoryId">product.displayName</a>. However, you can change the format by setting the ProductComparisonList.productLinkFormat property.

Note: If you display the product comparison information in a table, you can use the productLink property in the configuration of the TableInfo object that maintains the table information, as in the following example:

columns=\
  Product Name=productLink,\
  Price=sku.listPrice,\
  …

Or, similarly, to display the product link in a table column but sort the column on the product’s display name, you could modify the example in the following manner:

columns=\
    Product Name=productLink; product.displayName,\
    Price=sku.listPrice,\
    …

For more information on the TableInfo component, see the Implementing Sortable Tables chapter in the ATG Page Developer’s Guide.

categoryLink

String

An HTML fragment that specifies an anchor tag that links to the category’s page in the catalog. The default format for the link is <a href=category.template.url?id=category.repositoryId>category.displayName</a>. However, you can change the format by setting the ProductComparisonList.categoryLinkFormat property.

Note: Like the productLink property, the categoryLink property can be used in the configuration of a TableInfo component. See the description of the productLink property in this table for more information.

id

Int

A unique ID that names the list entry. You can use this property to retrieve individual entries by calling ProductComparisonList.getItems(id) in the Java code or by using <dsp:valueof bean="ProductList.entries[id]"/> in the .jsp page.

You can also use this property to delete specific entries, for example, with a form handler. For a JSP example, refer to Examples of Product Comparison Pages in the Implementing Product Comparison chapter of the ATG Commerce Guide to Setting Up a Store.

A page developer can refer to the properties of the Entry objects using familiar JSP syntax, as in the following example:

<dsp:droplet name="ForEach">
  <dsp:param bean="ProductComparisonList.items" name="array"/>

  <dsp:oparam name="output">
    <p>Product Name: <dsp:valueof
param="element.product.displayName"/><br>
       Category: <dsp:valueof param="element.category.displayName"/><br>
       Inventory: <dsp:valueof
param="element.inventoryInfo.inventoryAvailabilityMsg"/><br>
  </dsp:oparam>

</dsp:droplet>

The InventoryData Inner Class

The getInventoryInfo() method of the Entry inner class (class atg.commerce.catalog.comparison.ProductComparisonList.Entry) returns an instance of the InventoryData inner class (class atg.commerce.catalog.comparison.ProductComparisonList.Entry.InventoryData).

The InventoryData object stores the inventory data for a given item in the product comparison list. It returns a subset of the readable properties of an InventoryInfo object (class atg.commerce.inventory.InventoryInfo). However, unlike an InventoryInfo object, an InventoryData object is serializable, which enables it to participate in session failover. For a list of InventoryData properties, refer to the ATG API Reference.

ProductListContains

When given a category, product, and SKU, the ProductListContains servlet bean queries whether a product comparison list includes the given product.

The behavior of ProductListContains parallels that of ProductComparisonList. Namely, you can specify a product ID with or without an accompanying category or SKU. In the latter situation, ProductListContains behaves as follows:

For a list of the input, output, and open parameters for ProductListContains, and for JSP examples of how page developers can use ProductListContains, refer to the Implementing Product Comparison chapter of the ATG Commerce Guide to Setting Up a Store.

ProductListHandler

The ProductListHandler form handler manages product comparison lists. By default, ATG Commerce includes a session-scoped instance of ProductListHandler, located in Nucleus at /atg/commerce/catalog/comparison/ProductListHandler. It is configured to operate on the product comparison list located at /atg/commerce/catalog/comparison/ProductList.

If your application uses multiple instances of ProductComparisonList to manage multiple product comparison lists (for example, a list to compare cameras and a different list to compare televisions), then you may want to configure multiple instances of ProductListHandler to manage the contents of each list.

If your application uses alternate product catalogs for different locales, you can specify the product catalog to use when operating on a product comparison list. To do so, set the ProductListHandler.repositoryKey property to the key to pass to CatalogTools. CatalogTools uses the given key and its key-to-catalog mapping to select a product catalog repository. Typically, you would set the ProductListHandler.repositoryKey property via a hidden input field in a form. If the repositoryKey property is unset, then the default product catalog repository is used.

The following table describes ProductListHandler’s handle methods for managing a product comparison list:

Handle Method

Description

handleAddProduct

Adds the product specified by productID to the product comparison list, applying optional category and SKU information if supplied in categoryID and skuID.

handleAddProductAllSkus

Adds all of the SKUs for the product specified by productID to the product comparison list, applying optional category information if supplied in categoryID.

handleAddProductList

Adds all of the products specified by productIDList to the product comparison list, applying optional category information if supplied in categoryID and the default SKU for each product, if any.

handleAddProductListAllSkus

Adds all of the SKUs for all of the products specified by productIDList to the product comparison list, applying optional category information if supplied in categoryID.

handleCancel

Resets the form handler by setting productID, categoryID, and skuID to null.

handleClearList

Clears the product comparison list and redirects the user to the clearListSuccessURL on success.

handleRefreshInventoryData

Calls the ProductComparisonList.refreshInventoryData() method.

The handleRefreshInventoryData method also calls pre and post methods. If necessary, your subclasses can override these methods to provide additional application-specific processing. Also note that ProductListHandler has two optional properties, refreshInventoryDataSuccessURL and refreshInventoryDataErrorURL, which you can set to redirect the user when the handle method succeeds or fails, respectively.

handleRemoveCategory

Removes all entries for the category specified by categoryID from the product comparison list.

handleRemoveEntries

Removes the list entries whose ids are specified in entryIds from the product comparison list.

handleRemoveProduct

Removes the product specified by productID from the product comparison list, applying the optional category and SKU information if supplied in categoryID and skuID, respectively.

handleRemoveProductAllSkus

Removes all entries for the product specified by productID from the product comparison list.

handleSetProductList

Sets the product comparison list to the products specified by productIDList, applying optional category information if supplied in categoryID and the default SKU for each product, if any.

handleSetProductListAllSkus

Sets the product comparison list to contain all the SKUs for all the products specified by productIDList, applying optional category information if supplied in categoryID.

The behavior of ProductListHander’s handle methods parallels that of ProductComparisonList. Namely, optional category and SKU information is managed in the same way. If a product’s category information isn’t specified in categoryID, then the form handler looks for the default category of the product. If no default value exists, then the property is set to null. Similarly, if a product’s SKU information isn’t specified in skuID, then the form handler looks for the product’s first child SKU (that is, the default SKU). If no default value exists, then the property is set to null.

For additional information on ProductListHandler’s methods, refer to the ATG API Reference. For examples of how page developers can use ProductListHandler in JSPs to manage product comparison lists, refer to Implementing Product Comparison chapter of the ATG Commerce Guide to Setting Up a Store.

 
loading table of contents...