§Handling form submission
§Defining a form
The play.data
package contains several helpers to handle HTTP form data submission and validation. The easiest way to handle a form submission is to define a play.data.Form
that wraps an existing class:
public class User {
public String email;
public String password;
}
Form<User> userForm = Form.form(User.class);
Note: The underlying binding is done using Spring data binder.
This form can generate a User
result value from HashMap<String,String>
data:
Map<String,String> anyData = new HashMap();
anyData.put("email", "[email protected]");
anyData.put("password", "secret");
User user = userForm.bind(anyData).get();
If you have a request available in the scope, you can bind directly from the request content:
User user = userForm.bindFromRequest().get();
§Defining constraints
You can define additional constraints that will be checked during the binding phase using JSR-303 (Bean Validation) annotations:
public class User {
@Required
public String email;
public String password;
}
Tip: The
play.data.validation.Constraints
class contains several built-in validation annotations.
You can also define an ad-hoc validation by adding a validate
method to your top object:
public class User {
@Constraints.Required
public String email;
public String password;
public String validate() {
if (authenticate(email, password) == null) {
return "Invalid email or password";
}
return null;
}
}
The message returned in the above example will become a global error.
The validate
-method can return the following types: String
, List<ValidationError>
or Map<String,List<ValidationError>>
validate
method is called after checking annotation-based constraints and only if they pass. If validation passes you must return null
. Returning any non-null
value (empty string or empty list) is treated as failed validation.
List<ValidationError>
may be useful when you have additional validations for fields. For example:
public List<ValidationError> validate() {
List<ValidationError> errors = new ArrayList<ValidationError>();
if (User.byEmail(email) != null) {
errors.add(new ValidationError("email", "This e-mail is already registered."));
}
return errors.isEmpty() ? null : errors;
}
Using Map<String,List<ValidationError>>
is similar to List<ValidationError>
where map’s keys are error codes similar to email
in the example above.
§Handling binding failure
Of course if you can define constraints, then you need to be able to handle the binding errors.
if (userForm.hasErrors()) {
return badRequest(views.html.form.render(userForm));
} else {
User user = userForm.get();
return ok("Got user " + user);
}
Typically, as shown above, the form simply gets passed to a template. Global errors can be rendered in the following way:
@if(form.hasGlobalErrors) {
<p class="error">
@form.globalError.message
</p>
}
Errors for a particular field can be rendered in the following manner:
@for(error <- form("email").errors) {
<p>@error.message</p>
}
§Filling a form with initial default values
Sometimes you’ll want to fill a form with existing values, typically for editing:
userForm = userForm.fill(new User("[email protected]", "secret"));
Tip:
Form
objects are immutable - calls to methods likebind()
andfill()
will return a new object filled with the new data.
§Handling a form that is not related to a Model
You can use a DynamicForm
if you need to retrieve data from an html form that is not related to a Model
:
public static Result hello() {
DynamicForm requestData = Form.form().bindFromRequest();
String firstname = requestData.get("firstname");
String lastname = requestData.get("lastname");
return ok("Hello " + firstname + " " + lastname);
}
§Register a custom DataBinder
In case you want to define a mapping from a custom object to a form field string and vice versa you need to register a new Formatter for this object.
For an object like JodaTime’s LocalTime
it could look like this:
Formatters.register(LocalTime.class, new SimpleFormatter<LocalTime>() {
private Pattern timePattern = Pattern.compile(
"([012]?\\d)(?:[\\s:\\._\\-]+([0-5]\\d))?"
);
@Override
public LocalTime parse(String input, Locale l) throws ParseException {
Matcher m = timePattern.matcher(input);
if (!m.find()) throw new ParseException("No valid Input", 0);
int hour = Integer.valueOf(m.group(1));
int min = m.group(2) == null ? 0 : Integer.valueOf(m.group(2));
return new LocalTime(hour, min);
}
@Override
public String print(LocalTime localTime, Locale l) {
return localTime.toString("HH:mm");
}
});
When the binding fails an array of errors keys is created, the first one defined in the messages file will be used. This array will generally contain:
["error.invalid.<fieldName>", "error.invalid.<type>", "error.invalid"]
The errors keys are created by Spring DefaultMessageCodesResolver, the root “typeMismatch” is replaced by “error.invalid”.