Custom Form Handlers in oracle ATG

Form Handlers:

            In many web applications users input are taken from the forms.A form may need to handle user input in a variety of formats, check input for validity, handle errors, and pass input to a servlet for processing or to a database for storage.  ATG java classes that process these forms are none other than Formhandlers.

•         We can create forms in JSP Pages that set values of properties of Nucleus components directly when the form is submitted.

•         For more complex form handling operations, setting the values of properties directly is not always desirable. It is generally preferable to first submit the form to a form handler.

•         The form handler can evaluate the validity of the data, check for errors, and determine what action to take (e.g., submit the data, direct the user to a different page, display an error message, etc.)

•         Often when you use a form handler, the form input fields are associated with properties of the form handler rather than the component you ultimately want to modify

A form handler class must include one or more handler methods. A handler method is typically invoked when the user clicks the submit button, and handles the processing of the form. Depending on the purpose of the form handler, it can have several different handler methods that each perform a different operation. For example, a form handler that works with user profiles might have separate handler methods for creating the profile, modifying the profile, and logging the user in.

If the form uses FormHandler, the exceptions that occurred while processing the form are stored in the following properties.

•         formError : A Boolean that is true if any errors occurred when the form was processed.

•         formExceptions : A vector of the exceptions that occurred when the form is processed.

•         propertyExceptions : A read-only property that returns a Dictionary of subproperties, one for each property set by the form. For any property that generated an exception, the corresponding subproperty in the propertyExceptions Dictionary contains that exception. For any property that did not generate an exception, the corresponding subproperty in the propertyExceptions Dictionary is unset.

If a form handler returns “false” it will redirect to the same page. And if the form handler returns “true” it will redirect it to the success URL.

For every handle method in a formhandler the order of execution is:

•          1.beforeSetXXX() of the property

•          2.tag convertors (if any) will be applied(Note: Tag converters are converter classes that are used to convert the data from input/ to output)

•          3.preXXX()

•          4.handleXXX()

•          5.postXXX()

•          6.afterSetXXX()

        

Displaying Error Messages in Form Handlers:

Use this droplet to loop through and display the error messages that are generated by a form:

<dsp: droplet name=“/atg/dynamo/droplet/ErrorMessageForEach”>

<dsp:oparam name=“output”>

            <dsp:valueof param=“message”/><br>

</dsp:oparam>

</dsp:droplet>

ATG Form Handlers base classes:

Oracle ATG Web Commerce form handler classes all implement the interface atg.droplet.DropletFormHandler. Three form handler base classes implement this interface:

·         atg.droplet.EmptyFormHandler

·         atg.droplet.GenericFormHandler

·         atg.droplet.TransactionalFormHandler

EmptyFormHandler

atg.droplet.EmptyFormHandler implements the DropletFormHandler interface and provides empty implementations of the methods in this interface.

GenericFormHandler

atg.droplet.GenericFormHandler extends EmptyFormHandler. It provides simple implementations of DropletFormHandler interface methods and adds basic error handling logic. If errors occur in processing a form that uses GenericFormHandler, the errors are saved and exposed as properties of the form handler component. This form handler is included in the public API

TransactionalFormHandler

atg.droplet.TransactionalFormHandler extends atg.droplet.GenericFormHandler; it treats the form processing operation as a transaction. Although this form handler methods are processed discretely, their results are saved simultaneously. The transaction management occurs in the beforeGet and afterGet methods. This establishes the transaction before any of properties are set or handler methods are called, rather than in the handler methods themselves.

You can create a form handler by extending one of these classes or any of their subclasses.

Some of the classes that extend the base class in ATG API are:

Ø  SimpleSQLFormHandler for working with form data that is stored in a SQL database.

Ø  RepositoryFormHandler for saving repository data to a database.

Ø  ProfileFormHandler class to connect forms with user profiles stored in a profile repository

Ø  SearchFormHandler for specifying properties available to a search engine.

Steps in Writing a Custom FormHandler:

Non Java Steps:

Step i: Create a JSP file calling the from handler.

In The above example the submit is given to LoginBean.login (note “l” is small in “login”) so the LoginBean java class will call handleLogin() method (note “l” is Caps for “handle Method”).

Step ii: create properties file for the java class. Content will be similar to:

$class=managedBeans.LoginBean

$scope=global  

JAVA STEPS:

Step 1: Create a java class extending the atg.droplet.GenericFormHandler base class.

Step 2: Provide the appropriate handlexxx methods. Each Handler method will be triggered by

corresponding dsp:input submit button from the jsp page.

Step 3: Provide either a Map data structure to hold the form data or provide individual fields

with apprppriate set/get methods.

Step 4: Write the desired codes and return the Boolean codes appropriately.

Step 5: Populate validation errors if any

Step 6: Forward the user to the appropriate success URL.