HOWTOs

Create a required input

The following code snippet creates a required input of type string whose length must be between 6 and 12 characters long. A required input is valid when it has a value and its value satisfies all criteria.

input(stringType(), "username", length(6, 12));

Create an optional input

An input can be flagged as optional by invoking the optional() method. An optional input is valid either if it has no value, or if its value satisfies all criteria. In this case, the input is valid if it is left blank or if its length is at least 8 characters long.

input(stringType(), "address", minLength(8)).optional();

Create an input with a int value

This creates a required input whose value must be an integer. If the value provided is not an integer or if it is less than 0, the input is considered invalid.

input(intType(), "positive", min(0));

Specify a custom error message

Each criterion has a default error message that describes a validation error. The default message can be overridden where necessary by invoking the setOnError(...) method. The JSP page can display the error message by invoking the getOnError() method. Note that if the input validates successfully getOnError() returns an empty string, eliminating the need for checking whether the input is valid.

input(stringType(), "url", startsWith("http"))
	.setOnError("URL must start with http");

Using criteria that represent logical operators

Criteria can be combined using and(Criterion...c) or or(Criteria...c) criteria. Both expect at least two arguments otherwise an exception will be thrown.

In the first example, the input must either start with 'http' or with 'www.' for the input to validate successfully. The second specifies that the value must start with 'http' and be at least 10 characters long.

// using 'or'
input(stringType(), "url", or(startsWith("http"), startsWith("www.")));

// using 'and'
input(stringType(), "url", and(startsWith("http"), minLength(10)));

Create a single value checkbox

A single value checkbox has a single value that is either checked or unchecked. Since an unchecked checkbox does not submit a value with the request (that is, its value is null), it is always treated as an optional input.

checkbox(stringType(), "receiveNewsletter");

// jsp
<input type="checkbox" name="receiveNewsletter"> Subscribe to newsletter

Create a multi value checkbox

Unlike a single value checkbox, a checkbox with multiple values can be both, required or optional. The code snippet below creates a checkbox named 'toppings' that will only validate successfully if it has one of the values passed to the accept(...) criterion. Since this is a required input, at least one checkbox must be checked. If nothing is checked the input is deemed invalid.

multiCheckbox(stringType(), "toppings", accept("peppers", "olives", "ham"));

// jsp
<input type="checkbox" name="toppings" value="peppers"> Peppers
<input type="checkbox" name="toppings" value="olives"> Olives
<input type="checkbox" name="toppings" value="ham"> Ham

Create a select input

The following example creates a select input. This input supports only a single selection. In this example, the default option 'Select a country' has a value that is just an empty string. Therefore, if no selection is made validation will fail since this is a required input.

select(stringType(), "country");

// jsp
<select name="country">
  <option value="">Select a country</option>
  <option value="Spain"></Spain>
  <option value="Italy">Italy</option>
  <option value="France">France</option>
</select>

Create a multiple select

A multiple select input allows several selections to be submitted at once. This code snippet is an example of a required multiple select. It requires at least one selection to validate successfully.

multiSelect(stringType(), "colours");

// jsp
<select name="colours" multiple size="3">
  <option value="Red">Red</option>
  <option value="Green">Green</option>
  <option value="Blue">Blue</option>
</select>

Create a radio button

This is an example of a radio button with two values. The accept(...) criterion restricts the choices to 'yes' and 'no'. If any other value (or no value at all) is submitted validation will fail.

radio(stringType(), "acceptTerms", accept("yes", "no"));

// jsp
<input type="radio" name="acceptTerms" value="yes"> Yes
<input type="radio" name="acceptTerms" value="no"> No

Create an input group

An input group provides a convenient way of grouping related inputs together. This allows a large form to be split into several groups. For examples, a long application form can be split into subsections that group together contact information, bank account details, etc. In the following example, both groups are required. Therefore, all required inputs within the group must have valid values for the form to validate successfully.

Group contactDetails = requiredGroup("contactDetails");
group.input(stringType(), "address");
group.input(stringType(), "phoneNumber");
group.input(stringType(), "emailAddress").optional();

Group accountInfo = requiredGroup("accountInfo");
group.input(stringType(), "bankName");
group.input(intType(), "accountNumber");
group.input(intType(), "branchCode");

// other subsections ...

Create an optional input group

An optional group has different validation rules from a required group. An optional group is considered valid if all of its inputs are blank, regardless of whether the inputs are optional or required. However, if at least one input within the group has a value, then all inputs are validated as usual. In other words, it follows a 'all or nothing' principle.

The following code snippet is an example of an optional group. If the weight is entered then the group will only validate successfully if the units are also selected, and vice versa. However the group will also validate successfully if neither weight nor units are provided.

Group group = optionalGroup("personalInfo");
group.input(intType(), "weight");
group.select(stringType(), "units", accept("kg", "lb"));