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 |
---|---|
| The manager component that interfaces with the |
| The tools component that performs low-level operations on the catalog repository. |
| 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, |
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. |
| Used in multisite environments only. In multisite environments, if you do not want to use the current site as the |
GiftlistFormHandler Handle Methods
The GiftlistFormHandler
has a number of handle
methods. Many of the handle
methods have corresponding pre
methodName
, post
methodName
, and methodName
methods. For example, the handleCreateGiftlist
method has corresponding preCreateGiftlist
, postCreateGiftlist
and createGiftlist
methods. A handle method calls its pre
methodName
method before executing its methodName
method. Likewise, it calls its post
methodName
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 |
---|---|
| Adds items to a gift list during the shopping process, using the following properties taken from the form: quantity,
Associated Methods: Success and Failure URL properties: |
| Resets the properties in the Associated Methods: Success and Failure URL properties: |
| Deletes a gift list from the user’s profile and from the repository. This method calls Associated Methods: Success and Failure URL properties: |
| Takes items out of the shopping cart and adds them to the gift list whose ID is passed into the form handler.
Associated Methods: Success and Failure URL properties: |
| Creates and saves gift lists in the Associated Methods: Success and Failure URL properties: |
| Updates the current gift list. This method calls Associated Methods: Success and Failure URL properties: |
| Changes the quantity of a gift list item or removes the item from the list. Associated Methods: Success and Failure URL properties: |
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. Whenfalse
, searches for both published and unpublished gift lists.
GiftlistSearch Properties
GiftlistSearch
has the following properties to support gift list searching:
Property | Function |
---|---|
| Specifies whether to search gift lists by the owner’s name. |
| Specifies the fields to use during a name search (typically, |
| Specifies whether to search gift lists using properties other than the owner’s name. |
| Specifies the fields to use during an advanced search (for example, |
| Specifies whether to search only published gift lists. |
| When searching only published gift lists, lists must be both public and published in order to be included in the search results. Therefore, if |
| The repository that stores your gift lists. Set this value to |
| The gift list item type. Set this value to |
| These three properties are required for multisite environments only. See Gift and Wish Lists in a Multisite Environment for more details. |
| This property is used in multisite environments only. See Gift and Wish Lists in a Multisite Environment for more details. |
| Input text parsed for searching. This property should be set by the JSP page. |
|
|
| URL of the page to which the user is redirected on a successful search. |
| URL of the page to which the user is redirected on an error. |
GiftlistSearch Handle Methods
GiftlistSearch
has the following handle method:
Method | Function |
---|---|
|
|
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>