Adding shipping information to shopping carts involves the following sub-processes:
Creating a list of shipping groups for potential use in the current order. The user can select from among these shipping groups when checking out the order. See Creating Potential Shipping Groups.
Specifying the shipping groups to use with the current order. See Adding Shipping Groups to an Order.
Selecting the shipping methods, such as Ground or Next Day, for the order’s shipping groups. See Selecting Shipping Methods.
Note 1: Be aware that the ShippingGroupFormHandler
form handler and AvailableShippingMethods
servlet bean, which are described in the subsections below, do not re-price a given Order
. Consequently, if you enable customers to make order changes that affect order price through either mechanism, you should reprice the given Order
using the RepriceOrderDroplet
servlet bean before displaying its price to the customer. For more information on RepriceOrderDroplet
, see Repricing Shopping Carts in this chapter.
Note 2: If an order contains any gift items, ShippingGroupDroplet
and ShippingGroupFormHandler
treat those items and their shipping information differently from other items. See the Core Commerce Programming Guide for details.
Creating Potential Shipping Groups
You can create a list of shipping groups for potential use in an Order
in one of two ways:
from information gathered from the user via forms
from information stored in the user’s profile
To create shipping groups from information obtained from the user via forms, use CreateHardgoodShippingGroupFormHandler
and CreateElectronicShippingGroupFormHandler
. These form handlers create, respectively, hard good and electronic shipping groups. Additionally, if the addToContainer
property of the form handlers is set to true (which it is by default), they add the new shipping group to the ShippingGroupMapContainer
and make it the default shipping group in the container. The ShippingGroupMapContainer
stores the shipping groups available for use in the current order. Once the shipping group is added to the ShippingGroupMapContainer
, the user can use it when checking out the current order. See Adding Shipping Groups to an Order.
The following JSP code example from hardgood_sg.jsp
in the sample catalog illustrates the use of CreateHardgoodShippingGroupFormHandler
.
<dsp:importbean bean="/atg/commerce/order/purchase/CreateHardgoodShippingGroupFormHandler" /> <dsp:importbean bean="/atg/userprofiling/Profile"/> <hr>Enter new shipping address for HardgoodShippingGroup <dsp:form action="hardgood_sg.jsp" method="post"> ShippingGroup NickName:<dsp:input bean="CreateHardgoodShippingGroupFormHandler.hardgoodShippingGroupName" size="30" type="text" value=""/> <br>First:<dsp:input bean="CreateHardgoodShippingGroupFormHandler.HardgoodShippingGroup.Shippin gAddress.firstName" beanvalue="Profile.firstName" size="30" type="text"/> Middle:<dsp:input bean="CreateHardgoodShippingGroupFormHandler.HardgoodShippingGroup.Shippin gAddress.middleName" beanvalue="Profile.middleName" size="30" type="text"/> Last:<dsp:input bean="CreateHardgoodShippingGroupFormHandler.HardgoodShippingGroup.Shippin gAddress.lastName" beanvalue="Profile.lastName" size="30" type="text"/> <br>Address:<dsp:input bean="CreateHardgoodShippingGroupFormHandler.HardgoodShippingGroup.Shippin gAddress.address1" beanvalue="Profile.defaultShippingAddress.address1" size="30" type="text"/> Address (line 2):<dsp:input bean="CreateHardgoodShippingGroupFormHandler.HardgoodShippingGroup.Shippin gAddress.address2" beanvalue="Profile.defaultShippingAddress.address2" size="30" type="text"/> <br>City:<dsp:input bean="CreateHardgoodShippingGroupFormHandler.HardgoodShippingGroup.Shippin gAddress.city" beanvalue="Profile.defaultShippingAddress.city" size="30" type="text" required="<%=true%>"/> State:<dsp:input bean="CreateHardgoodShippingGroupFormHandler.HardgoodShippingGroup.Shippin gAddress.state" maxsize="2" beanvalue="Profile.defaultShippingAddress.state" size="2" type="text" required="<%=true%>"/> Postal Code:<dsp:input bean="CreateHardgoodShippingGroupFormHandler.HardgoodShippingGroup.Shippin gAddress.postalCode" beanvalue="Profile.defaultShippingAddress.postalCode" size="10" type="text" required="<%=true%>"/> Country:<dsp:input bean="CreateHardgoodShippingGroupFormHandler.HardgoodShippingGroup.Shippin gAddress.country" beanvalue="Profile.defaultShippingAddress.country" size="10" type="text"/> <br> <dsp:input bean="CreateHardgoodShippingGroupFormHandler.newHardgoodShippingGroupSucce ssURL" type="hidden" value="shipping.jsp?init=false"/> <dsp:input bean="CreateHardgoodShippingGroupFormHandler.newHardgoodShippingGroupError URL" type="hidden" value="shipping.jsp?init=false"/> <dsp:input bean="CreateHardgoodShippingGroupFormHandler.newHardgoodShippingGroup" priority="<%=(int)-10%>" type="submit" value="Create HardgoodShippingGroup"/> </dsp:form>
The following JSP code example from electronic_sg.jsp
in the sample catalog illustrates the use of CreateElectronicShippingGroupFormHandler
.
<dsp:importbean bean="/atg/commerce/order/purchase/CreateElectronicShippingGroupFormHandle r"/> <dsp:importbean bean="/atg/userprofiling/Profile"/> <hr>Enter new e-mail address for ElectronicShippingGroup <dsp:form action="electronic_sg.jsp" method="post"> ShippingGroup NickName:<dsp:input bean="CreateElectronicShippingGroupFormHandler.electronicShippingGroupNam e" size="30" type="text"/> <br>E-mail Address:<dsp:input bean="CreateElectronicShippingGroupFormHandler.emailAddress" beanvalue="Profile.email" size="30" type="text"/> <br> <dsp:input bean="CreateElectronicShippingGroupFormHandler.newElectronicShippingGroupS uccessURL" type="hidden" value="shipping.jsp?init=false"/> <dsp:input bean="CreateElectronicShippingGroupFormHandler.newElectronicShippingGroupE rrorURL" type="hidden" value="shipping.jsp?init=false"/> <dsp:input bean="CreateElectronicShippingGroupFormHandler.newElectronicShippingGroup" priority="<%=(int)-10%>" type="submit" value="Create ElectronicShippingGroup"/> </dsp:form>
In the sample catalog, both hardgood_sg.jsp
and electronic_sg.jsp
are embedded into shipping.jsp
, which itself manages the shipping information for the user’s current order. (Note that electronic_sg.jsp
is commented out.)
For more information on both CreateHardgoodShippingGroupFormHandler
and CreateElectronicShippingGroupFormHandler
, see the Checking Out Orders section of the Configuring Purchase Process Services chapter in the Core Commerce Programming Guide.
In contrast to creating shipping groups from information gathered from the user via forms, you can also create shipping groups from information that is stored in the user’s profile using the ShippingGroupDroplet
servlet bean. ShippingGroupDroplet
uses the information obtained from the current user’s profile to initialize ShippingGroups
and add them to the ShippingGroupMapContainer
. The input parameters passed into ShippingGroupDroplet
determine what types of ShippingGroups
are created (hard good, electronic, or both), and whether the ShippingGroupMapContainer
is cleared before they are created. If HardgoodShippingGroups
are created, ShippingGroupDroplet
also creates a default HardgoodShippingGroup
for the container using the default shipping address in the user’s profile. Once the shipping groups are added to the ShippingGroupMapContainer
, the user can select from among them when checking out the current Order
. See Adding Shipping Groups to an Order.
Additionally, ShippingGroupDroplet
uses the information in the user’s current Order
to initialize CommerceItemShippingInfo
objects for the CommerceItem
objects in the Order
. A CommerceItemShippingInfo
object is a helper object that represents the relationship between a CommerceItem
and a ShippingGroup
; it contains properties that allow the total quantity in the CommerceItem
to be spread across multiple shipping groups. The CommerceItemShippingInfoContainer
stores the CommerceItemShippingInfo
objects created for the current Order
.
Once a set of CommerceItemShippingInfo
objects is initialized for an order, you can present your customer with a form that allows the customer to:
Specify a different
ShippingGroup
for eachCommerceItemShippingInfo
object.Update the
SplitQuantity
andSplitShippingGroupName
property values of theCommerceItemShippingInfo
objects and submit the changes by calling theShippingGroupFormHandler.splitShippingInfos
method. In this way,CommerceItem
objects can be associated with additionalShippingGroups
than those provided by theShippingGroupDroplet
initialization. The changes are stored in additionalCommerceItemShippingInfo
objects.
When the customer is satisfied with the ShippingGroup
to CommerceItem
associations, he or she clicks a button to proceed with the purchase process. Behind the scenes, this button invokes the ShippingGroupFormHandler.applyShippingGroups
handler. The handler collects the information in the CommerceItemShippingInfo
helper objects and adds corresponding ShippingGroupCommerceItemRelationship
objects to the order. A ShippingGroupCommerceItemRelationship
creates an association between a CommerceItem
and a ShippingGroup
and represents the quantity of the item in the CommerceItem
that will be shipped using the information in the ShippingGroup
.
While they are closely related, CommerceItemShippingInfo
and ShippingGroupCommerceItemRelationship
objects serve slightly different purposes. A CommerceItemShippingInfo
object is external to the order and provides a means for defining commerce item-to-shipping group relationships. These changes do not affect the actual order until they are applied, allowing the order to remain in a stable state until the ShippingGroupFormHandler.applyShippingGroups
handler is invoked. Once the information in the CommerceItemShippingInfo
objects is applied to the order, the relationships are stored in the order as ShippingGroupCommerceItemRelationship
objects.
The input parameters passed into ShippingGroupDroplet
determine how the droplet creates and initializes CommerceItemShippingInfo
objects for each CommerceItem
and whether the CommerceItemShippingInfoContainer
is cleared before they are created. Three parameters control CommerceItemShippingInfo
object creation: initShippingInfos
, createOneInfoPerUnit
, and initBasedOnOrder
. These parameters, along with the other ShippingGroupDroplet
input parameters, are described in the table below.
Note: For more information on CommerceItemShippingInfo
objects, see Shipping to Multiple Addresses section in the Processing Orders chapter of the Business Commerce Reference Application Guide. For more information on ShippingGroupCommerceItemRelationship
objects, see the Using Relationship Objects section in the Working with Purchase Process Objects chapter of the Core Commerce Programming Guide.
ShippingGroupDroplet
takes the following input parameters:
Parameter | Description |
---|---|
| When set to |
| When set to |
| When set to This should be done at least once per |
| When set to |
| When set to |
| When set to |
| When set to |
| Used to override the component’s default setting for the user’s order. |
| A comma-separated list of |
ShippingGroupDroplet
sets the following output parameters:
Parameter | Description |
---|---|
| The |
| The |
ShippingGroupDroplet
renders one open parameter named output
.
The following code example illustrates the use of ShippingGroupDroplet
. The example creates HardgoodShippingGroup
objects for the current user based on the availability of shipping address information in the user’s profile. ShippingGroupDroplet
also creates CommerceItemShippingInfo
objects for the items in the user’s current order.
<dsp:droplet name="ShippingGroupDroplet"> <dsp:param value="true" name="clear"/> <dsp:param value="hardgoodShippingGroup" name="shippingGroupTypes"/> <dsp:param value="true" name="initShippingGroups"/> <dsp:param value="true" name="initShippingInfos"/> <dsp:oparam name="output"> Manipulation of objects here... </dsp:output> </dsp:droplet>
You can refer to shipping.jsp
in the sample catalog for another JSP code example that illustrates the use of ShippingGroupDroplet
.
Adding Shipping Groups to an Order
Use ShippingGroupFormHandler
to add shipping groups to an Order
once the shipping information for the Order
has been gathered from the following two processes (described in detail in the previous section):
The shipping groups for potential use in the
Order
have been created viaCreateHardgoodShippingGroupFormHandler
,CreateElectronicShippingGroupFormHandler
, and/orShippingGroupDroplet
. The shipping groups have been added to theShippingGroupMapContainer
.The
CommerceItemShippingInfo
objects for eachCommerceItem
in theOrder
have been created viaShippingGroupDroplet
. TheCommerceItemShippingInfo
objects have been added to theCommerceItemShippingInfoContainer
.
As an example, consider the following code segment from complex_shipping.jsp
in the sample catalog.
Note: In the code segment below, you can assume that each referenced component has been imported into the page via a dsp:importbean
tag. See the actual JSP for these import statements.
<dsp:droplet name="ShippingGroupDroplet"> <dsp:param name="clearShippingGroups" value="false"/> <dsp:param name="initShippingGroups" value="false"/> <dsp:param name="initShippingInfos" param="init"/> <dsp:oparam name="output"> <!-- begin output --> <table border=0 cellpadding=0 cellspacing=0 width=800> <tr> <td width=55></td> <td valign="top" width=745> <table border=0 cellpadding=4 width=80%> <tr><td></td></tr> <tr><td></td></tr> <tr valign=top> <td> <%-- table with multiple rows with eleven cells --%> <table border=0 cellpadding=4 cellspacing=1 width=100%> <tr> <td colspan=12><span class=help>To ship a line item to another address, select the address and click the "Save" button. To ship only some of the items to another address, change the quantity and select the address. You must save changes individually before continuing. </span></td> </tr> <tr bgcolor="#666666" valign=bottom> <td colspan=2><span class=smallbw>Part #</span></td> <td colspan=2><span class=smallbw>Name</span></td> <td colspan=2 align=middle><span class=smallbw>Qty</span></td> <td colspan=2 align=middle><span class=smallbw>Qty to move</span></td> <td colspan=2 align=middle><span class=smallbw>Shipping address</span></td> <td colspan=2><span class=smallbw>Save changes</span></td> </tr> <%-- get the real shopping cart items --%> <dsp:droplet name="ForEach"> <dsp:param name="array" param="order.commerceItems"/> <dsp:oparam name="output"> <dsp:setvalue paramvalue="element" param="commerceItem"/> <dsp:setvalue bean="ShippingGroupFormHandler.listId" paramvalue="commerceItem.id"/> <dsp:droplet name="ForEach"> <dsp:param bean="ShippingGroupFormHandler.currentList" name="array"/> <dsp:oparam name="output"> <!-- begin line item --> <dsp:setvalue paramvalue="element" param="cisiItem"/> <dsp:form action="complex_shipping.jsp" method="post"> <tr valign=top> <td><nobr><dsp:valueof param="commerceItem.auxiliaryData.catalogRef.manufacturer_part_number"/> </nobr></td> <td></td> <td><dsp:valueof param="commerceItem.auxiliaryData.catalogRef.displayName"/></td> <td></td> <td align=right> <dsp:valueof param="element.quantity"/></td> <td> </td> <td> <dsp:input bean="ShippingGroupFormHandler.currentList[param:index].splitQuantity" paramvalue="element.quantity" size="4" type="text"/></td> <td> </td> <td> <dsp:select bean="ShippingGroupFormHandler.currentList[param:index].splitShippingGroup Name"> <dsp:droplet name="ForEach"> <dsp:param name="array" param="shippingGroups"/> <dsp:oparam name="output"> <dsp:droplet name="Switch"> <dsp:param name="value" param="key"/> <dsp:getvalueof id="nameval4" param="cisiItem.shippingGroupName" idtype="java.lang.String"> <dsp:oparam name="<%=nameval4%>"> <dsp:getvalueof id="option305" param="key" idtype="java.lang.String"> <dsp:option selected="<%=true%>" value="<%=option305%>"/> </dsp:getvalueof><dsp:valueof param="key"/> </dsp:oparam> </dsp:getvalueof> <dsp:oparam name="default"> <dsp:getvalueof id="option313" param="key" idtype="java.lang.String"> <dsp:option selected="<%=false%>" value="<%=option313%>"/> </dsp:getvalueof><dsp:valueof param="key"/> </dsp:oparam> </dsp:droplet> </dsp:oparam> </dsp:droplet> </dsp:select> </td> <td></td> <td> <dsp:input bean="ShippingGroupFormHandler.splitShippingInfosSuccessURL" type="hidden" value="complex_shipping.jsp?init=false"/> <dsp:input bean="ShippingGroupFormHandler.ListId" paramvalue="commerceItem.id" priority="<%=(int)9%>" type="hidden"/> <dsp:input bean="ShippingGroupFormHandler.splitShippingInfos" type="submit" value=" Save "/> </td> </tr> </dsp:form> <!-- end line item --> </dsp:oparam> </dsp:droplet><!-- end inner ForEach --> </dsp:oparam> </dsp:droplet><!-- end outer ForEach --> <tr> <td colspan=12> <%-- table with one row with one cell --%> <table border=0 cellpadding=0 cellspacing=0 width=100%> <tr bgcolor="#666666"> <td></td> </tr> </table> </td> </tr> </table> </td> </tr> <tr> <td> <dsp:form action="complex_shipping.jsp" method="post"> <dsp:input bean="ShippingGroupFormHandler.applyShippingGroupsSuccessURL" type="hidden" value="billing.jsp?init=true"/> <dsp:input bean="ShippingGroupFormHandler.applyShippingGroups" type="submit" value="Continue"/> </dsp:form> </td> </tr> </table> </td> </tr> </table> <!-- end output --> </dsp:oparam> </dsp:droplet><!-- end ShippingGroupDroplet -->
Note the following sections of complex_shipping.jsp
:
When the page is rendered,
ShippingGroupDroplet
is used to initializeCommerceItemShippingInfo
objects for the items in the user’s current order and add them to theCommerceItemShippingInfoContainer
. Recall from the previous section that, by default,ShippingGroupDroplet
associates eachCommerceItemShippingInfo
object with the default shipping group in theShippingGroupMapContainer
.The remainder of the code renders an interface that enables the user to assign quantities of the items in the order to different shipping groups. This is achieved through the use of nested
ForEach
servlet beans:The outer
ForEach
servlet bean receives the array of items in theOrder
as an input parameter. It renders itsoutput
open parameter once for eachCommerceItem
in theOrder
. In theoparam
, theShippingGroupFormHandler.listId
property is set to the ID of the currentCommerceItem
. The current item’s ID is the key to itsList
ofCommerceItemShippingInfo
objects, which are now exposed via theShippingGroupFormHandler.currentList
property. (A hidden input tag farther down the page also sets this property on a subsequent request.)The inner
ForEach
servlet bean receives as an input parameter the array ofCommerceItemShippingInfo
objects for the currentCommerceItem
in the outerForEach
iteration. It renders itsoutput
oparam
once for eachCommerceItemShippingInfo
object in the array. Essentially, the output rendered is a form that displays the following: the part # and name of the associatedCommerceItem
, the quantity in the currentCommerceItemShippingInfo
object, a drop-down list with which to change the shipping group for a specified quantity in theCommerceItemShippingInfo
object, a textbox with which to specify the quantity in theCommerceItemShippingInfo
to assign to the selected shipping group, and a Save submit button with which to make these new associations.The shipping group drop-down list is populated with the shipping groups in the
ShippingGroupMapContainer
. These are exposed by theShippingGroupDroplet
through ashippingGroups
convenience parameter, and a third nestedForEach
servlet bean is used to iterate over the shipping groups and populate the drop-down list.Note that the shipping group drop-down list is associated with the
splitShippingGroupName
property of the currentCommerceItemShippingInfo
object. Similarly, the quantity textbox is associated with thesplitQuantity
property of the currentCommerceItemShippingInfo
object.Finally, note that the Save submit button invokes the
handleSplitShippingInfos
method ofShippingGroupFormHandler
. ThehandleSplitShippingInfos
method uses the values in thequantity
andsplitQuantity
properties of theCommerceItemShippingInfo
object to determine if the object should be split into two objects. If that is necessary, it then uses these properties and the shipping group specified in thesplitShippingGroupName
property to construct a secondCommerceItemShippingInfo
object. The method then sets the properties of both the old and new objects accordingly and adds the new object to theCommerceItemShippingInfoContainer
. Once the form is processed, the page is rendered again and reflects the changes the user has made.
The Continue submit button at the bottom of the page enables the user to apply the current shipping associations to the order and proceed to specifying billing information. The submit button invokes the
handleApplyShippingGroups
method ofShippingGroupFormHandler
, which adds the shipping groups that the user has selected to theOrder
. It does this by iterating over theCommerceItemShippingInfo
objects in theCommerceItemShippingInfoContainer
. For eachCommerceItemShippingInfo
object in the container, the associated shipping group is retrieved from theShippingGroupMapContainer
and added to theOrder
, and the appropriate quantity of the associatedCommerceItem
is added to thatShippingGroup
.
Note: For detailed information on all the handle methods of ShippingGroupFormHandler
, see the Preparing a Complex Order for Checkout section of the Configuring Purchase Process Services chapter in the Core Commerce Programming Guide. For more information on adding items to shipping groups, see the Assigning Items to Shipping Groups section of the Working With Purchase Process Objects chapter in the Core Commerce Programming Guide.
Refer to checkout/shipping.jsp
and checkout/ship_to_multiple.jsp
in the Motorprise reference application for JSP code examples that illustrate the use of ShippingGroupFormHandler
. You can access these pages at <ATG11dir>\MotorpriseJSP\j2ee-apps\motorprise\web-app\en\checkout\
. You can also open these pages in the ACC’s Document Editor via the Pages and Components>J2EE Pages task area. For more details, see the Shipping Information section of the Processing Orders chapter in the Business Commerce Reference Application Guide.
Selecting Shipping Methods
You can use the atg/commerce/pricing/AvailableShippingMethods
servlet bean to provide the user with a list of available shipping methods (such as Ground or Next Day) for a particular shipping group. Given a shipping group, AvailableShippingMethods
queries the ShippingPricingEngine
and returns a list of the shipping methods available for the type of the given shipping group.
AvailableShippingMethods
requires only one input parameter, named shippingGroup
, which is the specific shipping group to be shipped. (For a complete list of the input parameters of AvailableShippingMethods
, refer to the AvailableShippingMethodsDroplet section.) It sets one output parameter named availableShippingMethods
, which is a list of Strings representing the shipping methods that can be used to set a shippingMethod
value in a HardgoodShippingGroup
. Additionally, it renders one open parameter named output
.
The following JSP code segment from /checkout/shipping_method.jsp
in the Motorprise reference application illustrates the use of AvailableShippingMethods
. In the example, the AvailableShippingMethods
servlet bean is used to populate a select list from which to choose a shipping method for the current shipping group.
<tr valign=top> <td align=right width=25%><span class=smallb>Shipping method</span></td> <td align=left> <%-- The AvailableShippingMethods servlet bean permits the user to select a shipping method that is applied to the current ShippingGroup. --%> <dsp:droplet name="AvailableShippingMethods"> <dsp:param name="shippingGroup" param="sGroup"> <dsp:param bean="UserPricingModels.shippingPricingModels" name="pricingModels"> <dsp:param bean="Profile" name="profile"> <dsp:oparam name="output"> <dsp:select bean="ShoppingCart.current.ShippingGroups[param:index].shippingMethod"> <dsp:droplet name="ForEach"> <dsp:param name="array" param="availableShippingMethods"> <dsp:param name="elementName" value="method"> <dsp:oparam name="output"> <dsp:getvalueof id="methodname" idtype="String" param="method"> <dsp:option value="<%=methodname%>"><dsp:valueof param="method"></dsp:getvalueof> </dsp:oparam> </dsp:droplet> </dsp:select> </dsp:oparam> </dsp:droplet> </td> </tr>
See shipping_method.jsp
at <ATG11dir>\MotorpriseJSP\j2ee-apps\motorprise\web-app\en\checkout\
. You can also open the page in the ACC’s Document Editor via the Pages and Components>J2EE Pages task area. For more information on shipping_method.jsp
, see the Shipping Information section of the Processing Orders chapter in the Business Commerce Reference Application Guide.