Package org.xmpp.forms

Class FormField

java.lang.Object
org.xmpp.forms.FormField
@NotThreadSafe public class FormField extends Object
Represents a field of a form. The field could be used to represent a question to complete, a completed question or a data returned from a search. The exact interpretation of the field depends on the context where the field is used.
Author:
Gaston Dombiak

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    FormField.Option
    Represents the available option of a given FormField.
    static enum 
    FormField.Type
    Type-safe enumeration to represent the field type of the Data forms.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addOption(String label, String value)
    Adds an available option to the question that the user has in order to answer the question.
    void
    addValue(Object value)
    Adds a default value to the question if the question is part of a form to fill out.
    void
    clearValues()
    Removes all the values of the field.
    FormField
    createCopy()
    Creates and returns a new object that is an exact copy of this FormField object.
    String
    getDescription()
    Returns a description that provides extra clarification about the question.
    String
    getFirstValue()
    Returns the first value from the FormField, or 'null' if no value has been set.
    String
    getLabel()
    Returns the label of the question which should give enough information to the user to fill out the form.
    List<FormField.Option>
    getOptions()
    Returns the available options to answer for this question.
    FormField.Type
    getType()
    Returns an indicative of the format for the data to answer.
    List<String>
    getValues()
    Returns an Iterator for the default values of the question if the question is part of a form to fill out.
    String
    getVariable()
    Returns the variable name that the question is filling out.
    boolean
    isRequired()
    Returns true if the question must be answered in order to complete the questionnaire.
    void
    setDescription(String description)
    Sets a description that provides extra clarification about the question.
    void
    setLabel(String label)
    Sets the label of the question which should give enough information to the user to fill out the form.
    void
    setRequired(boolean required)
    Sets if the question must be answered in order to complete the questionnaire.
    void
    setType(FormField.Type type)
    Sets an indicative of the format for the data to answer.
    void
    setVariable(String var)
    Sets the attribute that uniquely identifies the field in the context of the form.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • addValue

      public void addValue(Object value)
      Adds a default value to the question if the question is part of a form to fill out. Otherwise, adds an answered value to the question.

      Nothing will be added if the provided argument is null.

      Parameters:
      value - a default value or an answered value of the question.

    • clearValues

      public void clearValues()
      Removes all the values of the field.

    • addOption

      public void addOption(String label, String value)
      Adds an available option to the question that the user has in order to answer the question.

      If argument 'value' is null or an empty String, no option element will be added.

      Parameters:
      label - a label that represents the option. Optional argument.
      value - the value of the option.

    • getOptions

      public List<FormField.Option> getOptions()
      Returns the available options to answer for this question. The returned options cannot be modified but they will be updated if the underlying DOM object gets updated.
      Returns:
      the available options to answer for this question.

    • setType

      public void setType(FormField.Type type)
      Sets an indicative of the format for the data to answer. Valid formats are:
      • text-single -> single line or word of text
      • text-private -> instead of showing the user what they typed, you show ***** to protect it
      • text-multi -> multiple lines of text entry
      • list-single -> given a list of choices, pick one
      • list-multi -> given a list of choices, pick one or more
      • boolean -> 0 or 1, true or false, yes or no. Default value is 0
      • fixed -> fixed for putting in text to show sections, or just advertise your web site in the middle of the form
      • hidden -> is not given to the user at all, but returned with the questionnaire
      • jid-single -> Jabber ID - choosing a JID from your roster, and entering one based on the rules for a JID.
      • jid-multi -> multiple entries for JIDs
      Parameters:
      type - an indicative of the format for the data to answer.

    • setVariable

      public void setVariable(String var)
      Sets the attribute that uniquely identifies the field in the context of the form. If the field is of type "fixed" then the variable is optional.
      Parameters:
      var - the unique identifier of the field in the context of the form.

    • setLabel

      public void setLabel(String label)
      Sets the label of the question which should give enough information to the user to fill out the form.
      Parameters:
      label - the label of the question.

    • setRequired

      public void setRequired(boolean required)
      Sets if the question must be answered in order to complete the questionnaire.
      Parameters:
      required - if the question must be answered in order to complete the questionnaire.

    • setDescription

      public void setDescription(String description)
      Sets a description that provides extra clarification about the question. This information could be presented to the user either in tool-tip, help button, or as a section of text before the question.

      If the question is of type FIXED then the description should remain empty.

      No new description will be set, if the provided argument is null or an empty String (although an existing description will be removed).

      Parameters:
      description - provides extra clarification about the question.

    • isRequired

      public boolean isRequired()
      Returns true if the question must be answered in order to complete the questionnaire.
      Returns:
      true if the question must be answered in order to complete the questionnaire.

    • getVariable

      public String getVariable()
      Returns the variable name that the question is filling out.
      Returns:
      the variable name of the question.

    • getValues

      public List<String> getValues()
      Returns an Iterator for the default values of the question if the question is part of a form to fill out. Otherwise, returns an Iterator for the answered values of the question.
      Returns:
      an Iterator for the default values or answered values of the question.

    • getFirstValue

      public String getFirstValue()
      Returns the first value from the FormField, or 'null' if no value has been set.
      Returns:
      String based value, or 'null' if the FormField has no values.

    • getType

      public FormField.Type getType()
      Returns an indicative of the format for the data to answer. Valid formats are:
      • text-single -> single line or word of text
      • text-private -> instead of showing the user what they typed, you show ***** to protect it
      • text-multi -> multiple lines of text entry
      • list-single -> given a list of choices, pick one
      • list-multi -> given a list of choices, pick one or more
      • boolean -> 0 or 1, true or false, yes or no. Default value is 0
      • fixed -> fixed for putting in text to show sections, or just advertise your web site in the middle of the form
      • hidden -> is not given to the user at all, but returned with the questionnaire
      • jid-single -> Jabber ID - choosing a JID from your roster, and entering one based on the rules for a JID.
      • jid-multi -> multiple entries for JIDs
      Returns:
      format for the data to answer.

    • getLabel

      public String getLabel()
      Returns the label of the question which should give enough information to the user to fill out the form.
      Returns:
      label of the question.

    • getDescription

      public String getDescription()
      Returns a description that provides extra clarification about the question. This information could be presented to the user either in tool-tip, help button, or as a section of text before the question.

      If the question is of type FIXED then the description should remain empty.

      Returns:
      description that provides extra clarification about the question.

    • createCopy

      public FormField createCopy()
      Creates and returns a new object that is an exact copy of this FormField object.
      Returns:
      an exact copy of this instance.