The product comparison system consists of the following four classes in the atg.commerce.catalog.comparison
package:
A class that provides a generic data structure to maintain an ordered list of objects and an associated set of sort directives to apply when displaying the items.
A subclass of
ComparisonList
that provides an extended API for comparing product information. Oracle ATG Web Commerce includes a session-scoped instance ofProductComparisonList
, located in Nucleus at/atg/commerce/catalog/comparison/ProductList
.A droplet that queries whether a product comparison list contains an entry for a specific product. Oracle ATG Web Commerce includes a globally-scoped instance of
ProductListContains
, located in Nucleus at/atg/commerce/catalog/comparison/ProductListContains
.A form handler that manages product comparison lists. Commerce includes a session-scoped instance of
ProductListHandler
, located in Nucleus at/atg/commerce/catalog/comparison/ProductListHandler
.
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 Platform API Reference.
Method | Description |
---|---|
| Adds an item to the end of the comparison list if the item isn’t already present in the list. |
| Removes all items from the comparison list. |
| Returns true if the comparison list contains the specified item. |
| Returns the item at the specified index in the comparison list. |
| Returns the list of items being compared. |
| Returns the index of the specified item in the comparison list; returns -1 if the item does not appear in the list. |
| Removes an item from the comparison list if it was present in the list. |
| 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. Oracle ATG Web 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.
The API for ProductComparisonList
The public API for ProductComparisonList
can be divided broadly into the following four categories:
add methods, which add entries to the list.
When you call
ProductComparisonList
’sadd
method, a newEntry
object is automatically constructed and added to the item list if it is not already present. When you callProductComparisonList
’saddAllSkus
method, a newEntry
object for each SKU associated with the given product is automatically constructed and added to the item list.When the
add
method oraddAllSkus
method is called, if no category ID for the given product is specified, then the product’s default parent category is used. If no default parent category for the given product is set, then thecategory
property of the newEntry
object is null. Similarly, if no SKU is specified in the method call, then the given product’s first child SKU is used. If the product has no child SKUs, then thesku
property of the newEntry
object is null.remove methods, which remove entries from the list.
contains methods, which query whether the list contains an entry matching specified product, category, SKU, or site information.
set and get methods, which set and get various properties of the
ProductComparisonList
itself.When you call
getItems
on aProductComparisonList
, you get back a List ofEntry
objects. When working with these objects in Java, you can either cast the objects toProductComparisonList.Entry
or use theDynamicBeans
system to retrieve the product, category, SKU, site, and inventory information from theEntry
. When working with these objects in JSPs, you can refer to their properties in the same way you refer to the properties of any other Java bean.refresh methods, which refresh the inventory information for the items in the
ProductComparisonList
.The
refreshInventoryData()
method iterates over the items in theProductComparisonList
and loads updated inventory information into them.The
setRefreshInventoryData(String unused)
method calls therefreshInventoryData()
method. This method enables you to update the inventory information for the items when you render the page that displays theProductComparisonList
. To do so, you could use the followingsetvalue
tag at the top of the page:<setvalue bean="ProductList.refreshInventoryData">
For related form handler methods, see ProductListHandler.
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 Platform 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 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 |
---|---|---|
|
| The product being compared. |
|
| 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 |
|
| 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 |
|
| The |
|
| 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 If you are using Oracle ATG Web Commerce’s multisite feature, the You can change the link format by setting the Note: If you display the product comparison information in a table, you can use the
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:
For more information on the |
|
| 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 Note: Like the Also like |
|
| A unique ID that names the list entry. You can use this property to retrieve individual entries by calling 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. |
|
| If you are using Oracle ATG Web Commerce’s multisite feature, this property holds the ID of the site with which the item is associated. |
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 Platform API Reference.
ProductListContains
When given a category, product, and SKU, the ProductListContains
droplet queries whether a product comparison list includes the given item.
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:
If you don’t specify a category ID for the given product, then
ProductListContains
looks for a list entry whosecategory
property matches either the given product’s default category or null if there is no default category for the given product.If you don’t specify a SKU for the given product, then
ProductListContains
looks for a list entry whosesku
property matches either the given product’s first child SKU or null if there are no SKUs for the given product.
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, Oracle ATG Web 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, 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 |
---|---|
| Adds the product specified by |
| Adds all of the SKUs for the product specified by |
| Adds all of the products specified by |
| Adds all of the SKUs for all of the products specified by |
| Resets the form handler by setting |
| Clears the product comparison list. |
| Calls the The |
| Removes all entries for the category specified by |
| Removes the list entries whose ids are specified in |
| Removes the product specified by |
| Removes all entries for the product specified by |
| Sets the product comparison list to the products specified by |
| Sets the product comparison list to contain all the SKUs for all the products specified by |
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 Platform API Reference. For examples of how page developers can use ProductListHandler
in JSPs to manage product comparison lists, refer to the Implementing Product Comparison chapter of the ATG Commerce Guide to Setting Up a Store.