Documentation

You are viewing the documentation for the 2.4.x release series. The latest stable release series is 3.0.x.

§Custom 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">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

§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 {
  import views.html.helper.FieldConstructor
  implicit val myFields = FieldConstructor(html.myFieldConstructorTemplate.f)
}

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

@import MyHelpers._
@helper.inputText(myForm("username"))

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

You can also set an implicit value for your FieldConstructor inline:

@implicitField = @{ helper.FieldConstructor(myFieldConstructorTemplate.f) }
@helper.inputText(myForm("username"))

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.