Form handlers use special handler methods for linking form elements with Nucleus components. A handler method has the name handleX, where X represents the name of the form handler property being set. This method must have the following signature:

public boolean handleX (javax.servlet.http.HttpServletRequest request,
                        javax.servlet.http.HttpServletResponse response)

A handleX method can also declare that it throws java.io.IOException or javax.servlet.ServletException.

This handleX method is called when the form is submitted. If a corresponding setX method also exists, the setX method is called before the handleX method is called.

The handleX method is passed the request and response objects that encapsulate the request. (Consult the Java Servlet specifications to see how to use these request and response types.) In many cases, however, the handler method does not need to do anything with the request and response objects. For example, the handler method might simply redirect the user to another page.

A handleX method can also use the Dynamo extensions to the HttpServletRequest and HttpServletResponse interfaces. These extensions are called DynamoHttpServletRequest and DynamoHttpServletResponse. This means that the signature of your handler method can look like this:

public boolean handleX (atg.servlet.DynamoHttpServletRequest request,
                        atg.servlet.DynamoHttpServletResponse response)

The handler method returns a Boolean value. This value indicates whether Dynamo should continue processing the rest of the page after this handler has finished. If false is returned, Dynamo does not process any remaining values after calling the handler, nor serves the rest of the page. A handler that redirects the user to another page, for example, should return false. If true is returned, Dynamo continues to process the rest of its values as it would normally, and serves the page specified by the form’s action attribute.

As mentioned above, Dynamo form handlers typically implement an interface called DropletFormHandler. This interface has the following methods, which are called at specific points as the form is processed:

Method

When Called

beforeSet

Before any setX methods are called

afterSet

After all setX methods are called

beforeGet

Before any input tags that reference this component are rendered

afterGet

After page rendering is complete, before the socket is closed

handleFormException

If an exception occurs when trying to call the setX method of a form

The beforeGet and afterGet methods are called only when the page is rendered, not when the form is submitted. The beforeSet and afterSet methods are called only when the form is submitted, not when the page is rendered. It is possible to have all four of these methods called on the same page.

See the Quincy Funds demo for an example of form handling. This demo uses form handler to process registration, login, and profile updates.

 
loading table of contents...