When removing gifts from the shopping cart, Commerce Reference Store has to take into account several cases:
Removing gifts that are only a portion of a
CommerceItem
’s total quantity (in other words, theCommerceItem
includes both a gift quantity and a non-gift quantity of the given item)Removing gift placeholders from the shopping cart page
Removing all unselected gifts from the shopping cart so that the customer can proceed to checkout
Removing Gifts that are Only a Portion of a Commerce Item’s Total Quantity
When a CommerceItem
is split across multiple lines in the shopping cart, some of which represent gifts and some of which represent regularly priced items, care must be taken to modify the appropriate quantity in the CommerceItem
and not remove the entire CommerceItem
from the cart when a Remove link is clicked. The logic for handling this situation is contained in the store.war/cart/gadgets/itemListingButtons.jsp
page. This page tests each line item in the cart to determine if the item is a gift item or a regularly priced item that is part of a CommerceItem
that also contains gifts.
For a gift item, the itemListingButtons.jsp
page includes the following code to render the Remove link:
<dsp:input iclass="atg_store_textButton atg_store_actionDelete" type="submit" name="remove_gwp_${nameSuffix}" bean="CartFormHandler.removeItemGwp" value="${deleteButtonTitle}" submitvalue="${currentItemId}"/>
When a customer clicks the Remove link associated with this code, the following happens:
The gift ID that is specified in the
submitvalue
attribute is stored in the/atg/store/order/purchase/CartFormHandler.removeItemGwp
property.The
atg.projects.store.order.purchase.StoreCartFormHandler.handleRemoveItemGwp()
method is called. This method is Commerce Reference Store-specific and it calls theStoreCartFormHandler.handleUpdate()
method to update each line item in the cart.During the process of updating the cart, the
StoreCartFormHandler.getQuantity()
method gets called. This method is a Commerce Reference Store extension that checks for the presence of theremoveItemGwp
property when calculating the item’s quantity. IfremoveItemGwp
is set,getQuantity()
decreases the overall quantity of theCommerceItem
by one. The overall quantity is reduced by one because this is a gift item and gifts are separated out in the shopping cart so that there is one gift per line item; therefore, removing a gift line item constitutes a reduction in quantity of one.Note that Commerce Reference Store’s implementation of the
getQuantity()
method decreases the total quantity of theCommerceItem
but it does not change the item’s gift with purchase markers. The effect of this change is to decrease the total quantity while leaving the gift quantity constant. For example, if the initial total quantity is three and the gift quantity is one, theCommerceItem
contains two regularly priced items and one free item. After thegetQuantity()
decrease, the total quantity is two, the gift quantity is still one, and the regularly priced quantity is also one. So, effectively, the regularly priced quantity of theCommerceItem
is reduced first, before the free quantity is reduced.Note: See the ATG Commerce Programming Guide for more information on gift with purchase markers.
For a regularly priced item that is part of a CommerceItem
that also contains gifts, the itemListingButtons.jsp
page includes the following code:
<dsp:input type="hidden" converter="map" bean="CartFormHandler.itemNonGwpQuantities" value="${currentItemId}=${missedQty}"/> <dsp:input iclass="atg_store_textButton atg_store_actionDelete" type="submit" name="remove_non_gwp_${nameSuffix}" bean="CartFormHandler.removeItemNonGwp" value="${deleteButtonTitle}" submitvalue="${currentItemId}"/>
The first input
statement stores a map with the current item’s ID and the quantity of that item that is regularly priced in the CartFormHandler.itemNonGwpQuantities
property. As each item in the cart is iterated over, this map grows to hold the regularly priced quantities for all items in the cart that have a combination of free and regularly priced quantities.
Note: The cart item iteration code is contained in store.war/cart/gadgets/cartItems.jsp
, which is the page that calls itemListingButtons.jsp
.
The second statement renders the Remove link. When a customer clicks the Remove link, the following happens:
The item ID that is specified in the
submitvalue
attribute is stored in the/atg/store/order/purchase/CartFormHandler.removeItemNonGwp
property.The
atg.projects.store.order.purchase.StoreCartFormHandler.handleRemoveItemNonGwp()
method is called. This method is Commerce Reference Store-specific and it calls theStoreCartFormHandler.handleUpdate()
method to update each line item in the cart.During the process of updating the cart, the
StoreCartFormHandler.getQuantity()
method gets called. This method is a Commerce Reference Store extension that checks for the presence of theremoveItemNonGwp
property when calculating the item’s quantity. IfremoveItemNonGwp
is set,getQuantity()
decreases the overall quantity of theCommerceItem
by the amount specified for that item in theitemNonGwpQuantities
map.
Removing Gift Placeholders
The Remove link for gift placeholders is rendered by the store.war/cart/gadgets/giftPlaceholders.jsp
page. This page includes the following code:
<dsp:input type="hidden" bean="CartFormHandler.gwpPlaceholderPromotionIds" paramvalue="selection.promotionId"/> <dsp:input type="hidden" bean="CartFormHandler.gwpPlaceholderHashCodes" paramvalue="selection.giftHashCode"/> <dsp:input iclass="atg_store_textButton atg_store_actionDelete" type="submit" submitvalue="${gwpRowCount}" bean="CartFormHandler.removeGwpPlaceholderFromOrder" value="${removeText}"/>
The first input
statement stores a list of the promotion IDs associated with all the gift placeholders, in the order they appear in the cart, in the /atg/store/order/purchase/CartFormHandler.gwpPlaceholderPromotionIds
property. The second input
statement stores a list of all the gift placeholder hash codes, in the order they appear in the cart, in the /atg/store/order/purchase/CartFormHandler.gwpPlaceholderHashCodes
property.
The third input
statement renders the Remove link. When a customer clicks the Remove link, the following happens:
The row number of the gift placeholder, which is specified in the
submitvalue
attribute, gets stored in the/atg/store/order/purchase/CartFormHandler.removeGwpPlaceholderFromOrder
property.The
atg.projects.store.order.purchase.StoreCartFormHandler.handleRemoveGwpPlaceholderFromOrder()
method is called. This handler method is Commerce Reference Store-specific. It gets the row number of the submitted placeholder and uses that information to retrieve the corresponding promotion ID and hash code from thegwpPlaceholderPromotionIds
andgwpPlaceholderHashCodes
lists. These two values identify the promotion in this particular order whose selectable gift quantity should be reduced. Next, theatg.commerce.promotion.GWPManager.updateSelectableQuantity()
method is called and the gift quantity available for selection for this promotion is reduced by one.
Removing All Unselected Gifts
When customers attempt to checkout with unselected free gifts still in the shopping cart, they are notified and asked whether they want to return to the shopping cart page to choose their free gifts or continue with checkout. If the shopper chooses to continue with checkout, all unselected free gifts must be removed from the shopping cart. The code that manages this task resides in the store.war/cart/giftNotSelected.jsp
page.
If the customer chooses to proceed with checkout, the giftNotSelected.jsp
page sets the /atg/commerce/promotion/GiftWithPurchaseFormHandler.removeAllSelectableQuantitySuccessURL
property with an appropriate URL. The URL that gets sets depends on whether login is required for checkout or the customer is using express checkout. Next, the atg.commerce.promotion.GiftWithPurchaseFormHandler.handleRemoveAllSelectableQuantity
method is called to remove all unselected free gifts from the order and redirect the customer to the URL stored in removeAllSelectableQuantitySuccessURL
.