Forms
Civilians form library helps to process HTML forms.
Introduction
Processing HTML forms in a classic roundtrip application typically follows this schema:
- The browser requests a HTML page which contains a form.
- The server returns the page. The form may or may not be populated with initial data.
- The browser submits the form.
- The server evaluates the submitted form. If the input has errors, it jumps back to step 2) and adds error messages to the page.
If the input has no errors, the server sends an appropriate response or redirects to another page.
Using only low-level APIs such as HttpServletRequest and HttpServletResponse makes form processing a hard job.
Type conversion of the data which is presented in the form is especially tedious:
- From the applications perspective, form values can have any (simple) type: strings, numbers, dates, discrete values (to select from), etc.
- Values must be converted to strings when rendered in the output.
- Values must be parsed from string request parameters when a form is submitted.
- In a multi-locale application conversion of values must obey the locale of request or response.
Controller method parameters
Parameters of controller methods build a simple way
how to extract values of a submitted form from the request.
Use the
@Parameter to read the value of a single form control
or
@BeanParam to read values from multiple controls in the form of a Java bean.
@Post public void processForm(@BeanParam Order order)
{ ...
The
Inject sample demonstrates this technique.
Controller method parameters take care of type conversion from request Strings to the target type.
But they can't handle conversion errors when string values of the request are converted to other types.
Invalid input will therefore result in response with status 400 (bad request).
A more elaborate and error tolerant way to process forms is to use Civilians form library:
Civilians form library allows a higher-level approach to form processing:
The
Form class models a HTML form and consists of a list of form controls.
For every form element presented in the HTML page you add a control to the form.
Control implementations exist for all HTML(5) form elements and provides accessors for the HTML attributes
used in these elements.
Controls possess a value whose type is not restricted to strings. For example DateField and IntField are two
Control implementations which have Date and Integer values. Therefore setting or getting values from a control does not need any
type conversion from your side.
Controls know how to write themselves to a response.
Sending a control to TemplateWriter.print(Object)
will print the HTML code for the control. Of course a template is still needed to print the overall form layout.
Evaluating a submitted form is equally easy. If a form object is asked to read its values from a Request,
all form controls will update their values from the request. If a submitted value is invalid (e.g. because it violates
the format prescribed by the control type), the control status reflects this.
Like controllers form objects are constructed for a single request. Please study the
form sample for further details.