play.data
Class Form<T>

java.lang.Object
  extended by play.data.Form<T>
Direct Known Subclasses:
DynamicForm

public class Form<T>
extends java.lang.Object

Helper to manage HTML form description, submission and validation.


Nested Class Summary
static interface Form.Display
          Defines a form element's display name.
static class Form.Field
          A form field.
 
Constructor Summary
Form(java.lang.Class<T> clazz)
          Creates a new Form.
Form(java.lang.String name, java.lang.Class<T> clazz)
           
Form(java.lang.String rootName, java.lang.Class<T> clazz, java.util.Map<java.lang.String,java.lang.String> data, java.util.Map<java.lang.String,java.util.List<ValidationError>> errors, F.Option<T> value)
          Creates a new Form.
 
Method Summary
 Form.Field apply(java.lang.String key)
          Retrieve a field.
 Form<T> bind(org.codehaus.jackson.JsonNode data, java.lang.String... allowedFields)
          Binds Json data to this form - that is, handles form submission.
 Form<T> bind(java.util.Map<java.lang.String,java.lang.String> data, java.lang.String... allowedFields)
          Binds data to this form - that is, handles form submission.
 Form<T> bindFromRequest(java.lang.String... allowedFields)
          Binds request data to this form - that is, handles form submission.
 java.util.Map<java.lang.String,java.lang.String> data()
          Retrieves the actual form data.
 ValidationError error(java.lang.String key)
          Retrieve an error by key.
 java.util.Map<java.lang.String,java.util.List<ValidationError>> errors()
          Returns all errors.
 org.codehaus.jackson.JsonNode errorsAsJson()
          Returns the form errors serialized as Json.
 org.codehaus.jackson.JsonNode errorsAsJson(Lang lang)
          Returns the form errors serialized as Json using the given Lang.
 Form.Field field(java.lang.String key)
          Retrieve a field.
 Form<T> fill(T value)
          Populates this form with an existing value, used for edit forms.
 T get()
          Gets the concrete value if the submission was a success.
 ValidationError globalError()
          Retrieves the first global error (an error without any key), if it exists.
 java.util.List<ValidationError> globalErrors()
          Retrieve all global errors - errors without a key.
 boolean hasErrors()
          Returns true if there are any errors related to this form.
 boolean hasGlobalErrors()
          Returns true if there any global errors related to this form.
 java.lang.String name()
           
 void reject(java.lang.String error)
          Add a global error to this form.
 void reject(java.lang.String error, java.util.List<java.lang.Object> args)
          Adds a global error to this form.
 void reject(java.lang.String key, java.lang.String error)
          Adds an error to this form.
 void reject(java.lang.String key, java.lang.String error, java.util.List<java.lang.Object> args)
          Adds an error to this form.
 void reject(ValidationError error)
          Adds an error to this form.
protected  java.util.Map<java.lang.String,java.lang.String> requestData()
           
 java.lang.String toString()
           
 F.Option<T> value()
          Retrieves the actual form value.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Form

public Form(java.lang.Class<T> clazz)
Creates a new Form.

Parameters:
clazz - wrapped class

Form

public Form(java.lang.String name,
            java.lang.Class<T> clazz)

Form

public Form(java.lang.String rootName,
            java.lang.Class<T> clazz,
            java.util.Map<java.lang.String,java.lang.String> data,
            java.util.Map<java.lang.String,java.util.List<ValidationError>> errors,
            F.Option<T> value)
Creates a new Form.

Parameters:
clazz - wrapped class
data - the current form data (used to display the form)
errors - the collection of errors associated with this form
value - optional concrete value of type T if the form submission was successful
Method Detail

requestData

protected java.util.Map<java.lang.String,java.lang.String> requestData()

bindFromRequest

public Form<T> bindFromRequest(java.lang.String... allowedFields)
Binds request data to this form - that is, handles form submission.

Returns:
a copy of this form filled with the new data

bind

public Form<T> bind(org.codehaus.jackson.JsonNode data,
                    java.lang.String... allowedFields)
Binds Json data to this form - that is, handles form submission.

Parameters:
data - data to submit
Returns:
a copy of this form filled with the new data

bind

public Form<T> bind(java.util.Map<java.lang.String,java.lang.String> data,
                    java.lang.String... allowedFields)
Binds data to this form - that is, handles form submission.

Parameters:
data - data to submit
Returns:
a copy of this form filled with the new data

data

public java.util.Map<java.lang.String,java.lang.String> data()
Retrieves the actual form data.


name

public java.lang.String name()

value

public F.Option<T> value()
Retrieves the actual form value.


fill

public Form<T> fill(T value)
Populates this form with an existing value, used for edit forms.

Parameters:
value - existing value of type T used to fill this form
Returns:
a copy of this form filled with the new data

hasErrors

public boolean hasErrors()
Returns true if there are any errors related to this form.


hasGlobalErrors

public boolean hasGlobalErrors()
Returns true if there any global errors related to this form.


globalErrors

public java.util.List<ValidationError> globalErrors()
Retrieve all global errors - errors without a key.

Returns:
All global errors.

globalError

public ValidationError globalError()
Retrieves the first global error (an error without any key), if it exists.

Returns:
An error or null.

errors

public java.util.Map<java.lang.String,java.util.List<ValidationError>> errors()
Returns all errors.

Returns:
All errors associated with this form.

error

public ValidationError error(java.lang.String key)
Retrieve an error by key.


errorsAsJson

public org.codehaus.jackson.JsonNode errorsAsJson()
Returns the form errors serialized as Json.


errorsAsJson

public org.codehaus.jackson.JsonNode errorsAsJson(Lang lang)
Returns the form errors serialized as Json using the given Lang.


get

public T get()
Gets the concrete value if the submission was a success.


reject

public void reject(ValidationError error)
Adds an error to this form.

Parameters:
error - the ValidationError to add.

reject

public void reject(java.lang.String key,
                   java.lang.String error,
                   java.util.List<java.lang.Object> args)
Adds an error to this form.

Parameters:
key - the error key
error - the error message
args - the errot arguments

reject

public void reject(java.lang.String key,
                   java.lang.String error)
Adds an error to this form.

Parameters:
key - the error key
error - the error message

reject

public void reject(java.lang.String error,
                   java.util.List<java.lang.Object> args)
Adds a global error to this form.

Parameters:
error - the error message
args - the errot arguments

reject

public void reject(java.lang.String error)
Add a global error to this form.

Parameters:
error - the error message.

apply

public Form.Field apply(java.lang.String key)
Retrieve a field.

Parameters:
key - field name
Returns:
the field (even if the field does not exist you get a field)

field

public Form.Field field(java.lang.String key)
Retrieve a field.

Parameters:
key - field name
Returns:
the field (even if the field does not exist you get a field)

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object