Oracle ATG Web Commerce - Gift List Form Handlers

Gift List Form Handlers

Form handlers process forms and pages. They provide an interface between the customer and the business layer classes that have access to the Giftlists repository. Forms (or JSPs) use these handlers to take input from the user and call methods to perform actions on the Giftlists repository. For more information on form handlers, see the Working with Forms and Form Handlers chapter in the ATG Platform Programming Guide and the Using Repository Form Handlers chapter in the ATG Page Developer's Guide.

This section describes the following gift list form handlers:

GiftlistFormHandler

The /atg/commerce/gifts/GiftlistFormHandler accepts input from the customer to create, update and delete gift lists, as well as to add items to and remove items from gift lists. Properties in the handler are used to store user input for processing, as well as to store success and failure URLs for redirect after processing. Some handle methods have pre- and post- methods defined to make it easier to extend the methods.

Note: You can remove items from a gift list by using the GiftlistFormHandler to update the item’s quantity to 0. Alternatively, you can use the GiftitemDroplet to remove items. See GiftitemDroplet in Gift List Servlet Beans for more information .

The GiftlistFormHandler should be session-scoped because multiple pages usually gather the information needed for gift list management. The customer should be able to enter information on different pages to configure the same gift list.

GiftlistFormHandler Properties

The GiftlistFormHandler has the following properties that support the management of gift lists and items in the repository.

Property	Function
`giftlistManager`	The manager component that interfaces with the `Giftlists` repository.
`catalogTools`	The tools component that performs low-level operations on the catalog repository.
`CommerceProfileTools`	The tools component that performs low-level operations on the user profile repository.
Giftlist properties	Properties that store gift list attributes, as entered by the customer. For example, `eventName`, `eventDate`, `description`.
Success and failure URL properties	Properties that tell the Oracle ATG Web Commerce platform what pages to redirect the customer to after an action is performed. Both success and failure URL properties are provided for each handle method.
`siteId`	Used in multisite environments only. In multisite environments, if you don’t want to use the current site as the `siteId` when creating a gift list or adding a gift item, you can set the `GiftlistFormHandler`’s `siteId` property and use it instead. Typically, this property would be set by the JSP page. See the Gift and Wish Lists in a Multisite Environment for more information.

GiftlistFormHandler Handle Methods

The GiftlistFormHandler has a number of handle methods. Many of the handle methods have corresponding premethodName, postmethodName, and methodName methods. For example, the handleCreateGiftlist method has corresponding preCreateGiftlist, postCreateGiftlist and createGiftlist methods. A handle method calls its premethodName method before executing its methodName method. Likewise, it calls its postmethodName method after executing its methodName method. The pre and post methods, whose default implementations are empty, provide an easy way to extend the functionality of the handle methods. The exceptions to this rule are handleDeleteGiftlist, handleSaveGiftlist, and handleUpdateGiftlist. These three methods have pre and post methods but they must call the GiftlistManager class to accomplish their primary tasks of deleting, saving, and updating gift lists.

GiftlistformHandler also has a set of successURL and errorURL properties that map to its handle methods. For example, handleCreateGiftlist has corresponding createGiftlistSuccessURL and createGiftlistErrorURL properties. After a handle method executes, you can use these properties to redirect the customer to pages other than those specified by the form’s action attribute. The redirected page’s content depends on the type of operation and whether the operation succeeded or not. For example, if an attempt to create a gift list fails, you could redirect the customer to a page explaining what missing information caused the failure. If the value for a particular success or failure condition is not set, no redirection takes place and the form is left on the page defined as the action page.

The value of the redirect properties is a URL relative to the action page of the form. You can either specify the values of these URL properties in the properties of the form handler or you can set them in the JSP itself using a hidden tag attribute. For example, you can set the addItemToGiftlistSucessURL property with this tag:

<dsp:input bean="GiftlistFormHandler.addItemToGiftlistSucessURL"
 value="../user/lists.jsp " type="hidden"/>

The following table lists the GiftlistFormHandler handle methods, along with each method’s pre and post methods, and success/failure URLs.

Method	Function
`handleAddItemToGiftlist()`	Adds items to a gift list during the shopping process, using the following properties taken from the form: quantity, `catalogRefIds` (an array of SKU IDs), `giftlistId`, and `siteId` (multisite environments only). `handleAddItemToGiftlist()` calls `GiftlistFormHandler.addItemToGiftlist()`, whose primary responsibility is to call `GiftlistManager.addCatalogItemToGiftlist()`, where the actual work of adding an item to a gift list is done. `addCatalogItemToGiftlist()` performs several steps to create the item and then add it to the gift list. First, it determines whether an item already exists in the gift list with the same SKU ID, product ID, and, in multisite environments, site ID. If an item already exists, `addCatalogItemToGiftlist()` increments the quantity of the item. If a corresponding item doesn’t already exist, `addCatalogItemToGiftlist()` creates the gift item. Next, `addCatalogItemToGiftlist()` calls `GiftlistManager.addItemToGiftlist()` to add the newly created gift item to the specified gift list. In multisite environments, `addItemToGiftlist()` also determines whether the gift item and the gift list have compatible site IDs before adding the item to the list (see Gift and Wish Lists in a Multisite Environment for more details). Associated Methods: `addItemToGiftlist() preAddItemToGiftlist() postAddItemToGiftlist() GiftlistManager.addCatalogItemToGiftlist()` Success and Failure URL properties: `addItemToGiftlistSuccessURL addItemToGiftlistErrorURL`
`handleCreateGiftlist()`	Resets the properties in the `GiftlistFormHandler` in preparation for creating a new gift list. Associated Methods: `createGiftList() preCreateGiftList() postCreateGiftList()` Success and Failure URL properties: `createGiftlistSuccessURL createGiftlistErrorURL`
`handleDeleteGiftlist()`	Deletes a gift list from the user’s profile and from the repository. This method calls `GiftlistManager.removeGiftlist()` with the `profileId` and `giftlistId` to remove the gift list from the repository. Associated Methods: `preDeleteGiftlist() postDeleteGiftlist() GiftlistManager.removeGiftlist()` Success and Failure URL properties: `deleteGiftlistSuccessURL deleteGiftlistErrorURL`
`handleMoveItemsFromCart()`	Takes items out of the shopping cart and adds them to the gift list whose ID is passed into the form handler. `handleMoveItemsFromCart()` calls `GiftlistFormHandler.moveItemsFromCart()`. This method performs several steps to create the gift item and then add it to the gift list. First, it determines whether an item already exists in the gift list with the same SKU ID, product ID, and, in multisite environments, site ID. If an item already exists, `moveItemsFromCart()` increments the quantity of the item, using the quantity specified. If no quantity is specified, `moveItemsFromCart()` moves the entire quantity to the gift list. If a corresponding item doesn’t already exist, `moveItemsFromCart()` calls `GiftlistManager.createGiftlistItem()` to create the gift item, based on the properties in the original commerce item, then `moveItemsFromCart()` calls `GiftlistManager.addItemToGiftlist()` to add the item to the specified gift list. In multisite environments, `addItemToGiftlist()` also determines whether the gift item and the gift list have compatible site IDs before adding the item to the list (see Gift and Wish Lists in a Multisite Environment for more details). Finally, `moveItemsFromCart()` calls `GiftlistFormHandler.updateOrder()`. This method is responsible for updating the quantity of the commerce item in the shopping cart, or removing the item altogether if the entire quantity has been transferred to the gift list. Associated Methods: `moveItemsFromCart() updateOrder() preMoveItemsFromCart() postMoveItemsFromCart() GiftlistManager.createGiftlistItem() GiftlistMnager.addItemToGiftlist()` Success and Failure URL properties: `moveItemsFromCartSuccessURL moveItemsFromCartErrorURL`
`handleSaveGiftlist()`	Creates and saves gift lists in the `Giftlists` repository. This method calls `createGiftlist()` in the `GiftlistManager` component with gift list properties to create a gift list in the repository, save properties and add the gift list to the customer’s profile. Associated Methods: `preSaveGiftlist() postSaveGiftlist() GiftlistManager.createGiftlist()` Success and Failure URL properties: `saveGiftlistSuccessURL saveGiftlistErrorURL`
`handleUpdateGiftlist()`	Updates the current gift list. This method calls `updateGiftlist()` in the `GiftlistManager` component, passing in gift list properties, to update a particular gift list in the repository. Associated Methods: `preUpdateGiftlist() postUpdateGiftlist() GiftlistManager.updateGiftlist()` Success and Failure URL properties: `updateGiftlistSuccessURL updateGiftlistErrorURL`
`handleUpdateGiftlistItems()`	Changes the quantity of a gift list item or removes the item from the list. Associated Methods: `updateGiftlistItems() preUpdateGiftlistItems() postUpdateGiftlistItems()` Success and Failure URL properties: `updateGiftlistItemsSuccessURL updateGiftlistItemsErrorURL`

GiftlistFormHandler Example

The GiftlistFormHandler.properties file is used to configure the GiftlistFormHandler. This file is located at /atg/commerce/gifts/ in <ATG10dir>/DCS/config/config.jar.

Note: The GiftlistFormHandler.siteId property is typically set in the JSP page, not in the GiftlistFormHandler.properties file.

$class=atg.commerce.gifts.GiftlistFormHandler
$scope=session

# Profile properties
profile=/atg/userprofiling/Profile
defaultLocale^=/atg/commerce/pricing/PricingTools.defaultLocale

# Giftlist repository
giftlistRepository=Giftlists

# Business layer giftlist manager
giftlistManager=GiftlistManager

# Business layer order manager
orderManager=/atg/commerce/order/OrderManager
shoppingCart=/atg/commerce/ShoppingCart
pipelineManager=/atg/commerce/PipelineManager

# commerce tools
giftlistTools=GiftlistTools
catalogTools=/atg/commerce/catalog/CatalogTools
profileTools=/atg/userprofiling/ProfileTools

# giftlist properties
itemType=gift-list

The following code sample demonstrates how to use the GiftlistFormHandler in a template. This serves as an example of how to display error messages, set up input and URL properties and make calls to handle methods in the form handler.

Note: This code sample works for both multisite and non-multisite environments. In multisite environments, the sample will use the current site’s ID when setting the siteId property on the newly created gift list. To set a gift list’s siteId to something other than the current site, you should add another dsp:input tag (hidden or otherwise) that sets the siteId property on the GiftlistFormHandler. For more information on the siteId property, see Gift and Wish Lists in a Multisite Environment.

<!-Import statements for components-->
<dsp:importbean bean="/atg/commerce/gifts/GiftlistFormHandler"/>
<dsp:importbean bean="/atg/dynamo/droplet/ErrorMessageForEach"/>
<dsp:importbean bean="/atg/dynamo/droplet/ForEach"/>
<dsp:importbean bean="/atg/dynamo/droplet/Switch"/>

<!-- Display any errors processing form -->
<dsp:droplet name="Switch">
<dsp:param bean="GiftlistFormHandler.formError" name="value"/>
<dsp:oparam name="true">
  <UL>
    <dsp:droplet name="ErrorMessageForEach">
      <dsp:param bean="GiftlistFormHandler.formExceptions"
           name="exceptions"/>
      <dsp:oparam name="output">
        <LI> <dsp:valueof param="message"/>
      </dsp:oparam>
    </dsp:droplet>
    </UL>
</dsp:oparam>
</dsp:droplet>

<!-Save giftlist -->
<dsp:form action="lists.jsp" method="POST">
  <!-Success and error URLs -->
  <dsp:input bean="GiftlistFormHandler.saveGiftlistSuccessURL"
     value="./lists.jsp" type="hidden"/>
  <dsp:input bean="GiftlistFormHandler.saveGiftlistErrorURL"
     value="./new_list.jsp" type="hidden"/>
  <b>Event Name</b><br>
  <dsp:input size="40" type="text" bean="GiftlistFormHandler.eventName"/>
  <p>
  <b>Event Type</b>
   <dsp:select bean="GiftlistFormHandler.eventType">
   <dsp:droplet name="ForEach">
     <dsp:param bean="GiftlistFormHandler.eventTypes" name="array"/>
     <dsp:oparam name="output">
       <dsp:option paramvalue="element"><dsp:valueof
            param="element">UNDEFINED</dsp:valueof>
     </dsp:oparam>
     </dsp:droplet>
     </dsp:select><br>
  <p>
  <b>Event Description</b><br>
  <dsp:setvalue bean="GiftlistFormHandler.description" value=""/>
  <dsp:textarea bean="GiftlistFormHandler.description" value="" cols="40"
     rows="4"></dsp:textarea>
  <p>
  <b>Where should people ship the gifts?</b><p>
    <dsp:select bean="GiftlistFormHandler.shippingAddressId">
    <!-display address nicknames for profile to select from -->
    <dsp:droplet name="ForEach">
      <dsp:param bean="GiftlistFormHandler.addresses" name="array"/>
      <dsp:oparam name="output">
        <dsp:option paramvalue="key"/>
        <dsp:valueof param="element">UNDEFINED</dsp:valueof>
      </dsp:oparam>
    </dsp:droplet>
    </dsp:select><br>
  <b>Gift list public?</b>
  <p>
  <dsp:input bean="GiftlistFormHandler.isPublished" value="true"
     type="radio" name="published"/> Make my list public now<br>
  <dsp:input bean="GiftlistFormHandler.isPublished" value="false"
     checked="<%=true%>" type="radio" name="published"/> Don't make my list
     public yet
  <dsp:input bean="GiftlistFormHandler.saveGiftlist" value="Save gift
     list" type="submit"/>

GiftlistSearch

The /atg/commerce/gifts/GiftlistSearch form handler searches the repository for gift lists. The form handler uses input from the customer, such as owner name, event name, event type and state, to find gift lists published by other customers. It returns a list of gift lists that match the given criteria.

GiftlistSearch should be session-scoped because multiple pages are typically involved in gathering and displaying information for gift list searching (for example, you might want to maintain a list of results for paging purposes). This form handler uses supporting servlet beans to add the retrieved gift lists to the customer’s profile and to display gift list contents.

GiftlistSearch is configurable to support all gift list searching requirements. Booleans specify what types of searching are done. The configurable searches include:

Name Search: Searches by the name of the gift list owner.
Advanced Search: Searches for matches to specific gift list properties (such as event name, event type, and owner’s state).
Published List Search: When true, searches for published lists only. When false, searches for both published and unpublished gift lists.

GiftlistSearch Properties

GiftlistSearch has the following properties to support gift list searching:

Property	Function
`doNameSearch`	Specifies whether to search gift lists by the owner’s name.
`nameSearchPropertyNames`	Specifies the fields to use during a name search (typically, `owner.firstName` and `owner.lastName`).
`doAdvancedSearch`	Specifies whether to search gift lists using properties other than the owner’s name.
`advancedSearchPropertyNames`	Specifies the fields to use during an advanced search (for example, `eventType`, `eventName`, and `state`).
`doPublishedSearch`	Specifies whether to search only published gift lists.
`publishedSearchPropertyNames`	When searching only published gift lists, lists must be both public and published in order to be included in the search results. Therefore, if `doPublishedSearch` is set to true, set this value to `public,published`.
`giftlistRepository`	The repository that stores your gift lists. Set this value to `Giftlists`.
`itemTypes`	The gift list item type. Set this value to `gift-list`.
`giftlistManager siteGroupManager siteScope`	These three properties are required for multisite environments only. See Gift and Wish Lists in a Multisite Environment for more details.
`siteIds`	This property is used in multisite environments only. See Gift and Wish Lists in a Multisite Environment for more details.
`searchInput`	Input text parsed for searching. This property should be set by the JSP page.
`searchResults`	`Giftlist` repository items found based on searching criteria. Your results page must use this property to render search results.
`searchSuccessURL`	URL of the page to which the user is redirected on a successful search.
`searchErrorURL`	URL of the page to which the user is redirected on an error.

GiftlistSearch Handle Methods

GiftlistSearch has the following handle method:

Method	Function
`handleSearch`	`handleSearch` provides the core functionality of this form. This method builds a search query based on the configuration specified in the `GiftlistSearch` form handler’s properties file, along with any properties set on the JSP page itself. It then applies the query to the `Giftlists` repository to find a list of gift lists. The list is stored in the `searchResults` property for the form to display.

Method

Function

handleSearch

handleSearch provides the core functionality of this form. This method builds a search query based on the configuration specified in the GiftlistSearch form handler’s properties file, along with any properties set on the JSP page itself. It then applies the query to the Giftlists repository to find a list of gift lists. The list is stored in the searchResults property for the form to display.

GiftlistSearch Example

The following properties file is an example of how you configure the GiftlistSearch form handler. Note that the last three properties, giftlistManager, siteGroupManager, and siteScope, are required for multisite environments only. This properties file is located at /atg/commerce/gifts/GiftlistSearch.properties in <ATG10dir>/DCS/config/config.jar.

$class=atg.commerce.gifts.SearchFormHandler
$scope=session

doNameSearch=true
nameSearchPropertyNames=owner.firstName,owner.lastName

doAdvancedSearch=true
advancedSearchPropertyNames=eventType,eventName,state

doPublishedSearch=true
publishedSearchPropertyNames=public,published

giftlistRepository=Giftlists
itemTypes=gift-list

# Multisite properties: required for multisite enviromments only
giftlistManager=/atg/commerce/gifts/GiftlistManager
siteGroupManager=/atg/multisite/SiteGroupManager
siteScope^=/atg/commerce/gifts/GiftlistManager.siteScope

The following code sample demonstrates one method for using GiftlistSearch in a template in non-multisite environments.

Note: This code sample works for both multisite and non-multisite environments. In multisite environments, the sample will use the current site’s ID when determining which gift lists to return. To return gift lists from sites other than the current one, you should add another dsp:input tag (hidden or otherwise) that sets the siteIds property on the GiftlistSearch form handler. For more information on the siteIds property, see Gift and Wish Lists in a Multisite Environment.

<!-Import statements for form components>
<dsp:importbean bean="/atg/commerce/gifts/GiftlistSearch"/>
<dsp:importbean bean="/atg/dynamo/droplet/IsEmpty"/>
<dsp:importbean bean="/atg/dynamo/droplet/ForEach"/>
<dsp:importbean bean="/atg/dynamo/droplet/Switch"/>

<TITLE>Giftlist Search</TITLE>

<dsp:form action="giftlist_search.jsp">
<p>
<b>Find someone's gift list</b>
<hr size=0>
Name: <dsp:input bean="GiftlistSearch.searchInput" size="30" type="text"/>
<p>
Optional criteria that may make it easier to find the right list:
<p>
<dsp:droplet name="ForEach">
  <!-- For each property specified in
   GiftlistSearch.advancedSearchPropertyNames, retrieve all possible
   property values. This allows the customer
   to pick one to search on for advanced searching. -->
  <dsp:param bean="GiftlistSearch.propertyValuesByType" name="array"/>
  <dsp:oparam name="output">
  <dsp:droplet name="Switch">
    <dsp:param param="key" name="value"/>
    <dsp:oparam name="eventType">
    Event Type
      <!-- property to store the customer's selection is
           propertyValues -->
      <dsp:select bean="GiftlistSearch.propertyValues.eventType">
      <dsp:option value=""/>Any
      <dsp:setvalue paramvalue="element" param="outerelem"/>
      <dsp:droplet name="ForEach">
        <dsp:param param="outerelem" name="array"/>
        <dsp:oparam name="output">
        <dsp:option/><dsp:valueof param="element">UNDEFINED</dsp:valueof>
        </dsp:oparam>
      </dsp:droplet>
      </dsp:select><br>
    </dsp:oparam>
    <dsp:oparam name="eventName">
      <b>Event Name
      <!-- property to store the customer's selection is
           propertyValues -->
      <dsp:input bean="GiftlistSearch.propertyValues.eventName" size="30"
           value="" type="text"/> <br>
    </dsp:oparam>
    <dsp:oparam name="state">
      <b>State
      <!-- property to store the customer's selection is
           propertyValues -->
      <dsp:input bean="GiftlistSearch.propertyValues.state" size="30"
           value="" type="text"/> <br>
    </dsp:oparam>
  </dsp:oparam>
</dsp:droplet>

</dsp:droplet>
<p>
<dsp:input bean="GiftlistSearch.search" value="Perform Search"
     type="hidden"/>
<dsp:input bean="GiftlistSearch.search" value="Perform Search"
     type="submit"/>
</dsp:form>

Legal Notices

Gift List Form Handlers

GiftlistFormHandler

GiftlistSearch

ATG Commerce Programming Guide