It is a common requirement to restrict the form data entered by users with one rule or another. For example, checking to ensure that the name field data does not contain digits, the age is less than 18 years, if an expired card is being used to complete the transaction, and so on. Play provides default constraints, which can be used to validate the field data. Using these constraints, we can define a form easily as well as restrict the field data in some ways, as shown here:

mapping(
    "userName" -> nonEmptyText,
    "emailId" -> email,
    "password" -> nonEmptyText(minLength=8,maxLength=15)
    )

The default constraints can be broadly classified into two categories: the ones that define a simple Mapping[T], and the ones that consume Mapping[T] and result in Mapping[KT], as shown here:

mapping(
    "userName" -> nonEmptyText,
    "interests" -> list(nonEmptyText)
    )

In this example, Mapping[String] is transformed into Mapping[List[String]].

There are two other constraints that do not fall into either category. They are ignored and checked.

The ignored constraint can be used when we do need mapping from the user data for that field. For example, fields such as login time or logout time should be filled in by an application and not the user. We could use mapping in this way:

mapping(
    "loginId" -> email,
    "password" -> nonEmptyText,
    "loginTime" -> ignored(System.currentTimeMillis())
    )

The checked constraint can be used when we need to ensure that a particular checkbox has been selected by the user. For example, accepting terms and conditions of the organization, and so on, in signupForm:

mapping(
    "loginId" -> email,
    "password" -> nonEmptyText,
    "agree" -> checked("agreeTerms")
    )

The constraints of the first category are listed in this table:

This table lists the constraints included in the second category:

In addition to these field constraints, we can also define ad hoc and/or custom constraints on a field using the verifying method.

An instance might arise where an application lets users choose their userName, which can only consist of numbers and alphabet. To ensure that this rule is not broken, we can define an ad hoc constraint:

mapping(
"userName" ->  nonEmptyText(minLength=5) verifying pattern("""[A-Za-z0-9]*""".r, error = "only digits and alphabet are allowed in userName"
)

Or, we can define a custom constraint using the Constraint case class:

val validUserName = """[A-Za-z0-9]*""".r
val userNameCheckConstraint: Constraint[String] = Constraint("contraints.userName")({
    text =>
      val error = text match {
        case validUserName() => Nil
        case _ => Seq(ValidationError("only digits and alphabet are allowed in userName"))
      }
      if (error.isEmpty) Valid else Invalid(error)
  })

val userNameCheck: Mapping[String] = nonEmptyText(minLength = 5).verifying(passwordCheckConstraint)

We can use this in a form definition:

mapping(
"userName" ->  userNameCheck
)

Note that nonEmpty, minLength, maxLength, min, max, pattern, and email are predefined constraints. They are defined in the play.api.data.validation trait. The available constraints can be used as references when defining custom constraints.

What happens when one or more constraints has been broken in the form that has been submitted? The bindFromRequest method creates a form with errors, which we earlier referred to as formWithErrors.

For each violated constraint, an error is saved. An error is represented by FormError, defined as follows:

case class FormError(key: String, messages: Seq[String], args: Seq[Any] = Nil)

The key is the name of the field where a constraint was broken, message is its corresponding error message and args are the arguments, if any, used in the message. In the case of constraints defined in multiple fields, the key is an empty string and such errors are termed globalErrors.

The errors in a form for a specific field can be accessed through the errors method, defined as:

def errors(key: String): Seq[FormError] = errors.filter(_.key == key)

For example:

registerForm.errors("userName")

Alternatively, to access only the first error, we can use the error method instead. It is defined as follows:

def error(key: String): Option[FormError] = errors.find(_.key == key)

Now, how do we access globalErrors (that is, an error from a constraint defined in multiple fields together)?

We can use the form's globalErrors method, which is defined as follows:

def globalErrors: Seq[FormError] = errors.filter(_.key.isEmpty)

If we want just the first globalError method, we can use the globalError method. It is defined as follows:

def globalError: Option[FormError] = globalErrors.headOption

When we use the form-field helpers, field-specific errors are mapped to the field and displayed if they're present. However, if we are not using the form helpers, we will need to display the errors, as shown here:

<label>Password
  <input type="password" name="password" tabindex="2" required="required">
</label>
@registerForm.errors("password").map{ er => <p>@er.message</p>}

The globalErrors method needs to be added to the view explicitly, as shown here:

@registerForm.globalErrors.map{ er => <p>@er.message</p>}

In the previous example, we used the HTML code for the form fields, but we can also do this using the form field helpers provided by Play. We can update our view,@import models.Credentials, as shown here:

@(registerForm: Form[Credentials])(implicit flash: Flash) 
 
@main("Register") { 
  @helper.form(action = routes.Application.newUser, 'enctype -> "multipart/form-data") { 
    @registerForm.globalErrors.map { error => 
      <p class="error"> 
        @error.message 
      </p> 
    } 
        
    @helper.inputText(registerForm("loginId"), 'tabindex -> "1", '_label -> "Email ID", 
    'type -> "email", 'required -> "required", '_help -> "A valid email Id") 

    @helper.inputPassword(registerForm("password"), 'tabindex -> "2", 
    'required -> "required", '_help -> "preferable min.length=8") 

    <input type="submit" value="Register"> 
    <hr/> 
    Existing User?<a href="@routes.Application.login()">Login</a> 
    } 
}

Let's see how this works. The helper inputText is a view defined as follows:

@(field: play.api.data.Field, args: (Symbol,Any)*)(implicit handler: FieldConstructor, lang: play.api.i18n.Lang)

@inputType = @{ args.toMap.get('type).map(_.toString).getOrElse("text") }

@input(field, args.filter(_._1 != 'type):_*) { (id, name, value, htmlArgs) =>
    <input type="@inputType" id="@id" name="@name" value="@value" @toHtmlArgs(htmlArgs)/>
}

It uses the input helper internally, which is also a view and can be defined as follows:

@(field: play.api.data.Field, args: (Symbol, Any)* )(inputDef: (String, String, Option[String], Map[Symbol,Any]) => Html)(implicit handler: FieldConstructor, lang: play.api.i18n.Lang)

@id = @{ args.toMap.get('id).map(_.toString).getOrElse(field.id) }

@handler(
    FieldElements(
        id,
        field,
        inputDef(id, field.name, field.value, args.filter(arg => !arg._1.name.startsWith("_") && arg._1 != 'id).toMap),
        args.toMap,
        lang
    )
)

Both the form field helpers use an implicit FieldConstructor. This field constructor is responsible for the HTML rendered. By default, defaultFieldConstructor is forwarded. It is defined as follows:

@(elements: FieldElements)

<dl class="@elements.args.get('_class) @if(elements.hasErrors) {error}" id="@elements.args.get('_id).getOrElse(elements.id + "_field")">
    @if(elements.hasName) {
    <dt>@elements.name(elements.lang)</dt>
    } else {
    <dt><label for="@elements.id">@elements.label(elements.lang)</label></dt>
    }
    <dd>@elements.input</dd>
    @elements.errors(elements.lang).map { error =>
        <dd class="error">@error</dd>
    }
    @elements.infos(elements.lang).map { info =>
        <dd class="info">@info</dd>
    }
</dl>

So, if we wish to change the layouts for our form fields, we can define a custom FieldConstructor and pass it to the form field helpers, as shown here:

@input(contactForm("name"), '_label -> "Name", '_class -> "form-group", '_size -> "100") { (id, name, value, htmlArgs) =>
  <input class="form-control" type="text" id="@id" name="@name" value="@value" @toHtmlArgs(htmlArgs)/>
}

This section attempts to explain how the form helper works; for more examples, refer to the Play Framework documentation at http://www.playframework.com/documentation/2.3.x/ScalaForms.