Developing ATG Applications

Part I
Chapter 6 • Using Repository Form Handlers

Using ATG Repositories, Scenario PersonalizationSM

and the Dynamo Application Framework
Objectives
• After completing this chapter, you will be able to
— Understand ATG's form handling capabilities

— Create a form handler using the

RepositoryFormHandler class
— Create a form page that allows the user to

modify repository data

— Create and use a search form handler to

search the repository

6-2
Dynamusic Forms
• Dynamusic.com needs a way for users to enter
information on the site
— Concert and album reviews

— User registration and profile updates

— Song and event data (admin users)

— Discussion group bulletin board postings

— Etc.

• User input needs to be received, validated and

stored in a repository

6-3
ATG Forms
• ATG provides a powerful mechanism for
handling forms in JSPs, by combining
— DSP form tags: special versions of the

standard HTML form tags that link form

fields to component properties
— ATG Form Handlers: components that

manage form input and processing

6-4
 Repository Form Handler

6-5
RepositoryFormHandler
• ATG provides a specialized class to handle form
input to a repository
— Supports creating new items, and updating or

deleting existing items

— Handles errors

— Redirects to specified pages based on result of

the operation
— Class for component instances configured for

repository and item type

6-6
Configuring a Repository Form Handler
• Create a new component based on the
RepositoryFormHandler class

VenueForm
Handler Events
repository Repository venue

itemDescriptorName = "venue"
concert

requireIdOnCreate = "false"

scope = request id
name
description
venue
imageURL
…
6-7
Using a Repository Form Handler

VenueForm id
Handler
name
itemDescriptorName = "venue"
venue description
value imageURL
…

page.jsp
id
<… bean=
name "VenueFormHandler.
description value.name" …/>

imageURL
…

6-8
Using DSP Form Tags (1)

VenueForm
Handler
value

name Madison Square

Garden
description "The Garden" is
New York City's
premiere location…
…

6-9
Using DSP Form Tags (2)
newVenue.jsp
<dsp:form action="newVenue.jsp" method="post">
…
Venue Name:
<dsp:input bean="VenueFormHandler.value.name"
type=text/>
…
Description:
<dsp:textarea
bean="VenueFormHandler.value.description"
cols="40" rows="4"/>
…
</dsp:form>

6-10
DSP Input Tags (1)
• DSP input tags must be used inside a
<dsp:form> tag
• DSP form input tags have the same attributes as
the corresponding HTML tags plus a bean
attribute
• By default, the current value of the bean
property will be displayed in the form
— Override the existing value by setting the

value attribute
<dsp:input type="type"
bean="component.property"
value="value"/>

6-11
DSP Input Tags (2)
• You can mark an input field as "required"
• An exception will be thrown if the user does not
supply a value
<dsp:input bean="VenueFormHandler.value.name"
required="true"/>
• Converters can be used to convert string input to
the data type required by the property definition
<dsp:input bean="ConcertFormHandler.date"
date="M/dd/yyyy"/>

6-12
Default Values
• Default values can be specified in the form
• Syntax depends on the source of the default
value
— Literal

<dsp:input value="No image available" …/>

— Component property
<dsp:input
beanvalue="Profile.favoriteArtist.name"…/>
— Parameter
<dsp:input paramvalue="element.title"…/>

6-13
Multi-value Form Input (1)

VenueForm
Handler
value

name Fleet Center

type concert
sport
other
…

6-14
Multi-value Form Input (2)
<dsp:input type="checkbox"
bean="VenueFormHandler.value.type"
value="concert" checked="<%=true%>"/>Concerts<br>
<dsp:input type="checkbox"
bean="VenueFormHandler.value.type"
value="sport" />Sporting Events<br>
<dsp:input type="checkbox"
bean="VenueFormHandler.value.type"
value="theater" />Plays and Musicals<br>
<dsp:input type="checkbox"
bean="VenueFormHandler.value.type"
value="dance" />Dance Performances<br>
<dsp:input type="checkbox"
bean="VenueFormHandler.value.type"
value="other" />Other<br>

name Fleet Center

type concert
sport
other
6-15
Hidden Input Fields
• Hidden fields allows you to pass a value to the
form handler without allowing the user to see or
change it
<dsp:input type="hidden"
bean="RepositoryFormHandler.repositoryId"
paramvalue="itemId"/>
• Often used to pass parameters to the target page
<dsp:form action="newpage.jsp">
<input type="hidden" value="artist.jsp"
name="lastviewed">…
is equivalent to URL newpage.jsp?
lastviewed=artist.jsp

6-16
Submission Handler Methods (1)
• HTML forms are processed when a form Submit
button is clicked
• RepositoryFormHandler supplies several
methods that can be called on submission to
process the data in the form
— create – creates a new item based on the

form input
— update – updates the current repository item

based on form input

— delete – deletes the current repository item

— cancel – cancels the form in progress

6-17
Submission Handler Methods (2)

<dsp:form action="newVenue.jsp" method="post">

…
<dsp:input bean="VenueFormHandler.create"
type="Submit" value="Add New Venue"/>
<dsp:input bean="VenueFormHandler.cancel"
type="Submit" value="Cancel"/>
…
</dsp:form>
6-18
Page Redirection (1)
• By default, when the form is submitted, the
form's "action" page will be displayed
<dsp:form action="newVenue.jsp" method="post">
• RepositoryFormHandler lets you specify a
different page to redirect to based on the results
of the submission
<dsp:form action="newVenue.jsp" method="post">
…
<dsp:input
bean="VenueFormHandler.createSuccessURL"
type="hidden" value="venues.jsp"/>
…
</dsp:form>

6-19
Page Redirection (2)
• RepositoryFormHandler has both success
and error redirection properties for each
submission handler
— createSuccessURL

— createErrorURL

— updateSuccessURL

— updateErrorURL

— deleteSuccessURL

— deleteErrorURL

6-20
A Common Form Page Design (1)
• One common approach to form page redirection
is to set the action page back to the form page
— Process errors on the form page itself if

necessary
— Redirect on success by setting the success

URL property
error

Success
Form Page success Page

6-21
A Common Form Page Design (2)
• Rather than hard-coding in the current page as
the "action" of a form, use a JSP expression

<dsp:form method="post" action="<

%=request.getRequestURI()%>">

6-22
Error Handling (1)
• RepositoryFormHandler has properties to
help manage form errors
— formError (boolean) – true if an error

occurred processing the form

— formExceptions - an vector of all

exceptions that occurred

— propertyExceptions – a Dictionary

that maps repository item properties to

exceptions that occurred while processing
that property

6-23
Error Handling (2)
You can use the ErrorMessageForEach Servlet
Bean to loop through and display the error
messages that are generated by a form
<dsp:droplet
name="/atg/dynamo/droplet/ErrorMessageForE
ach">
<dsp:oparam name="output">
<dsp:valueof param="message"/> <br>
</dsp:oparam>
</dsp:droplet>

6-24
Example: ErrorMessageForEach

6-25
Updating Existing Repository Items
• The previous example showed creation of a
new item; updating an item requires three
extra steps
1. Populate the form with the existing data
2. Set the item ID for the item to update on the
form handler
3. Pass the item ID to the "action" page

6-26
Request Scoped Form Handlers
request #1: editVenue.jsp request #2: success.jsp

VenueForm VenueForm
Venue Venue
Handler Handler
Repository Repository
update

6-27
Populating a RepositoryFormHandler
venueDetails.jsp
<dsp:a href="editVenue.jsp">
<dsp:param name="itemId"
param="itemId"/>
Edit Venue
</dsp:a>

editVenue.jsp
<dsp:setvalue
bean=
"VenueFormHandler.repositoryId"
paramvalue="itemId"/>

6-28
Setting the Item ID in the Form Handler
editVenue.jsp
<dsp:setvalue
bean="VenueFormHandler.repositoryId"
paramvalue="itemId"/>

<dsp:form action="<%=request.getRequestURI()%>"
method="post">
…
<dsp:input bean="VenueFormHandler.repositoryId"
type="hidden" paramvalue="itemId"/>
…
</dsp:form>

6-29
Passing the Item ID to the Action Page
editVenue.jsp
<dsp:setvalue
bean="VenueFormHandler.repositoryId"
paramvalue="itemId"/>

<dsp:form action="<%=request.getRequestURI()%>"
method="post">
…
<dsp:input bean="VenueFormHandler.repositoryId"
type="hidden" paramvalue="itemId"
name="itemId"/>
…
</dsp:form>

6-30
Advanced RepositoryFormHandler
Features
• All examples shown here have been simple item
properties
• The RepositoryFormHandler can also handle
some more complex operations including
— manipulating multi-value properties (adding,

removing, overriding)
— managing item relationships

• Advanced RepositoryFormHandler
functionality is detailed in the Page Developer's
Guide

6-31
Form Handlers and the ACC

• Some form
handlers (including
RepositoryForm
Handler) include
wizards to help set
up the form

6-32
 Search Form Handlers

6-33
Search Form Handlers
• Search Forms allow users to search for
repositories that match criteria

6-34
Using SearchFormHandler
• SearchFormHandler supports several kinds of
searches
— Keyword – simple string comparison

— Text – full text search including wildcards

— Advanced – search for values for different

properties, including ranges of values

— Hierarchical – search for items in a hierarchy

6-35
Configuring a Keyword Search Component

EventSearch
FormHandler Events
repositories Repository venue

itemTypes = "concert" concert

keywordSearchPropertyNames =
"concert.name",
"concert.description"

doKeywordSearch = "true" id
name
scope = session
description
imageURL
concert …

6-36
Using SearchFormHandler (1)

searchevents.jsp

<dsp:form action="<%=request.getRequestURI()%>"
method="post">
Search for concerts:
<dsp:input type="text"
bean="EventSearchFormHandler.keywordInput"/>
<dsp:input
bean="EventSearchFormHandler.successURL"
type="hidden" value="eventSearchResults.jsp"/>
<dsp:input bean="EventSearchFormHandler.search"
type="submit" value="Search"/>
</dsp:form>
6-37
Using SearchFormHandler (2)
eventSearchResults.jsp
<p>The following events match your criteria: <p>
<dsp:droplet name="ForEach">
<dsp:param bean="EventSearchFormHandler.searchResults"
name="array"/>
<dsp:oparam name="output">
<li>
<dsp:a href="concertDetails.jsp">
<dsp:param name="itemId" param="element.id"/>
<dsp:valueof param="element.name"/>
</dsp:a>
</dsp:oparam>
<dsp:oparam name="empty">
Sorry, no concerts matched
your search criteria.
</dsp:oparam>
</dsp:droplet>
6-38
ATG Search
• The SearchFormHandler component provides
very basic searching capabilities using string
comparison (keyword) or database text
searching (text)
• The ATG Search product provides much more
advanced searching
— Natural language processing

— Contextual and concept searches

— Relevance ranking

— Etc.

6-39
Summary
In this chapter, you learned
• About the ATG form handling architecture

• How to use DSP form tags to attach user input to

component properties
• How to attach submit buttons to form handler

submit methods
• How to use the RepositoryFormHandler to

create, delete, and update Repository items

• How to use a SearchFormHandler component

to search for Repository items

6-40
For More Information
• Page Developer's Guide
— "Creating Forms"

— "Using Search Forms"

— "Using Repository Form Handlers"

— "DSP Tag Library" reference appendix

6-41
Exercises
• Create forms to add, update or delete an artist
• Create a search form handler and form page to
search for songs by title or description substring

6-42