Documentation

You are viewing the documentation for the 2.4.0-M2 development release. The latest stable release series is 3.0.x.

§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 not-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 like bind() and fill() will return a new object filled with the new data.

You can use a DynamicForm if you need to retrieve data from an html form that is not related to a Model :

public 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 fail 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”.

Next: Using the form template helpers