Saturday, 25 August 2012

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/" 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"/>
When the user submits the form, the /samples/ 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.


  1. hi sony,
    Iam really amazed the way you put efforts to write these blogs. Please could you write something about folder structure. how it is created, if you could. God bless you

  2. check it @

    If you want to know anything special, please raise it... :-)

  3. this post is good one tag An ATG form is defined by the dsp:form tag, which typically encloses DSP tags that specify form elements

  4. your efforts are brilliant. please try to increase the examples on form handlers and droplets. as i am a beginner your blog helping me alot!

  5. Thank you for the info. It sounds pretty user friendly. I guess I’ll pick one up for fun. thank u

    Form Processing

  6. Hi sony,

    Great effort!.it's really helpful for beginners like me.could you please explain login validations using form handlers?

  7. hi sony,
    I want to know how to extend the oob(Out Of Box) components and how can i override those methods....

  8. Hi Sony,

    Thanks for your valuable time that you gave here to write this blog.
    It is very very helpful and your effort is really appreciable.
    Wish to see more posts from you in coming future.

    Great job :)

  9. i am new to ATG, Please explain me how ATG is Different From other tools or Frameworks to develop Websites. Thank you Somuch