Field (MollyPages.org Foundation API)

java.lang.Object
- 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

Nested Classes
Modifier and Type Class and Description

static class Field.Type
Encapsulates different types of HTML form elements.

Nested Classes
Modifier and Type	Class and Description
`static class`	`Field.Type` Encapsulates different types of HTML form elements.

Constructor Summary

Constructors
Constructor and Description

Field(String fieldName)
Creates a new form Field.

Constructors
Constructor and Description
`Field(String fieldName)` Creates a new form Field.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`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:
    - if the returned data was null would write an empty string or nothing
    - the list of error messages adjacent to the html field itself.
    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:
    Note, . and _ are not allowed in css class names (for legacy reasons) but - is allowed.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class Field

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Field

Method Detail

getName

getType

setValueFromSubmit

isFilled

renderImpl

render

render

render

renderError

renderError

addError

add

addString

addLabel

getLabel

validate

getValidateErrors

enable

disable

enable

disable

isEnabled

setStyleTag

renderStyleTag

toString