Controls

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

Control Interface - describes the Control interface
Control Callback - control event callback pattern
Control Classes - control Java classes
Message Properties - control message properties

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

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() / setContext() - provides access to the request Context.
setListener() - set the control action callback listener.
getName() / setName() - defines the controls name in the Page model or Form fields.
onProcess() - process request event handler.
toString() - while not part of the Control interface, by convention toString() is used to render the HTML display.

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:

public class SimpleCallback extends Page {

    /**
     * @see Page#onInit()
     */
    public void onInit() {
        ActionLink clickLink = new ActionLink("clickLink");
        clickLink.setListener(this, "onClick");
        addControl(clickLink);    
    }
    
    public boolean onClick() {
        System.out.println("onClick invoked");
        return true;
    }
}

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. This execution logic is illustrated in the Page Execution Activity Diagram.

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

Control classes are defined in the package net.sf.click.control, with most controls mapping to a HTML element. The control package 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:

/click-control.properties

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

# Click Control messages
calendar-image-title=Calendar
creditcard-number-error={0} is invalid
date-format-error={0} is invalid. Date format is {1}
double-format-error={0} must be a number value
email-format-error={0} is invalid, email format is user@hostname
errors-header=
errors-prefix=
errors-suffix=
errors-footer=
field-maxlength-error={0} must be no longer than {1} characers
field-minlength-error={0} must be at least {1} characters
field-required-error=You must enter a value for {0}
file-required-error=You must enter a filename for {0}
integer-format-error={0} must be a number value
label-required-prefix=
label-required-suffix=<font color="red">*</font>
not-checked-error=You must select {0}
number-maxvalue-error={0} must not be larger than {1}
number-minvalue-error={0} must not be smaller than {1}
select-error=You must select a value for {0} 

# Message displayed when a error occurs when the application is in "production" mode
production-error-message=<div id='errorReport' class='errorReport'>
   The application encountered an unexpected error.</div>

The errors-header, errors-prefix, errors-suffix and errors-footer act like their equivalent Struts values and will format form validation error messages in HTML list. For example to render error messages as red list items:

errors-header=<ul>
errors-prefix=<li><font color="red">
errors-suffix=</font></li>
errors-footer=</ul>

The Field class provides a number of methods for gettting localized strings and formatting messages:

getMessage(String) - return the localized string
getMessage(String, Object) - return the string formatted with the given object
getMessage(String, Object[]) - return the localized string formatted with the given array of objects

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