Class Field

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(FormData, Writer) method and are shown just for that request. They are not part of the form and cannot be later retrieved by Form.get(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(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
    Description
    static class 
    Field.Type
    Encapsulates different types of HTML form elements.

  • Constructor Summary

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

  • Method Summary

    Modifier and Type
    Method
    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(java.io.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
    invalid reference 
    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, jakarta.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, jakarta.servlet.http.HttpServletRequest req)
    Validates this field via the installed validators.

    Methods inherited from class Object

    equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • 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
      invalid reference 
      #setEnabled
      method.
      Parameters:
      fieldName - the name of this field

  • Method Details

    • 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, jakarta.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(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(java.io.Writer) but also renders the specified prefix/suffix strings before and after each element. For example, one can say (in a jsp):
      invalid input: '<'% form.get("foo").render(); %>
      or:
      <span class="invalid-tag">invalid input: '&lt;'</span>% form.get("foo").render("<td>", "<br></td>"); %&gt;
      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
      invalid reference 
      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(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:

    • 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(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, jakarta.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(FormData, 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(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(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:
      <span class="invalid-tag">invalid input: '&lt;'</span>input ..... class="myform-myname" ....&gt;
      Note, . and _ are not allowed in css class names (for legacy reasons) but - is allowed.

    • toString

      public String toString()
      Overrides:
      toString in class Object