fc.web.forms
Class Field

java.lang.Object
  extended by fc.web.forms.Field
Direct Known Subclasses:
AbstractText, Choice, ChoiceGroup, DependentField, Hidden, Select

public abstract class Field
extends Object

Represents an HTML form field. Subclasses provide concrete representations of various HTML input types.

Note: A FieldValidator for a given field is added to that field automatically by a new Validator when that validator is instantiated (so a public addValidator method is not needed in this class).

Fields are normally created and added to a form once. However, new fields can also be created per user/per-submit and added to the FormData object. These fields can then be rendered via the Form.renderDynamicFields(fc.web.forms.FormData, java.io.Writer) method and are shown just for that request. They are not part of the form and cannot be later retrieved by Form.get(java.lang.String) -- use {Form#getSubmittedField} instead.

Initial values (if any) for fields are typically specified during form instantiation. These default values are initially shown to all users when the form is rendered. However, in some cases, it is possible to show different initial values to different users. This is done by creating a new FormData object before the form is rendered and calling the setValue(FormData, ...) methods on various fields to set values on the formdata object.

FormData objects are automatically created to store submitted form data (and maintain form state) by the Form.handleSubmit(javax.servlet.http.HttpServletRequest) method. By manually creating a new FormData object before showing the form, and the using that object to render the form, per-user initial values can be displayed (this simulates a user form submission which of course is different for each user).

This form api is complex. For a simpler bare-bones alternative, see fc.web.simpleforms


Nested Class Summary
static class Field.Type
          Encapsulates different types of HTML form elements.
 
Constructor Summary
Field(String fieldName)
          Creates a new form Field.
 
Method Summary
 void add(FieldRefresher refresher)
          Adds a refresher to this field.
 void addError(FormData fd, String errorMessage)
          Adds a field level validation error message.
 void addLabel(String label)
          Adds some arbitrary text to this field which can later be retrieved via the getLabel method and shown as an html label for this field.
 void addString(String str)
          Adds any arbitrary string to the field, which is written as is when the field is rendered.
 void disable()
          Disables this field for all users.
 void disable(FormData fd)
          Disabled this field for this particular request.
 void enable()
          Enables this field for all users.
 void enable(FormData fd)
          Enables this field for this particular request.
 String getLabel()
          Returns the previously set label or null if no label was set.
 String getName()
          Returns the name of this form element
abstract  Field.Type getType()
          Subclasses should return an appropriate Field.Type.
 List getValidateErrors(FormData fd)
          Returns a List of Strings containing validation errors.
 boolean isEnabled(FormData fd)
           
abstract  boolean isFilled(FormData fd)
          Returns true if this field was isFilled out or selected by the user, false otherwise.
 void render(FormData fd, Writer writer)
          This method writes the HTML for this form field to the given writer.
 void render(FormData fd, Writer writer, String prefix, String suffix)
          Similar to render(Writer) but also renders the specified prefix/suffix strings before and after each element.
 void render(Writer writer)
          Convenience method that calls render(null, writer) (for when the form needs to be displayed the first time without any formdata)
 Field renderError(FormData fd, Writer writer)
          Calls renderError(Writer, String) with <br> as the message seperator string.
 Field renderError(FormData fd, Writer writer, String htmlSep)
          Convenience method to render validation errors.
abstract  void renderImpl(FormData fd, Writer writer)
           
 void renderStyleTag(boolean val)
          Set to true if the element should render a style tag, false otherwise.
 void setStyleTag(String value)
          Sets a style tag to be rendered (overrides the default class tag of formName-inputName.
abstract  void setValueFromSubmit(FormData fd, javax.servlet.http.HttpServletRequest req)
          This method sets the value of this field from the parameters obtained from the specified request.
 String toString()
           
 boolean validate(FormData fd, javax.servlet.http.HttpServletRequest req)
          Validates this field via the installed validators.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Field

public Field(String fieldName)
Creates a new form Field. By default, a field is enabled. To disable a field (so that it will not be validated), use the #setEnabled method.

Parameters:
fieldName - the name of this field
Method Detail

getName

public String getName()
Returns the name of this form element


getType

public abstract Field.Type getType()
Subclasses should return an appropriate Field.Type. This type is rendered as part of <input type= ...


setValueFromSubmit

public abstract void setValueFromSubmit(FormData fd,
                                        javax.servlet.http.HttpServletRequest req)
                                 throws SubmitHackedException
This method sets the value of this field from the parameters obtained from the specified request. The name of the parameter to obtain this value will typically be the name of this field itself.

Parameters:
fd - the form data object to store the value in
Throws:
SubmitHackedException

isFilled

public abstract boolean isFilled(FormData fd)
Returns true if this field was isFilled out or selected by the user, false otherwise.

Note: Some fields like selects will never be empty since non-multiple select fields always send their default selected value. [although select/with/multiple can be empty since the browser sends (much like radio buttoms) nothing at all when no option is selected].


renderImpl

public abstract void renderImpl(FormData fd,
                                Writer writer)
                         throws SQLException,
                                IOException
Throws:
SQLException
IOException

render

public void render(FormData fd,
                   Writer writer)
            throws SQLException,
                   IOException
This method writes the HTML for this form field to the given writer. Only the HTML for the field itself should be written and the enclosing HTML for this field is left upto the calling code. (typically a dynamic server side page). The field should be rendered in a sticky fashion, i.e., should incorporate/display the last submitted value.

Important Note: Although each field renders itself, validation errors are not rendered as part of this rendering. This is specifically designed for flexibility in HTML layout and display of error messages. This does imply that page authors must remember to extract and write error messages from each field.

Important Note 2: If providing a non-null argument for the FormData parameter, this method should only be called after calling Form.handleSubmit(javax.servlet.http.HttpServletRequest). FormData objects hold the results of submitted form data. If the formdata is null, it implies that the form is shown to the user for the first time. The fields then render themselves based on their default/initial values.. However, one can also display different initial values unique to a user (say by retrieving their last filled values from a database). In that case, a FormData object should be initially/manually created and passed to this method.

Parameters:
fd - the current form data object (can be null).
writer - the output destination
Throws:
SQLException
IOException

render

public void render(Writer writer)
            throws SQLException,
                   IOException
Convenience method that calls render(null, writer) (for when the form needs to be displayed the first time without any formdata)

Throws:
SQLException
IOException

render

public void render(FormData fd,
                   Writer writer,
                   String prefix,
                   String suffix)
            throws SQLException,
                   IOException
Similar to render(Writer) but also renders the specified prefix/suffix strings before and after each element. For example, one can say (in a jsp):
<% form.get("foo").render(); %>
or:
<% form.get("foo").render("<td>", "<br></td>"); %>

Parameters:
fd - the current form data object (if any). Form data objects hold the results of submitted form data. This might be null initially (when the form is show to the user for the first time).
writer - the output destination
prefix - prefix value for each element. specify null or an empty string if not needed.
suffix - suffix value for each element. specify null or an empty string if not needed.
Throws:
SQLException
IOException

renderError

public Field renderError(FormData fd,
                         Writer writer)
                  throws IOException
Calls renderError(Writer, String) with <br> as the message seperator string.

Throws:
IOException

renderError

public Field renderError(FormData fd,
                         Writer writer,
                         String htmlSep)
                  throws IOException
Convenience method to render validation errors. Normally, a jsp would always call getValidateErrors(fc.web.forms.FormData) and:

This method does exactly that: if applicable it writes validation error messages, each seperated by the specfied message seperator parameter.

If this field is rendering style tags, then the error messages are encapulated in a html <span> tag and the class of the span tag is set to form-errmsg

Parameters:
writer - the Writer to render errors to
htmlSep - the seperator string (any string or html tag/fragment) to separate messages (if there are more than 1 error messages)
Returns:
this field object for method chaining convenience
Throws:
IOException

addError

public void addError(FormData fd,
                     String errorMessage)
Adds a field level validation error message. This method is needed when some validation for this field is done via classes that are not subclasses of FieldValidator (these classes are used outside of the validation framework and their error message still needs to be added to the field validation error data)

This is a very useful method for adding the results of arbitrary code to this form.

See Also:
Form.addError(fc.web.forms.FormData, java.lang.String, java.lang.String)

add

public void add(FieldRefresher refresher)
Adds a refresher to this field. The refresher will be invoked to set new values for this field before the field is rendered.


addString

public void addString(String str)
Adds any arbitrary string to the field, which is written as is when the field is rendered. (style tags should be set via the setStyleTag(java.lang.String) however).

This method can be called as many times as needed. For example:

addString("tabindex=2");
addString("onclick='foo();return true;'");
or to set a arbitrary Javascript string:
addString("onMouseOver='bar()' onClick='foo()'");


addLabel

public void addLabel(String label)
Adds some arbitrary text to this field which can later be retrieved via the getLabel method and shown as an html label for this field. This is useful when programmatically creating fields from a database where the label itself is retrieved from the database.


getLabel

public String getLabel()
Returns the previously set label or null if no label was set.


validate

public boolean validate(FormData fd,
                        javax.servlet.http.HttpServletRequest req)
Validates this field via the installed validators. This method should be called after setting the submitted value of this field via the setValueFromSubmit(fc.web.forms.FormData, javax.servlet.http.HttpServletRequest) method.

No validators are run if the field is not enabled.

Validation errors that result after calling this method (if any) can be retrieved via the getValidateErrors(fc.web.forms.FormData) method.

Returns:
false on a validation error, true otherwise.

getValidateErrors

public List getValidateErrors(FormData fd)
Returns a List of Strings containing validation errors. Items in this list are a collection of all error messages (Strings) returned by validators that validate this field. If there are no validation errors, the returned list will be null.


enable

public void enable(FormData fd)
Enables this field for this particular request. Enabled fields run through all attached validators. Non enabled fields skip all validation.

Note, since we use the FormData to keep track of enable/disable status, fields can be enabled/disabled per user (independent of other users).


disable

public void disable(FormData fd)
Disabled this field for this particular request. Disabled fields skip all validation.

Note, since we use the FormData to keep track of enable/disable status, fields can be enabled/disabled per user (indepenent of other users).


enable

public void enable()
Enables this field for all users.


disable

public void disable()
Disables this field for all users.


isEnabled

public boolean isEnabled(FormData fd)

setStyleTag

public void setStyleTag(String value)
Sets a style tag to be rendered (overrides the default class tag of formName-inputName.


renderStyleTag

public void renderStyleTag(boolean val)
Set to true if the element should render a style tag, false otherwise. By default this value is true.

An arbitrary style class can be set for a field by calling the setStyleTag(java.lang.String) method. If a custom style class is not set via this method, style tags are rendered as:

class=formName-inputName
So, for example, a input type of name myname contained in the form myform will render it's style tag as the following class:
<input ..... class="myform-myname" ....>
Note, . and _ are not allowed in css class names (for legacy reasons) but - is allowed.


toString

public String toString()
Overrides:
toString in class Object