# 7. Validation

Grails validation capability is built on Spring's Validator API and data binding capabilities. However Grails takes this further and provides a unified way to define validation "constraints" with its constraints mechanism.

Constraints in Grails are a way to declaratively specify validation rules. Most commonly they are applied to domain classes, however URL Mappings and Command Objects also support constraints.

## 7.1 Declaring Constraints

Within a domain class a constraints are defined with the constraints property that is assigned a code block:

    class User {
        String login
        String password
        String email
        Integer age    static constraints = {
    	  …
        }
    }

You then use method calls that match the property name for which the constraint applies in combination with named parameters to specify constraints:

    class User {
        ...    static constraints = {
            login(size:5..15, blank:false, unique:true)
            password(size:5..15, blank:false)
            email(email:true, blank:false)
            age(min:18, nullable:false)
        }
    }

In this example we've declared that the `login` property must be between 5 and 15 characters long, it cannot be blank and must be unique. We've all applied other constraints to the `password`, `email` and `age` properties.

> A complete reference for the available constraints can be found on the reference guide

## 7.2 Validating Constraints

#### Validation Basics

To validate a domain class you can call the validate method on any instance:

    def user =  new User(params)if(user.validate()) {
        // do something with user
    }
    else {
        user.errors.allErrors.each {
            println it
        }
    }

The `errors` property on domain classes is an instance of the Spring Errors interface. The `Errors` interface provides methods to navigate the validation errors and also retrieve the original values.

#### Validation Phases

Within Grails there are essentially 2 phases of validation, the first phase is data binding which occurs when you bind request parameters onto an instance such as:

    def user = new User(params)

At this point you may already have errors in the `errors` property due to type conversion (such as converting Strings to Dates). You can check these and obtain the original input value using the `Errors` API:

    if(user.hasErrors()) {
    	if(user.errors.hasFieldErrors("login")) {
    		println user.errors.getFieldError("login").rejectedValue
    	}
    }

The second phase of validation happens when you call validate or save. This is when Grails will validate the bound values againts the constraints you defined. For example, by default the persistent save method calls `validate` before executing hence allowing you to write code like:

    if(user.save()) {
        return user
    }
    else {
        user.errors.allErrors.each {
            println it
        }
    }

## 7.3 Validation on the Client

#### Displaying Errors

Typically if you get a validation error you want to redirect back to the view for rendering. Once there you need some way of rendering errors. Grails supports a rich set of tags for dealing with errors. If you simply want to render the errors as a list you can use renderErrors:

    <g:renderErrors bean="${user}" />

If you need more control you can use hasErrors and eachError:

    <g:hasErrors bean="${user}">
      <ul>
       <g:eachError var="err" bean="${user}">
           <li>${err}</li>
       </g:eachError>
      </ul>
    </g:hasErrors>

#### Highlighting Errors

It is often useful to highlight using a red box or some indicator when a field has been incorrectly input. This can also be done with the hasErrors by invoking it as a method. For example:

    <div class='value ${hasErrors(bean:user,field:'login','errors')}'>
       <input type="text" name="login" value="${fieldValue(bean:user,field:'login')}"/>
    </div>

What this code does is check if the `login` field of the `user` bean has any errors and if it does adds an `errors` CSS class to the `div` thus allowing you to use CSS rules to highlight the `div`.

#### Retrieving Input Values

Each error is actually an instance of the FieldError class in Spring, which retains the original input value within it. This is useful as you can use the error object to restore the value input by the user using the fieldValue tag:

    <input type="text" name="login" value="${fieldValue(bean:user,field:'login')}"/>

This code will look if there is an existing `FieldError` in the `User` bean and if there is obtain the originally input value for the `login` field.

## 7.4 Validation and Internationalization

Another important thing to note about errors in Grails is that the messages that the errors display are not hard coded anywhere. The FieldError class in Spring essentially resolves messages from message bundles using Grails' i18n support.

#### Constraints and Message Codes

The codes themselves are dictated by a convention. For example consider the constraints we looked at earlier:

    package com.mycompany.myappclass User {
        ...    static constraints = {
            login(size:5..15, blank:false, unique:true)
            password(size:5..15, blank:false)
            email(email:true, blank:false)
            age(min:18, nullable:false)
        }
    }

If the `blank` constraint was violated Grails will, by convention, look for a message code in the form:

    [Class Name].[Property Name].[Constraint Code]

In the case of the `blank` constraint this would be `user.login.blank` so you would need a message such as the following in your `grails-app/i18n/messages.properties` file:

    user.login.blank=Your login name must be specified!

The class name is looked for both with and without a package, with the packaged version taking precedence. So for example, com.mycompany.myapp.User.login.blank will be used before user.login.blank. This allows for cases where you domain class encounters message code clashes with plugins.

For a reference on what codes are for which constraints refer to the reference guide for each constraint.

#### Displaying Messages

The renderErrors tag will automatically deal with looking up messages for you using the message tag. However, if you need more control of rendering you will need to do this yourself:

    <g:hasErrors bean="${user}">
      <ul>
       <g:eachError var="err" bean="${user}">
           <li><g:message error="${err}" /></li>
       </g:eachError>
      </ul>
    </g:hasErrors>

In this example within the body of the eachError tag we use the message tag in combination with its `error` argument to read the message for the given error.

## 7.5 Validation Non Domain and Command Object Classes

Domain classes and command objects support validation by default. Other classes may be made validateable by defining the static constraints property in the class (as described above) and then telling the framework about them. It is important that the application register the validateable classes with the framework. Simply defining the constraints property is not sufficient.

#### The Validateable Annotation

Classes which define the static constraints property and are marked with the @Validateable annotation may be made validateable by the framework. Consider this example:

    // src/groovy/com/mycompany/myapp/User.groovy
    package com.mycompany.myappimport org.codehaus.groovy.grails.validation.Validateable@Validateable
    class User {
        ...    static constraints = {
            login(size:5..15, blank:false, unique:true)
            password(size:5..15, blank:false)
            email(email:true, blank:false)
            age(min:18, nullable:false)
        }
    }

You need to tell the framework which packages to search for @Validateable classes by assigning a list of Strings to the grails.validateable.packages property in Config.groovy.

    // grails-app/conf/Config.groovy...grails.validateable.packages = ['com.mycompany.dto', 'com.mycompany.util']...

The framework will only search those packages (and child packages of those) for classes marked with @Validateable.

#### Registering Validateable Classes

If a class is not marked with @Validateable, it may still be made validateable by the framework. The steps required to do this are to define the static constraints property in the class (as described above) and then telling the framework about the class by assigning a value to the grails.validateable.classes property in Config.groovy.

    // grails-app/conf/Config.groovy...grails.validateable.classes = [com.mycompany.myapp.User, com.mycompany.dto.Account]...