Forms #

Introduction #

Forms are generally how user data flows into and out of your application. Typically, the forms that you present to your users are representative of your domain models and data transfer objects.

Usually, processing data submitted by users entails the following steps:

Getting all the form parameters from the request
Creating an instance of your Data Transfer Object (DTO)
Copying all of the form parameters from the request to the DTO
Performing validations (and notifying the user of any errors)
Finally, using the data

That’s quite a lot! This process can be tedious and error prone, but luckily working with forms in Diego only entails a few easy steps.

Step 1: Define a model #

First, we define a model. A model is any domain object with properties (and optional constraints). For our example, we will be working with the following model:

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.AssertTrue;
import org.hibernate.validator.constraints.Length;

class SignupForm {
    @NotBlank 
    private String email;
    @NotBlank 
    @Length(min = 8, message = 'must be at least 10 characters') 
    private String password;
    @NotBlank 
    private String passwordConfirm;
    
    // Getters and setters - VERY IMPORTANT
}

In Groovy, fields declared without the `public` modifier are are given getters and setters automatically. If you prefer to use Java, you'll have to implement these according to JavaBean Conventions. This is essential for the next step.

Note the special @NotBlank annotation. This annotation serves as a constraint and is part of the wider Jakarta EE Validation package. In our example, this constraint ensures that the email and password fields do not contain null values or empty strings.

Step 2: Parse the request #

Diego provides the diego.validation.Forms utility class to parse request bodies and request parameters and perform validation using the Hibernate Validator.

The following example shows how this is done using the Express-style routing:

app.post("/login", (ctx) -> {
    SignupForm form = ctx.form(SignupForm.class); // Parse the request using the SignupForm class as a schema
    // Use the data in the form...
})

For controllers, you use the @Form annotation next to your method parameter:

@POST
public void login(@Form SignupForm form) { ... }

Here, the request is parsed and a SignupForm object is returned. This object is populated according to the data in the request.

If there is a parsing error, Diego will throw a ValidationException . This is handled by the validationFailed() method in your WebMvcConfiguration implementation.

The Context#form(Class) method works for both JSON requests and regular HTML form submissions (URL encoded and multipart). For JSON requests, the shape of the JSON object must match the shape of the form classl, but for HTML forms, the form parameters must map to properties of the model according to the established naming conventions.

Step 3: Use the data #

You’re done! Use the data in your SignupForm to complete you business logic.

Custom validation #

There are several ways you can perform custom validation on your models:

Option1: Implement the `Validatable` interface #

Make your forms implement the Validatable interface. This will give you access to a special method named fail() that will throw ValidationExceptions based on your custom logic:

class SignupForm implements Validatable {
    // Fields, getters and setters
    
    @Override
    public void validate() {
        if(password != passwordConfirm) fail("Password and confirmation do not match.")
    }
}

Option 2: Use the JSR 303 spec #

The JSR 303 spec features @AssertTrue and @AssertFalse annotations that can be leveraged to perform some custom validation logic.

Let’s use them to add some extra validation logic to our signup form:

import jakarta.validation.constraints.AssertTrue;

/* Fields, getters and setters */

@AssertTrue(message = "Password and confirmation do not match.")
private boolean getPasswordMatch() {
    return password == passwordConfirm;
}

Note that the return type is boolean not Boolean and the method name begins with “is” or “get”. This is to align with the JavaBeans specification (Section 8.3.2).

Option 3: Custom constraints #

You can create a custom validation constraints by following this guide.

Validation Groups #

The form validation framework also support Hibernate Validation Groups. These can be useful when you want to reuse a form for multiple routes, but validate different parts of the form depending on the data that needs to be captured.

For Controller methods, the @Form annotation has the validationGroups property where you can specify the validation groups. For Express-style routes, the Context#form method has an overloaded option for you to specify validation groups.

File uploads and forms #

You can include file uploads in your forms as well. Simply create a diego.web.Http.FileUpload field that also adheres to the naming conventions.

class ProfileForm {
    @Required @Upload(mimeType = "image/*") private FileUpload profilePic;
}

Here, we use the diego.validation.constraints.Required and diego.validation.constraints.Upload constraints to ensure that the profilePic field is required and is an image type.

Handling Validation Failures #

How your application responds to validation failures can be configured by overriding the validationFailed() method in your WebMvcConfiguration.

By default, if the request has an X-Requested-With header with a value of XMLHttpRequest or there is no Referer header, then the framework will return an HTTP 422 response with the following JSON body:

{
    [field name]: ["Violation message 1", "Violation message n"]
}

If the form submission came from a traditional HTML form, then the framework will redirect the user back to the form page with a flash error message and the form parameters from the form submission. You can learn more about flash messages and template variables in the Templates chapter.

Naming conventions for HTML forms #

When submitting data using regular HTML forms, the Context#form method uses the built-in data mapper to inspect the form parameters and map them to properties on the supplied class. This mapping will only be successful if the form parameter names adhere to certain conventions.

Regular properties #

<!-- Set the fullName attribute to the fullName property. Use camelCase -->
<input type="text" name="fullName" />

Lists #

<!-- Use square bracket notation for collection items -->
<input type="checkbox" name="interests[]" value="swimming" />
<input type="checkbox" name="interests[]" value="reading" />
<input type="checkbox" name="interests[]" value="biking" />

Nested objects #

<!-- Use dot notation to map to fields in nested objects. -->
<input type="text" name="address.street" />    
<input type="text" name="address.town" />

Nested Lists #

<!-- Use a combination of dot notation and square brackets to map to nested lists. -->
<input type="checkbox" name="building.features[]" value="balcony" />
<input type="checkbox" name="building.features[]" value="pool" />
<input type="checkbox" name="building.features[]" value="office" />

Limitations #

Presently, the data binder cannot represent lists of objects or nested lists of objects.

<input type="text" name="customers[0].name" /> <!-- This will throw an error. -->

This limitations may be addressed in a future release depending on identified use cases.

This limitation does not apply when using JSON requests.