Provides an abstract form Field control. Field controls are contained by the {@link Form} control which will orchestrate the processing andrendering of the contained fields. All Form field controls must extend this abstract class.
Field Processing
Post Requests
When processing POST requests forms typically invoke the {@link #onProcess()}method on all its fields. The Field
onProcess() method is used to bind the fields request value, validate the submission and invoke any control listener method. If the
onProcess() method returns true the form will continue processing fields, otherwise the form will abort further processing.
The body of the Field
onProcess() method is detailed below.
public boolean onProcess() { bindRequestValue(); if (getValidate()) { validate(); } registerActionEvent(); return true; } The Field methods called by
onProcess() include:
- {@link #bindRequestValue()}
- This method will bind the HTTP request value to the Field's value.
- {@link #getValidate()}
- This method will return true if the Field should validate itself. This value is generally inherited from the parent Form, however the Field can override this value and specify whether it should be validated.
- {@link #validate()}
- This method will validate the submitted Field value. If the submitted value is not valid this method should set the Field {@link #error} property,which can be rendered by the Form.
- {@link #dispatchActionEvent()}
- This method will register any Control action listener method which has be defined for the Field.
Field subclasses generally only have to override the
validate() method, and possibly the
bindRequestValue() method, to provide their own behaviour.
Get Requests
When processing GET requests a Page's Form will typically perform no processing and simply render itself and its Fields.
Rendering
Field subclasses must override the {@link #render(org.apache.click.util.HtmlStringBuffer)}method to enable themselves to be rendered as HTML. With the increasing use of AJAX, Fields should render themselves as valid XHTML, so that they may be parsed correctly and used as the
innerHtml in the DOM.
When a Form object renders a Field using autolayout, it renders the Field in a table row using the Field's {@link #label} attribute, its{@link #error} attribute if defined, and the Fields{@link #render(org.apache.click.util.HtmlStringBuffer)} method.
To assist with rendering valid HTML Field subclasses can use the {@link org.apache.click.util.HtmlStringBuffer} class.
Message Resources
Fields support a hierarchy of resource bundles for displaying validation error messages and display messages. These localized messages can be accessed through the methods:
- {@link #getMessage(String)}
- {@link #getMessage(String,Object)}
- {@link #getMessage(String,Object[])}
- {@link #getMessages()}
- {@link #setErrorMessage(String)}
- {@link #setErrorMessage(String,Object)}
Fields automatically pick up localized messages where applicable. Please see the following methods on how to customize these messages:
- {@link #getLabel()}
- {@link #getTitle()}
- {@link #getHelp()}
- {@link #setErrorMessage(String)}
- {@link #setErrorMessage(String,Object)}
The order in which localized messages resolve are:
- Page scope messages
- Message lookups are first resolved to the Pages message bundle if it exists. For example a Login page may define the message properties:
/com/mycorp/page/Login.properties
If you want messages to be used only for a specific 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 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
You can modify these properties by copying this file into your applications root class path and editing these properties. Note when customizing the message properties you must include all the properties, not just the ones you want to override.