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 |
---|---|
| The manager component to interface with the repository. |
| The tools component to provide low level operations on the catalog. |
| The tools component to provide low level operations on the commerce specific profile. |
|
|
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 |
---|---|
| Adds items to a gift list during the shopping process. It takes the This method performs a few steps to add the item. It looks up the product in the repository by |
| Creates a new |
| Deletes a gift list from the user’s profile and from the repository. It calls |
| Creates and saves gift lists in the |
| Updates the current gift list. It calls |
| Executed at the start of the |
| Executed at the start of the |
| Executed at the end of the |
| Executed at the end of the |
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:
Name Search: Searches by the name of the gift list owner.
Properties Search: Searches for matches of specific gift list properties (such as event name, event type, and owner’s state).
Published List Search: Searches for both published and unpublished gift lists by turning
doPublishedSearch
to false in the configuration file.
GiftlistSearch Properties
GiftlistSearch
has the following properties to support gift list searching:
Property | Function |
---|---|
| Specifies if searching by name. |
| Specifies if searching gift lists by advanced properties. |
| Advanced search property names. |
| Specifies if searching only published gift lists. |
| Input text parsed for searching. |
|
|
GiftlistSearch Submit Handle Methods
GiftlistSearch
has the following handle submit method:
Method | Function |
---|---|
|
|
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>