ATG Commerce Programming Guide

The CartModifierFormHandler is used to add items to and remove items from an Order, modify the quantity of items in the Order, and prepare the Order for the checkout process.

CartModifierFormHandler is an instance of class atg.commerce.order.purchase.CartModifierFormHandler; it is located in Nucleus at /atg/commerce/order/purchase/CartModifierFormHandler.

Many of the methods (described below) in CartModifierFormHandler call OrderManager.updateOrder() to save the Order in its present state to the Order Repository. For information on OrderManager.updateOrder() and the updateOrder pipeline that it executes, see the Updating an Order with the OrderManager subsection of Saving Orders in this chapter.

The following sections describes the important methods in CartModifierFormHandler. As can be seen from the method descriptions that follow, the handleAddXXX and handleRemoveXXX methods of CartModifierFormHandler automatically reprice the Order whenever the user makes changes to it.

However, you should note that users can also make changes to their orders through other purchase process form handlers that do not reprice orders, such as the form handlers that create and manage shipping groups. In these situations, where the user can change the current Order in ways that affect its price, and where the form handler used to process those changes does not reprice the Order, you should use the RepriceOrderDroplet servlet bean to reprice the Order before displaying its price to the user. For more information on RepriceOrderDroplet, see Repricing Orders section of the ATG Commerce Guide to Setting Up a Store.

getQuantity

Retrieves the quantity for the given item.

getCatalogKey

Retrieves a string that identifies the catalog to use when obtaining a catalogRef and productRef for the creation of a CommerceItem. The string is determined by the user’s locale, which is obtained from the Request object. Consequently, the key is the user’s locale and the value is the corresponding repository to use (for example, en_US=ProductCatalog, fr_FR=FrenchCatalog). /atg/commerce/catalog/CatalogTools maintains the key-to-catalog mapping.

getShippingGroupCommerceItemRelationships

Retrieves the list of ShippingGroupCommerceItemRelationships within the order.

handleAddItemToOrder

Adds items to an order by calling addItemToOrder(), which actually adds the items to the Order. It then calls OrderManager.updateOrder().

See the addItemToOrder() method for more information.

handleSetOrder

Performs the actual work necessary to save an Order. It calls modifyOrder() to validate the user’s changes and modify the Order. It then calls runProcessSetOrder(), which executes the pipeline set in CartModifierFormHandler.setOrderChainId. Finally, it calls OrderManager.updateOrder().

See the modifyOrder() and runProcessSetOrder() methods for more information.

handleSetOrderByRelationshipId

Performs the actual work necessary to save an Order. It calls modifyOrderByRelationshipId() to validate the user’s changes and modify the Order. It then calls runProcessSetOrder(), which executes the pipeline set in CartModifierFormHandler.setOrderChainId. Finally, it calls OrderManager.updateOrder().

See the modifyOrderByRelationshipId() and runProcessSetOrder() methods for more information.

handleMoveToPurchaseInfo

Performs the actual work necessary to save an Order. Unlike handleSetOrder() and handleSetOrderByRelationshipId(), it also verifies that the Order is ready for checkout.

The handle method calls modifyOrder() to validate the user’s changes and modify the Order. It then calls runProcessMoveToPurchaseInfo(), which executes the pipeline set in CartModifierFormHandler.moveToPurchaseInfoChainId. Finally, it calls OrderManager.updateOrder().

See the modifyOrder() and runProcessMoveToPurchaseInfo() methods for more information.

handleMoveToPurchaseInfoByRelId

Performs the actual work necessary to save an Order. Unlike handleSetOrder() and handleSetOrderByRelationshipId(), it also verifies that the Order is ready for checkout.

The handle method calls modifyOrderByRelationshipId() to validate the user’s changes and modify the Order. It then calls runProcessMoveToPurchaseInfo(), which executes the pipeline set in CartModifierFormHandler.moveToPurchaseInfoChainId. Finally, it calls OrderManager.updateOrder().

See the modifyOrderByRelationshipId() and runProcessMoveToPurchaseInfo() methods for more information.

addItemToOrder

Invoked by handleAddItemToOrder(). The method calls mergeItemInputForAdd(). If all input values are valid, the method then calls doAddItemToOrder().

See the mergeItemInputForAdd() and doAddItemToOrder() methods for more information.

mergeItemInputForAdd

Invoked by addItemToOrder() to unify the way input values are made available to doAddItemToOrder() and to validate input values.

The method first calls CartModifierFormHandler.getItems(). If the returned value is null, the method constructs an items array whose size matches the size of the return value from CartModifierFormHandler.getCatalogRefIds(). The method copies the values from getCatalogRefIds() into the items array elements. Then the method copies the values returned by the following CartModifierFormHandler.getXXX methods into the items array elements: quantity, productId or productIds, value, commerceItemType, giftlistId, and giftlistItemId.

If the initial CartModifierFormHandler.getItems() call retrieves a non-null value, the method copies the value returned by CartModifierFormHandler.getCommerceItemType() to every items array element whose commerceItemType subproperty was null. The method also calls CartModifierFormHandler.mergeValueDictionaries() to combine the Dictionary returned by CartModifierFormHandler.getValueDictionary() with each items array element’s value Dictionary.

doAddItemToOrder

Invoked by addItemToOrder(). The method retrieves the list of items to add by calling CartModifierFormHandler.getItems(), and calls CartModifierFormHandler.getCatalogKey() to determine which catalog to use. Then, for each item to add to the Order, the method uses the PurchaseProcessHelper class to do the following:

After the above steps have been taken for all the new items, addItemToOrder() calls runProcessRepriceOrder(), which reprices the Order by executing the pipeline set in CartModifierFormHandler.repriceOrderChainId. Then, for each new item addItemToOrder() calls runProcessAddItemToOrder(), which executes the pipeline set in CartModifierFormHandler.addItemToOrderChainId. Finally, the method fires a scenario event of type ItemAddedToOrder for each new item.

See the runProcessRepriceOrder() and runProcessAddItemToOrder() methods for more information.

modifyOrder

Invoked by handleSetOrder() and handleMoveToPurchaseInfo().

The modifyOrder() method modifies the Order based on the changes made in the request. It iterates over each CommerceItem in the Order. For each CommerceItem, it retrieves the current quantity by calling getQuantity() and passing in the catalogRefId (SKU ID) of the item.

Next, the method checks if the catalogRefId of the current item is in the removalCatalogRefIds list. If it is, then the quantity of the current item is set to zero.

Then, the quantity of the current item is assessed and one of two actions occurs:

modifyOrderByRelationshipId

Invoked by handleSetOrderByRelationshipId() and handleMoveToPurchaseInfoByRelId().

The modifyOrderByRelationshipId() method updates the Order based on the changes made in the request and the existing ShippingGroupCommerceItemRelationships in the Order. It iterates over each ShippingGroupCommerceItemRelationship in the Order. For each ShippingCommerceItemRelationship, it first checks to make sure the Relationship is of type SHIPPINGQUANTITY. If it is not, then an exception is thrown. Then, the method retrieves the current quantity of the ShippingGroupCommerceItemRelationship by calling getQuantity() and passing in the ShippingGroupCommerceItemRelationship ID.

Next, the method checks if the ID of the ShippingGroupCommerceItemRelationship is in the removalRelationshipIds list. If it is, then the quantity of the current ShippingGroupCommerceItemRelationship is set to zero.

Then, the quantity of the current ShippingGroupCommerceItemRelationship is assessed and one of two actions occurs:

For more information on the SHIPPINGQUANTITY type of ShippingGroupCommerceItemRelationship, see Relationship Types in the Using Relationship Objects section of the Working With Purchase Process Objects chapter.

handleRemoveItemFromOrder

Removes items from the Order by CommerceItem ID. This handle method calls deleteItems() to delete the items from the Order and then calls OrderManager.updateOrder().

See the deleteItems() method for more information.

handleRemoveItemFromOrderByRelationshipId

Removes items from the Order by ShippingGroupCommerceItemRelationship ID. This handle method calls deleteItemsByRelationshipId() to delete the items from the Order and then calls OrderManager.updateOrder().

See the deleteItemsByRelationshipId() method for more information.

deleteItems

Deletes from the Order all CommerceItems whose IDs are in the removalCommerceIds property. The method also removes all associated ShippingGroupCommerceItemRelationships and calls runProcessRepriceOrder(), which reprices the Order by executing the pipeline set in CartModifierFormHandler.repriceOrderChainId. Finally, the method fires a scenario event of type ItemRemovedFromOrder.

See the runProcessRepriceOrder() method for more information.

deleteItemsByRelationshipId

This method deletes CommerceItems from the Order by ShippingGroupCommerceItemRelationship ID. It iterates through the IDs in the removalShippingGroupCommerceItemRelIds property. For each ID, it first ensures that the Relationship type is of type SHIPPINGQUANTITY (logging an error if it is not), and then it removes the HandlingInstructions associated with the ShippingGroup. Next, one of two conditions can exist:

runProcessAddItemToOrder

Invoked by the handleAddItemToOrder() method. This method runs the pipeline set in CartModifierFormHandler.addItemToOrderChainId. By default, this property is set to addItemToOrder.

Note: By default, the addItemToOrder pipeline is commented out of commercepipeline.xml, the commerce pipeline configuration file. It is provided for extension purposes, should you need to include additional functionality, such as scenario events.

runProcessSetOrder

Invoked by handleSetOrder() and handleSetOrderByRelationshipId(). This method runs the pipeline set in CartModifierFormHandler.setOrderChainId. By default, this property is set to setOrder.

Note: By default, the setOrder pipeline is commented out of commercepipeline.xml, the commerce pipeline configuration file. It is provided for extension purposes, should you need to include additional functionality, such as scenario events.

runProcessRepriceOrder

Runs the pipeline to execute whenever the order needs to be repriced. The pipeline to run is set in CartModifierFormHandler.repriceOrderChainId. By default, this property is set to repriceOrder. By default, this method executes an ORDER_TOTAL pricing operation. (For more information about pricing operations, see the Repricing Shopping Carts section of the ATG Commerce Guide to Setting Up a Store.)

runProcessMoveToPurchaseInfo

Invoked by handleMoveToPurchaseInfo() and handleMoveToPurchaseInfoByRelId(). This method runs the pipeline set in CartModifierFormHandler.moveToPurchaseInfoChainId. By default, this property is set to moveToPurchaseInfo.

The moveToPurchaseInfo pipeline, in turn, executes the validateForCheckout pipeline, which verifies that the Order is ready for checkout. For more information on both pipelines, see the Commerce Processor Chains section.