Form handlers process forms and pages. They provide an interface between the customer and the manager classes with 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 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 GiftlistFormHandler provides the primary interface between the customer and the Giftlists repository. This handler accepts input from the customer to create, update and delete gift lists, as well as to add items to gift lists. (See GiftitemDroplet in Gift List Servlet Beans for information on how to 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 simplify extending the methods to add functionality.

The GiftlistFormHandler, like most form handlers, should be session-scoped because multiple pages usually gather the information needed for gift list management. The site 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 to interface with the repository.

catalogTools

The tools component to provide low level operations on the catalog.

CommerceProfileTools

The tools component to provide low level operations on the commerce specific profile.

Giftlist properties (for example, eventName, eventDate, description)

Giftlist properties to store information entered by the customer to use for management of attributes.

Navigation properties

Navigation properties are used to tell Dynamo to what pages to redirect after an action is performed. Both success and failure URL properties are provided.

GiftlistFormHandler Submit Handle Methods

The GiftlistFormHandler has the following handle and support methods:

Method

Function

handleAddItemToGiftlist

Adds items to a gift list during the shopping process. It takes the skuId, quantity and giftlistId from the form.

This method performs a few steps to add the item. It looks up the product in the repository by skuId. Then it checks if the item already exists in the giftlist. If it does, it increments the desired quantity. If it does not, it adds the item to the gift list by calling addItemToGiftlist in the manager class with the correct parameters.

handleCreateGiftlist

Creates a new Giftlist object.

handleDeleteGiftlist

Deletes a gift list from the user’s profile and from the repository. It calls removeGiftlist in the manager class with the profileId and giftlistId to remove it from the repository.

handleSaveGiftlist

Creates and saves gift lists in the Giftlists repository. It calls createGiftlist in the manager class with gift list properties to create a gift list in the repository, save properties and add the gift list to the customer’s profile.

handleUpdateGiftlist

Updates the current gift list. It calls updateGiftlist in the manager class with gift list properties to update a particular gift list in the repository.

preAddItemToGiftlist

Executed at the start of the handleAddItemToGiftlist method. The default implementation is empty. This method provides a way to extend the functionality of this form handler.

preSaveGiftlist

Executed at the start of the handleSaveGiftlist method. The default implementation is empty. This method provides a way to extend the functionality of this form handler.

postAddItemToGiftlist

Executed at the end of the handleAddItemToGiftlist method. The default implementation is empty. This method provides a way to extend the functionality of this form handler.

postSaveGiftlist

Executed at the end of the handleSaveGiftlist method. The default implementation is empty. This method provides a way to extend the functionality of this form handler.

GiftlistFormHandler Navigation Properties

After a form operation (createGiftlist, saveGiftlist, addItemToGiftlist) is completed, you can redirect the customer to pages other than those specified by the form’s action attribute. This page’s content depends on the type of form 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.

The GiftlistFormHandler has a set of properties you can use to control navigation after a form operation. These properties specify the URLs to which to redirect on certain error and success conditions. If the value for a particular condition is not set, no redirect takes place and the form is left on the page defined as the action page. Each operation has its own SuccessURL and ErrorURL properties. The properties available include the following:

  • createGiftlistSuccessURL

  • createGiftlistErrorURL

  • saveGiftlistSuccessURL

  • saveGiftlistErrorURL

  • deleteGiftlistSuccessURL

  • deleteGiftlistErrorURL

  • addItemToGiftlistSuccessURL

  • addItemToGiftlistErrorURL

The value of each of these properties is a URL relative to the action page of the form. Either you can 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"/>

GiftlistFormHandler Example

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

$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.

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

<!-- Display any errors processing form -->
<dsp:droplet name="/atg/dynamo/droplet/Switch">
<dsp:param bean="GiftlistFormHandler.formError" name="value"/>
<dsp:oparam name="true">
  <font color=cc0000><STRONG><UL>
    <dsp:droplet name="/atg/dynamo/droplet/ErrorMessageForEach">
      <dsp:param bean="GiftlistFormHandler.formExceptions"
name="exceptions"/>
      <dsp:oparam name="output">
     <LI> <dsp:valueof param="message"/>
      </dsp:oparam>
    </dsp:droplet>
    </UL></STRONG></font>
</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>
  <input size="40" value='<dsp:valueof
bean="GiftlistFormHandler.eventName"/>' type="text">
  <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:getvalueof id="option76" param="element"
idtype="java.lang.String">
<dsp:option value="<%=option76%>"/>
</dsp:getvalueof><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:getvalueof id="option117" param="key"
idtype="java.lang.String">
<dsp:option value="<%=option117%>"/>
</dsp:getvalueof><dsp:valueof param="element">UNDEFINED</dsp:valueof>
      </dsp:oparam>
    </dsp:droplet>
    </dsp:select><br>
  <table width=100% cellpadding=0 cellspacing=0 border=0>
  <tr><td class=box-top-store>Gift list public?</td></tr></table>
  <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 GiftlistSearch form handler searches the repository for gift lists. The 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.

Like most form handlers, GiftlistSearch should be session-scoped because multiple pages are typically involved in gathering and displaying information for gift list searching. 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 searching is done. The configurable searches include:

GiftlistSearch Properties

GiftlistSearch has the following properties to support gift list searching:

Property

Function

doNameSearch

Specifies if searching by name.

doAdvancedSearch

Specifies if searching gift lists by advanced properties.

advancedSearchPropertyNames

Advanced search property names.

doPublishedSearch

Specifies if searching only published gift lists.

searchInput

Input text parsed for searching.

searchResults

Giftlist repository items found based on searching criteria.

GiftlistSearch Submit Handle Methods

GiftlistSearch has the following handle submit method:

Method

Function

handleSearch

handleSearch provides the core functionality of this form. It uses the configuration set in the properties file to build its query string. This method builds the query based on the configuration and applies it to the Giftlists repository to find a list of gift lists. The list is stored in the results property for the form to display.

GiftlistSearch Example

The following properties file is used to configure the GiftlistSearch form handler. This properties file is located at /atg/commerce/gifts/GiftlistSearch.properties in /<ATG9dir>/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

The following code sample demonstrates how to use GiftlistSearch in a template. It is only one example of how it might be used to search for gift lists.

giftlist_search.jsp:

<!-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"/>
    <!-- One property that a product in the store can have is weight
range.
     In this case, if the property is weight range, we want to put all
     possible choices in a pulldown menu. -->
    <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>
 
loading table of contents...