§Using the form template helpers

Play provides several helpers for rendering form fields in HTML templates.

§Create a <form> tag

The first thing is to be able to create the <form> tag. It is a pretty simple helper that has no more value than automatically setting the action and method tag parameters according to the reverse route you pass in:

@helper.form(action = routes.Application.submit) {
    
}

You can also pass an extra set of parameters that will be added to the generated Html:

@helper.form(action = routes.Application.submit, 'id -> "myForm") {
    
}

§Rendering an <input> element

You can find several input helpers in the views.html.helper package. You feed them with a form field, and they display the corresponding HTML input, setting the value, constraints and errors:

@(myForm: Form[User])

@helper.form(action = routes.Application.submit) {
    
    @helper.inputText(myForm("username"))
    
    @helper.inputPassword(myForm("password"))
    
}

As for the form helper, you can specify an extra set of parameters that will be added to the generated Html:

@helper.inputText(myForm("username"), 'id -> "username", 'size -> 30)

Note: All extra parameters will be added to the generated Html, unless they start with the _ character. Arguments starting with _ are reserved for field constructor arguments (we will see that shortly).

§Handling HTML input creation yourself

There is also a more generic input helper that lets you code the desired HTML result:

@helper.input(myForm("username")) { (id, name, value, args) =>
    <input type="date" name="@name" id="@id" @toHtmlArgs(args)>
} 

§Field constructors

A field rendering is not only composed of the <input> tag, but it also needs a <label> and possibly other tags used by your CSS framework to decorate the field.

All input helpers take an implicit FieldConstructor that handles this part. The default one (used if there are no other field constructors available in the scope), generates HTML like:

<dl class="error" id="username_field">
    <dt><label for="username"><label>Username:</label></dt>
    <dd><input type="text" name="username" id="username" value=""></dd>
    <dd class="error">This field is required!</dd>
    <dd class="error">Another error</dd>
    <dd class="info">Required</dd>
    <dd class="info">Another constraint</dd>
</dl>

This default field constructor supports additional options you can pass in the input helper arguments:

'_label -> "Custom label"
'_id -> "idForTheTopDlElement"
'_help -> "Custom help"
'_showConstraints -> false
'_error -> "Force an error"
'_showErrors -> false

§Twitter bootstrap field constructor

There is also another built-in field constructor that can be used with TwitterBootstrap 1.4. (Note: 2.0.2 will support LESS 1.3 and Bootstrap 2.0.)

To use it, just import it in the current scope:

@import helper.twitterBootstrap._

It generates Html like:

<div class="clearfix error" id="username_field">
    <label for="username">Username:</label>
    <div class="input">
        <input type="text" name="username" id="username" value="">
        <span class="help-inline">This field is required!, Another error</span>
        <span class="help-block">Required, Another constraint</span> 
    </div>
</div>

It supports the same set of options as the default field constructor (see below).

§Writing your own field constructor

Often you will need to write your own field constructor. Start by writing a template like:

@(elements: helper.FieldElements)

<div class="@if(elements.hasErrors) {error}">
    <label for="@elements.id">@elements.label</label>
    <div class="input">
        @elements.input
        <span class="errors">@elements.errors.mkString(", ")</span>
        <span class="help">@elements.infos.mkString(", ")</span> 
    </div>
</div>

Note: This is just a sample. You can make it as complicated as you need. You also have access to the original field using @elements.field.

Now create a FieldConstructor using this template function:

object MyHelpers {
    
  implicit val myFields = FieldConstructor(myFieldConstructorTemplate.f)    
    
}

And to make the form helpers use it, just import it in your templates:

@import MyHelpers._

@inputText(myForm("username"))

It will then use your field constructor to render the input text.

Note: You can also set an implicit value for your FieldConstructor inline in your template this way:

@implicitField = @{ FieldConstructor(myFieldConstructorTemplate.f) }

@inputText(myForm("username"))

§Handling repeated values

The last helper makes it easier to generate inputs for repeated values. Let’s say you have this kind of form definition:

val myForm = Form(
  tuple(
    "name" -> text,
    "emails" -> list(email)
  )
)

Now you have to generate as many inputs for the emails field as the form contains. Just use the repeat helper for that:

@inputText(myForm("name"))

@repeat(myForm("emails"), min = 1) { emailField =>
    
    @inputText(emailField)
    
}

The min parameter allows you to display a minimum number of fields even if the corresponding form data are empty.

Next: Working with JSON

Found an error in this documentation? The source code for this page can be found here. After reading the documentation guidelines, please feel free to contribute a pull request. Have questions or advice to share? Go to our community forums to start a conversation with the community.