|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectfc.web.forms.Form
public class Form
Represents an HTML form. It is possible to instantiate a different form object per user and store each form in that users session scope. However, more typically, instances of this object are instantiated once per unique form and stored in web application scope.
Method in this class are thread safe since form processing is done
entirely within various methods and the form processing results in the
creation of seperate FormData
objects for each request.
Various Fields
can be added to the form at form creation
time. Some fields (like Hidden
can also be added per user/request,
dynamically, to the FormData
object. This is useful while saving
some user or request specific information.
A form collects data from the front-end/web-client and often saves it to a back end database entity. Form data validation can be done in 2 ways:
An HTML form presented to the user can contain fields from more than 1 database table. For example, there could to 2 database tables, say "person" and "office" both with a "other" column. Since each field contained in the form object must have a unique name, there will be a name clash between the fields/attributes of the entities when 2 fields with the name "other" are added to the form.
There are 2 general approaches to solving this problem.
Sometimes, other methods need to obtain a field (for a particular table) by
name. For example, the managers generated by Generate
have a addValidators(form) method that extract the fields for a
particular table and add validators to that field. This method in
particular need to be passed either the appropriate form object in which
that field exists (if there are multiple form objects) or in the case of
only 1 form object, passed the prefix for that particular field, if that
field was added with a prefix to it's name.
Field Summary | |
---|---|
static java.util.List |
empty_list
|
static java.util.Map |
empty_map
|
Constructor Summary | |
---|---|
Form(java.lang.String name)
Creates a new form with the specified name, method=POST and no action URL |
|
Form(java.lang.String name,
java.lang.String method,
java.lang.String actionURL)
Creates a new form with logging to the default log retreived by Log.getDefault() and the default SubmitHackedHandler |
|
Form(java.lang.String name,
java.lang.String method,
java.lang.String actionURL,
Log log)
|
|
Form(java.lang.String name,
java.lang.String method,
java.lang.String actionURL,
Log log,
SubmitHackedHandler handler)
Creates a new form with the specified name, method (get/post) and URL |
Method Summary | |
---|---|
Form |
add(Dependency d)
Adds the specified dependency to the form. |
Form |
add(Field field)
Adds the specified element to the form. |
Form |
add(FieldRef ref)
Adds a FieldRef to this Form. |
void |
addDynamicField(FormData fd,
Hidden f)
Adds a Hidden field to this form. |
void |
addError(FormData fd,
java.lang.String errorMessage)
Convenience method that invokes addError with an empty validation errorKey. |
void |
addError(FormData fd,
java.lang.String errorKey,
java.lang.String errorMessage)
Adds a form level validation error message. |
void |
addMessage(FormData fd,
java.lang.String key,
java.lang.String value)
Adds an arbitrary message for this request. |
void |
addSubmitHackedHandler(SubmitHackedHandler handler)
|
void |
addValidator(FormValidator validator)
Adds a form level validator to this form. |
boolean |
containsField(java.lang.String fieldName)
Returns true if the form contains the specified field. |
void |
destroy()
This method should be called when the form is removed from session or application scope. |
Field |
get(java.lang.String name)
Returns the form field with the specified name. |
java.lang.String |
getActionURL()
Returns the action URL string. |
java.util.Collection |
getAllFields()
Returns a collection view of all the fields contained in this form. |
Checkbox |
getCheckbox(java.lang.String name)
Returns the field with the specific name as a Checkbox . |
CheckboxGroup |
getCheckboxGroup(java.lang.String name)
Returns the field with the specific name as a Checkbox . |
java.util.List |
getContaining(java.lang.String name)
Returns all the fields that contains the specified name. |
java.lang.String |
getDisplayURL()
Returns the display URL string. |
Hidden |
getDynamicField(FormData fd,
java.lang.String fieldName)
Gets a Hidden field added to the form data object. |
java.util.Map |
getFieldErrors(FormData fd)
|
FieldRef |
getFieldRef(java.lang.String key)
Returns the FieldRef with the specified key. |
java.util.Collection |
getFormErrorsCollection(FormData fd)
|
java.util.List |
getFormErrorsFor(FormData fd,
java.lang.String formValidatorName)
Returns a list containing all form-level errors for the specified validator. |
Hidden |
getHidden(java.lang.String name)
Returns the field with the specific name as a Hidden . |
java.lang.String |
getMessage(FormData fd,
java.lang.String key)
Retrieves a previously added message or null if the speccified form data was null or if the message was not found. |
java.lang.String |
getName()
Returns the name of this form |
Password |
getPassword(java.lang.String name)
Returns the field with the specific name as a Password . |
Radio |
getRadio(java.lang.String name)
Returns the field with the specific name as a Radio . |
RadioGroup |
getRadioGroup(java.lang.String name)
Returns the field with the specific name as a Checkbox . |
Select |
getSelect(java.lang.String name)
Returns the field with the specific name as a Select . |
Hidden |
getSubmittedField(javax.servlet.http.HttpServletRequest req,
java.lang.String name)
Once the form is displayed to the user (with, say, hidden fields that were added dynamically for that request), then when that form is submitted, those dynamic fields can be retrieved via any of: the ServletRequest.getParameter(java.lang.String) method (often the easiest
way)
the #getSubmittedField(HttpServletRequest) method (which will
attempt to read the request parameter with the specified name and return
is as a Hidden field. |
Text |
getText(java.lang.String name)
Returns the field with the specific name as a Text . |
TextArea |
getTextArea(java.lang.String name)
Returns the field with the specific name as a TextArea . |
java.util.Timer |
getTimer()
|
RefreshableSelect |
getUpdatableSelect(java.lang.String name)
Returns the field with the specific name as a RefreshableSelect . |
FormData |
handleSubmit(javax.servlet.http.HttpServletRequest req)
Processes the submitted form. |
FormData |
handleSubmit(javax.servlet.http.HttpServletRequest req,
java.sql.Connection con)
This method is similar to handleSubmit(HttpServletRequest) except
it stores the specified connection in the form data. |
static boolean |
hasError(FormData fd)
Returns true if validation did not succeed. |
FormData |
refresh(javax.servlet.http.HttpServletRequest req)
|
FormData |
refresh(javax.servlet.http.HttpServletRequest req,
java.sql.Connection con)
Refreshes the form for this request by running all attached refreshers and dependencies. |
java.lang.Object |
remove(Field field)
Removes the specified field from the form. |
void |
renderDynamicFields(FormData fd,
java.io.Writer out)
Renders all dynamically added hidden fields of the form. |
void |
renderError(FormData fd,
java.io.Writer writer)
Convenience method to render form-level validation errors. |
void |
renderErrorFor(FormData fd,
java.io.Writer writer,
java.lang.String formValidatorName)
Convenience method to render a validation error for a particluar form level validator. |
void |
setActionURL(java.lang.String url)
Sets an arbitrary application specific string that can later be retrieved. |
void |
setDisplayURL(java.lang.String url)
Sets an arbitrary application specific string. |
java.lang.String |
toString()
|
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final java.util.List empty_list
public static final java.util.Map empty_map
Constructor Detail |
---|
public Form(java.lang.String name, java.lang.String method, java.lang.String actionURL, Log log, SubmitHackedHandler handler)
public Form(java.lang.String name, java.lang.String method, java.lang.String actionURL, Log log)
public Form(java.lang.String name, java.lang.String method, java.lang.String actionURL)
Log.getDefault()
and the default SubmitHackedHandler
public Form(java.lang.String name)
Method Detail |
---|
public void destroy()
public java.lang.Object remove(Field field)
Map.remove(Object)
for the general contract.
field
- the field to remove from the form.public Form add(Field field)
Note, field names have to be unique. "Grouped" fields (such
as HTML form checkboxes or radio buttons) which require the
same field name are encapsulated by a single appropriate
grouped field object such as RadioGroup
and CheckboxGroup
. This field object itself should have a
unique name.
java.lang.IllegalArgumentException
- if an element with the same name
already exists in this form.public Form add(Dependency d)
public Form add(FieldRef ref)
FieldRef
to this Form. This is useful when
to track a set of related fields in a form. (Note: those fields
must also directly be added to the form).
public void addError(FormData fd, java.lang.String errorKey, java.lang.String errorMessage)
FormValidator
(these classes are used outside of the
validation framework and their error message still needs to be added to
the form data).
This is a very useful method for adding the results of arbitrary code to this form.
fd
- form dataerrorKey
- an arbitrary/optional validation key which allows
to later retrieve and display a particular
form error. Specify null for no
key.errorMessage
- the form error messageField.addError(fc.web.forms.FormData, java.lang.String)
public void addError(FormData fd, java.lang.String errorMessage)
addError
with an empty validation errorKey.
public void addDynamicField(FormData fd, Hidden f)
Hidden
field to this form. This field exists only for the
duration of this form data object and is useful for request specific
data.
public void addValidator(FormValidator validator)
java.lang.IllegalArgumentException
- if a validator with the same name
already exists in this form.public void addMessage(FormData fd, java.lang.String key, java.lang.String value)
public boolean containsField(java.lang.String fieldName)
public java.lang.String getMessage(FormData fd, java.lang.String key)
public void addSubmitHackedHandler(SubmitHackedHandler handler)
public FormData handleSubmit(javax.servlet.http.HttpServletRequest req) throws javax.servlet.ServletException, java.io.IOException
hasError(FormData)
method with the formdata returned by this method.
Seeing validation errors is optional of course, and so is using validators
in the first place.
req
- the HttpServletRequest corresponding to the request
being processed by this form.
FormData
object containing populated
field data and the results of the validation.
javax.servlet.ServletException
java.io.IOException
public FormData handleSubmit(javax.servlet.http.HttpServletRequest req, java.sql.Connection con) throws javax.servlet.ServletException, java.io.IOException
handleSubmit(HttpServletRequest)
except
it stores the specified connection in the form data. This connection can
be used by any attached dependency classes for database queries when
updating form depedencies.
Note, we can set arbitrary objects in the HttpServletRequest
via
it's setAttribute
method.
However, specifying and storing the connection in the FormData is easier
to remember and use.
There are 2 cases:
WebApp#getConnection
to obtain a connection and no connection has to be set in the form data.handleSubmit(HttpServletRequest)
can then be used.
handleSubmit(HttpServletRequest)
is sufficient.
req
- the HttpServletRequest corresponding to the request
being processed by this form.con
- a connection object. The connection is not closed and
it is the callers responsiblity to do so.
javax.servlet.ServletException
java.io.IOException
public FormData refresh(javax.servlet.http.HttpServletRequest req) throws javax.servlet.ServletException, java.io.IOException
javax.servlet.ServletException
java.io.IOException
public FormData refresh(javax.servlet.http.HttpServletRequest req, java.sql.Connection con) throws javax.servlet.ServletException, java.io.IOException
To refresh the form for all users/requests from this point onwards, create a new instance of the form and replace the existing instance of the form with the newly created instance.
javax.servlet.ServletException
java.io.IOException
public static boolean hasError(FormData fd)
public void renderError(FormData fd, java.io.Writer writer) throws java.io.IOException
writer
- the Writer to render errors to
java.io.IOException
public void renderErrorFor(FormData fd, java.io.Writer writer, java.lang.String formValidatorName) throws java.io.IOException
writer
- the Writer to render errors toformValidatorName
- the name of a form level validator
java.io.IOException
public java.util.Map getFieldErrors(FormData fd)
fd
- a non-null form data object
Field.getValidateErrors(fc.web.forms.FormData)
methodpublic java.util.Collection getFormErrorsCollection(FormData fd)
fd
- a non-null form data object
FormValidator.getErrorMessage()
methodpublic java.util.List getFormErrorsFor(FormData fd, java.lang.String formValidatorName)
fd
- a non-null form data objectformValidatorName
- a form validator namepublic void renderDynamicFields(FormData fd, java.io.Writer out) throws java.sql.SQLException, java.io.IOException
FormData
if/as needed.
Note: Dynamic fields are not part of a form's fields and are not available via
java.sql.SQLException
java.io.IOException
public java.lang.String getName()
public void setActionURL(java.lang.String url)
public java.lang.String getActionURL()
public void setDisplayURL(java.lang.String url)
public java.lang.String getDisplayURL()
public java.util.Collection getAllFields()
public Field get(java.lang.String name)
name
- the name of the field
public Hidden getDynamicField(FormData fd, java.lang.String fieldName)
Hidden
field added to the form data object. Returns
null if the form data object is null or if the specified
field does not exist. Dyanamic fields returned by this method are only
available for the duration of the form data object and can not
obtain a field from a submitted form. (use getDynamicField(FormData, HttpServletRequest)
for that purpose.
public Hidden getSubmittedField(javax.servlet.http.HttpServletRequest req, java.lang.String name)
ServletRequest.getParameter(java.lang.String)
method (often the easiest
way)
#getSubmittedField(HttpServletRequest)
method (which will
attempt to read the request parameter with the specified name and return
is as a Hidden field. (this is slightly more convenient if there is more
than 1 hidden field with the same name, since all hidden fields with the
same name are encapsulated by one object of type Hidden
).
public java.util.List getContaining(java.lang.String name)
name
- the name of the field
public FieldRef getFieldRef(java.lang.String key)
FieldRef
with the specified key. This is
used to retrieve an arbitrary object added the via #addObject
method. Returns null if no object is
found for the specified key.
public java.util.Timer getTimer()
public Select getSelect(java.lang.String name)
Select
.
java.lang.IllegalArgumentException
- if a field with the specified name does not exist or
if the field exists but is not of type Selectpublic RefreshableSelect getUpdatableSelect(java.lang.String name)
RefreshableSelect
.
java.lang.IllegalArgumentException
- if a field with the specified name does not exist or
if the field exists but is not of type RefreshableSelectpublic Checkbox getCheckbox(java.lang.String name)
Checkbox
.
java.lang.IllegalArgumentException
- if a field with the specified name does not exist or
if the field exists but is not of type Checkboxpublic CheckboxGroup getCheckboxGroup(java.lang.String name)
Checkbox
.
java.lang.IllegalArgumentException
- if a field with the specified name does not exist or
if the field exists but is not of type Checkboxpublic Hidden getHidden(java.lang.String name)
Hidden
.
java.lang.IllegalArgumentException
- if a field with the specified name does not exist or
if the field exists but is not of type Hiddenpublic Text getText(java.lang.String name)
Text
.
java.lang.IllegalArgumentException
- if a field with the specified name does not exist or
if the field exists but is not of type Textpublic TextArea getTextArea(java.lang.String name)
TextArea
.
java.lang.IllegalArgumentException
- if a field with the specified name does not exist or
if the field exists but is not of type TextAreapublic Password getPassword(java.lang.String name)
Password
.
java.lang.IllegalArgumentException
- if a field with the specified name does not exist or
if the field exists but is not of type Passwordpublic Radio getRadio(java.lang.String name)
Radio
.
java.lang.IllegalArgumentException
- if a field with the specified name does not exist or
if the field exists but is not of type Radiopublic RadioGroup getRadioGroup(java.lang.String name)
Checkbox
.
java.lang.IllegalArgumentException
- if a field with the specified name does not exist or
if the field exists but is not of type Checkboxpublic java.lang.String toString()
toString
in class java.lang.Object
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |