Adding shipping information to shopping carts involves the following subprocesses:

Note 1: Be aware that the ShippingGroupFormHandler form handler and AvailableShippingMethods servlet bean, which are described in the subsections below, do not reprice 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 ATG 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:

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 commerce 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 commerce 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 commerce 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 ATG 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:

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 ATG 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 ATG Commerce Programming Guide.

ShippingGroupDroplet takes the following input parameters:

ShippingGroupDroplet sets the following output parameters:

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 commerce 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):

As an example, consider the following code segment from complex_shipping.jsp in the commerce 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>&nbsp;</td>
                   <td>
                   <dsp:input
bean="ShippingGroupFormHandler.currentList[param:index].splitQuantity"
paramvalue="element.quantity" size="4" type="text"/></td>
                   <td>&nbsp;</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:

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 ATG 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 ATG 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 <ATG10dir>\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 ATG 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, see The Pricing Servlet Beans section of the Using and Extending Pricing Services chapter of the ATG Commerce Programming Guide.) 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 <ATG10dir>\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 ATG Business Commerce Reference Application Guide.