root
API
Generated with
root/play/play.api/play.api.data/Form

Form

play.api.data.Form
See theForm companion object
case class Form[T](mapping: Mapping[T], data: Map[String, String], errors: Seq[FormError], value: Option[T])

Helper to manage HTML form description, submission and validation.

For example, a form handling a User case class submission:

import play.api.data._
import play.api.data.Forms._
import play.api.data.format.Formats._

val userForm = Form(
 mapping(
   "name" -> of[String],
   "age" -> of[Int],
   "email" -> of[String]
 )(User.apply)(User.unapply)
)

Type parameters

T

the type managed by this form

Value parameters

data

the current form data, used to display the form

errors

the collection of errors associated with this form

mapping

the form mapping, which describes all form fields

value

a concrete value of type T if the form submission was successful

Attributes

Companion
object
Graph
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all

Members list

Value members

Concrete methods

def apply(key: String): Field

Retrieves a field.

Retrieves a field.

For example:

val usernameField = userForm("username")

Value parameters

key

the field name

Attributes

Returns

the field, returned even if the field does not exist

def bind(data: Map[String, String]): Form[T]

Binds data to this form, i.e. handles form submission.

Binds data to this form, i.e. handles form submission.

Value parameters

data

the data to submit

Attributes

Returns

a copy of this form, filled with the new data

def bind(data: JsValue, maxChars: Long): Form[T]

Binds data to this form, i.e. handles form submission.

Binds data to this form, i.e. handles form submission.

Value parameters

data

Json data to submit

maxChars

The maximum number of chars allowed to be used in the intermediate map representation of the JSON. parse.DefaultMaxTextLength is recommended to passed for this parameter.

Attributes

Returns

a copy of this form, filled with the new data

def bind(data: JsValue, maxChars: Long, maxDepth: Int): Form[T]

Binds data to this form, i.e. handles form submission.

Binds data to this form, i.e. handles form submission.

Value parameters

data

Json data to submit

maxChars

The maximum number of chars allowed to be used in the intermediate map representation of the JSON. parse.DefaultMaxTextLength is recommended to passed for this parameter.

maxDepth

The maximum level of nesting for JSON objects and arrays.

Attributes

Returns

a copy of this form, filled with the new data

def bindFromRequest()(implicit request: Request[_], formBinding: FormBinding): Form[T]

Binds request data to this form, i.e. handles form submission.

Binds request data to this form, i.e. handles form submission.

Attributes

Returns

a copy of this form filled with the new data

def bindFromRequest(data: Map[String, Seq[String]]): Form[T]
def discardingErrors: Form[T]

Discards this form’s errors

Discards this form’s errors

Attributes

Returns

a copy of this form without errors

def error(key: String): Option[FormError]

Retrieve the first error for this key.

Retrieve the first error for this key.

Value parameters

key

field name.

Attributes

def errors(key: String): Seq[FormError]

Retrieve all errors for this key.

Retrieve all errors for this key.

Value parameters

key

field name.

Attributes

def errorsAsJson(implicit provider: MessagesProvider): JsValue

Returns the form errors serialized as Json.

Returns the form errors serialized as Json.

Attributes

def fill(value: T): Form[T]

Fills this form with a existing value, used for edit forms.

Fills this form with a existing value, used for edit forms.

Value parameters

value

an existing value of type T, used to fill this form

Attributes

Returns

a copy of this form filled with the new data

def fillAndValidate(value: T): Form[T]

Fills this form with a existing value, and performs a validation.

Fills this form with a existing value, and performs a validation.

Value parameters

value

an existing value of type T, used to fill this form

Attributes

Returns

a copy of this form filled with the new data

def fold[R](hasErrors: Form[T] => R, success: T => R): R

Handles form results. Either the form has errors, or the submission was a success and a concrete value is available.

Handles form results. Either the form has errors, or the submission was a success and a concrete value is available.

For example:

 anyForm.bindFromRequest().fold(
    f => redisplayForm(f),
    t => handleValidFormSubmission(t)
 )

Type parameters

R

common result type

Value parameters

hasErrors

a function to handle forms with errors

success

a function to handle form submission success

Attributes

Returns

a result R.

def forField[R](key: String)(handler: Field => R): R

Applies a function for a field.

Applies a function for a field.

For example:

userForm.forField("username") { field =>
 <input type="text" name={field.name} value={field.value.getOrElse("")} />
}

Type parameters

R

result type

Value parameters

handler

field handler (transform the field to R)

key

field name

Attributes

def get: T

Returns the concrete value, if the submission was a success.

Returns the concrete value, if the submission was a success.

Note that this method fails with an Exception if this form has errors.

Attributes

def globalError: Option[FormError]

Retrieves the first global error, if it exists, i.e. an error without any key.

Retrieves the first global error, if it exists, i.e. an error without any key.

Attributes

Returns

an error

def globalErrors: Seq[FormError]

Retrieves all global errors, i.e. errors without a key.

Retrieves all global errors, i.e. errors without a key.

Attributes

Returns

all global errors

def hasErrors: Boolean

Returns true if there is an error related to this form.

Returns true if there is an error related to this form.

Attributes

def hasGlobalErrors: Boolean

Returns true if there is a global error related to this form.

Returns true if there is a global error related to this form.

Attributes

def withError(error: FormError): Form[T]

Adds an error to this form

Adds an error to this form

Value parameters

error

Error to add

Attributes

Returns

a copy of this form with the added error

def withError(key: String, message: String, args: Any*): Form[T]

Convenient overloaded method adding an error to this form

Convenient overloaded method adding an error to this form

Value parameters

args

Error message arguments

key

Key of the field having the error

message

Error message

Attributes

Returns

a copy of this form with the added error

def withGlobalError(message: String, args: Any*): Form[T]

Adds a global error to this form

Adds a global error to this form

Value parameters

args

Error message arguments

message

Error message

Attributes

Returns

a copy of this form with the added global error

Deprecated methods

def bind(data: JsValue): Form[T]

Binds data to this form, i.e. handles form submission.

Binds data to this form, i.e. handles form submission.

Value parameters

data

Json data to submit

Attributes

Returns

a copy of this form, filled with the new data

Deprecated
true

Inherited methods

def productElementNames: Iterator[String]

Attributes

Inherited from:
Product
def productIterator: Iterator[Any]

Attributes

Inherited from:
Product

Concrete fields

val constraints: Map[String, Seq[(String, Seq[Any])]]

Constraints associated with this form, indexed by field name.

Constraints associated with this form, indexed by field name.

Attributes

val formats: Map[String, (String, Seq[Any])]

Formats associated to this form, indexed by field name. *

Formats associated to this form, indexed by field name. *

Attributes

Generated with