ATG - more about Forms and Form Handlers

An ATG form is defined by the dsp:form tag, which typically encloses DSP tags that specify form elements, such as dsp:input that provide direct access to Nucleus component properties. Find below a sample dsp:form tag.
   <dsp:form action="/testPages/showPersonProperties.jsp" method="post" target="_top">
     <p>Name: <dsp:input bean="/samples/Person.name" type="text"/>
     <p>Age: <dsp:input bean="/samples/Person.age" type="text" value="30"/>
     <p><dsp:input type="submit" bean="/samples/Person.submit"/> value="Click to submit"/>
   </dsp:form>
 
When the user submits the form, the /samples/Person.name property is set to the value entered in the input field.Unlike standard HTML, which requires the name attribute for most input tags; the name attribute is optional for DSP form element tags. If an input tag omits the name attribute, the ATG platform assigns one when it compiles the page. A text input field displays the component property’s current value unless the dsp:input tag also includes the value attribute. The value attribute overrides the property’s current value.

If an outer JSP has a dsp:form then the inner included page(dsp:include) can contain element tags such as dsp:input, dsp:textarea, and dsp:select only if the page is a complete JSP. Form elements cannot be embedded in a JSP fragment (.jspf) file.

ATG provides hundreds of readymade form handlers for performing all sorts of tasks, like updating a customer profile(CommerceProfileFormHandler), managing your shopping cart(CartModifierFormHandler), checking out(ExpressCheckoutFormHandler), or interacting with a repository(RepositoryFormHandler).

Following are the tasks assigned to Form Handlers by ATG :

• Validate data before it is submitted.
• Detect missing information and display appropriate messages to the user.
• Direct users to different pages depending on form submission results.
• Read and write database or repository data.

A better way to create a new form handler is to subclass a Dynamo class that implements DropletFormHandler interface. Dynamo provides three form handler base classes that implement this interface :

• atg.droplet.DropletFormHandler --> inteface
• atg.droplet.EmptyFormHandler --> implements DropletFormHandler
• atg.droplet.GenericFormHandler --> extends EmptyFormHandler
• atg.droplet.TransactionalFormHandler --> extends GenericFormHandler --> treats the form processing operation as a transaction.

Find below a sample call to /atg/search/formhandlers/SearchValidateFormHandler from a JSP :

      <dsp:input bean="SearchValidateFormHandler.validate" name="validate" id="validate" type="hidden" value="DAS" style="display:none" priority="-10"/>

A handler method will be specified with the name ‘handlex’ where x represents the name of the submit. The signature of the handle method is:

       public boolean  handlex(DynamoHttpServletRequest request,
DynamoHttpServletResponse response)throws IOException, ServletException{}

The handler method (handlex) returns a boolean value. This value indicates whether Dynamo should continue processing the rest of the page after this handler has finished. In the above example, there is a public boolean handleValidate(DynamoHttpServletRequest pRequest,DynamoHttpServletResponse pResponse) method @ SearchValidateFormHandler.

If there are any setx methods in the FormHandler, it will be called before the handlex method is invoked. Some of the other methods used by the form handler are:

• beforeSet --> This is called before any setx methods are called.
• afterSet --> This is called after all setx methods are called.
• beforeGet  --> This is called before any tags that reference the component is rendered.
• afterGet --> This is called after the page rendering gets completed.
• handleFormException --> This is called when any exception occurs while trying to call the setx methods.

Following are the form handler component properties to handle form errors/exceptions:

• formError --> Boolean that is set to true if any errors occur during form processing.
• formExceptions  --> A vector of the exceptions that occur during form processing.  If your form handler is session-scoped, clear the formExceptions property after you display errors to the user.
• propertyExceptions  --> A read-only property that returns a Dictionary of subproperties, one for each property set by the form. For each property that generates an exception, a corresponding subproperty in the propertyExceptions Dictionary contains that exception

Use the checkFormRedirect(String pSuccessURL, String pFailureURL, DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse) method of GenericFormHandler to redirect to a url from the formhandler on a success/error cases. A handler that redirects the user to another page should return false.

The atg.droplet.GenericFormHandler class (and any subclass of GenericFormHandler you write) includes a handleCancel method for implementing Cancel buttons in forms. This method redirects to the URL specified in the form handler’s cancelURL property.

When a dsp:setvalue tag is rendered for a form handler property, it invokes the setX and handleX methods of the form handler (if the methods exists).

A form handler component should be either request- scoped or session-scoped.When your form handler spans several pages, such as in a multi-page registration process,  you want the session-scoped form handler.It is especially important to clear error messages to ensure they do not appear in other forms where they are not relevant.