Understanding the CartModifierFormHandler

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.

If you’d prefer for items to be priced according to a pricelist rather than the default behavior provided by the pricing engine, set the priceListId property to the appropriate pricelist.

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 table describes the important methods in CartModifierFormHandler.

Method	Description
`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.
`getShippingGroupCommerceItem Relationships`	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 in this table 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 in this table 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 in this table 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 in this table 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 in this table 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 in this table 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()`. Then, for each item to add to the `Order`, the method does the following: First, the method calls `CartModifierFormHandler.createCommerceItem()`, which calls `CommerceItemManager.createCommerceItem()` to create a `CommerceItem` using the `commerceItemType`, `catalogRefId`, `productId` and `quantity` found in the current array element from `getItems()`. Additionally, the catalog to use is determined by calling `CartModifierFormHandler.getCatalogKey()`. `CartModifierFormHandler.createCommerceItem()` also calls `CommerceItemManager.addItemToOrder()` to add the created `CommerceItem` to the order. Second, the method calls `CartModifierFormHandler.setCommerceItemProperties()` to copy custom values from the current item’s `value` Dictionary to the new `CommerceItem`. Third, the method calls `CartModifierFormHandler.addItemToShippingGroup()`, which calls `CommerceItemManager.addItemQuantityToShippingGroup()` which in turn takes the given quantity of the `CommerceItem` and the given `ShippingGroup` and creates a `ShippingGroupCommerceItemRelationship` of type SHIPPINGQUANTITY. Note that if the `ShippingGroup` is not set in the form, then by default it will be set to the first `ShippingGroup` found in the `Order`. Fourth, the method calls `CartModifierFormHandler.createConfigurableSubitems()`, which is an empty method that can be overridden as needed by sites that use configurable commerce items. Fifth, the method calls `CartModifierFormHandler.processGiftAddition()`, which checks if the item that was added to the order is a gift (that is, the item’s input `giftlistId or giftlistItemId` property is non-`null`). If the item is a gift, `processGiftAddition()` calls `GiftListManager.addGiftToOrder()` to perform additional gift list processing. 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 in this table 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: -- If the quantity is greater than zero, the method sets the quantity in the `CommerceItem` and the corresponding `ShippingGroupCommerceItemRelationship`. -- If the quantity is less than or equal to zero, then it removes the `CommerceItem` and any associated `Relationship` objects from the `Order`.
`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: -- If the quantity is greater than zero, then the quantity of the `ShippingGroupCommerceItemRelationship` and the quantity of the associated `CommerceItem` are adjusted appropriately. -- If the quantity is less than or equal to zero, then the `ShippingGroupCommerceItemRelationship` is removed from the `Order` and the quantity of the associated `CommerceItem` is adjusted appropriately. 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 in this table 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 in this table 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 in this table 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: -- If the quantity in the `ShippingGroupCommerceItemRelationship` is greater than or equal to the quantity in the `CommerceItem`, then the `CommerceItem` and all associated `Relationships` are removed from the `Order`. The method then 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 in this table for more information.) -- If the quantity in the `ShippingGroupCommerceItemRelationship` is less than the quantity in the `CommerceItem`, but the `CommerceItem` has `Relationships` to other `ShippingGroups`, then the quantity in the `CommerceItem` is reduced and the given `ShippingGroupCommerceItemRelationship` removed.
`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.

As can be seen from the method descriptions above, 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.

ATG Commerce Programming Guide

Understanding the CartModifierFormHandler