Java Web Application Development With Click Framework/Controls

Click provides a rich set of Controls which support client side rendering and server side processing. This section covers the following topics:


 * The Control interface
 * Control event callback pattern
 * Control Java classes
 * Control message properties

While this section provides an overview how Controls work please see the Javadoc which provides extensive information and examples.

Control Interface
In Click Controls provide the server side components that process user input, and render their display to the user. Controls are equivalent to Visual Basic Controls or Delphi Components.

Controls handle the processing of user input with the onProcess method and rendering their HTML display using the toString method. The execution sequence for Control being processed and rendered is illustrated below in Figure 1.



'''Figure 1. Post Sequence Diagram''' - created with Enterprise Architect courtesy Sparx Systems

In Click all control classes must implement the Control interface. The Control interface is depicted below in Figure 2.



'''Figure 2. Control Interface Diagram''' - created with Enterprise Architect courtesy Sparx Systems

Methods on the Control interface include:


 * getContext - provides access to the request Context.
 * getHtmlImports - defines the controls HTML header imports.
 * getId - defines the controls HTML id attribute.
 * setListener - set the control action callback listener.
 * getMessages - defines the controls localized messages map.
 * getName / setName - defines the controls name in the Page model or Form fields.
 * getParent / setParent - defines the controls parent.
 * onDeploy - deploy resources on startup.
 * onInit - on initialize event handler.
 * onProcess - process request event handler.
 * onDestroy - on destroy event handler.

Control Callback
Click Controls provide an event callback mechanism similar the java.awt.ActionListener callback.

To define a control listener, simply set the listener object instance and the name of the listener method to be invoked. For example:

The listener method can have any name but it must have take no parameters and must return a boolean or java.lang.Boolean value.

When a callback method returns true the processing of other Controls will continue and the Pages onGet or onPost event handler will be called. If a controls returns false not further Control processing will be performed and neither of the Page onGet or onPost methods will be invoked.

Being able to stop further processing and do something else can be very handy. For example your Pages onGet or onPost method may perform an expensive database operation. By using returning false in a event handler you can skip this step and forward to the next page.

Control Classes
Core control classes are defined in the package net.sf.click.control. This package includes controls for the essential HTML elements.

Extended control classes are provided in the Click Extras package net.sf.click.extras.control. Click Extras classes can contain dependencies to 3rd party frameworks.

A subset of these control classes are depicted below in Figure 3.



'''Figure 3. Package Class Diagram''' - created with Enterprise Architect courtesy Sparx Systems

The key control classes include:


 * ActionLink - provides a anchor link which can invoke callback listeners.
 * Field - provides the abstract form field control.
 * Form - provides a form control for processing, validation and rendering.
 * Submit - provides a input type submit control which can invoke callback listeners.
 * TextField - provides a input type text control which can invoke callback listeners.

The control classes are designed to support subclassing for customized behaviour. All control fields have protected visibility and have public accessor methods.

You can also aggregate controls to build more complex controls. For example the CreditCardField uses a Select control to render the different credit card types.

Message Properties
Control strings for field validation messages and HTML formatting strings are externalized in the properties file. By using these properties files you can localize a Click application for your particular language and dialect.

Message Resolution
Messages are looked up in a particular order enabling tailor specific messages, for your controls, individual pages or across your entire application. The order in which localized messages are resolve is:


 * Page scope messages
 * Message lookups are first resolved to the Page classes message bundle if it exists. For example a Login page may define the message properties:
 * /com/mycorp/page/Login.properties
 * If you want to tailor messages for a particular page this is where to place them.


 * Global page scope messages
 * Next message lookups are resolved to the global pages message bundle if it exists.
 * /click-page.properties
 * If you want messages to be used across your entire application this is where to place them.


 * Control scope messages
 * Next message lookups are resolved to the Control classes message bundle if it exists. For example a CustomTextField control may define the message properties:
 * /com/mycorp/control/CustomTextField.properties


 * Global control scope messages
 * Finally message lookups are resolved to the global application control message bundle if the message has not already found. The global control properties file is:
 * /click-control.properties

Control Properties
To customize the click-control.properties simply add this file to your classpath and tailor the specific values.

Note when customizing the message properties you must include all the properties, not just the ones you want to override.

Accessing Messages
Field classes support a hierarchy of resource bundles for displaying validation error messages and display messages. These localized messages can be accessed through the Field methods:


 * getMessage(String)
 * getMessage(String, Object)
 * getMessage(String, Object[])
 * getMessages
 * setErrorMessage(String)
 * setErrorMessage(String, Object)

These methods use the Locale of the request to lookup the string resource bundle, and use MessageFormat for any string formatting.