Class FormField

    • Method Detail

      • getName

        public java.lang.String getName()
        Returns the control name shared by all of this field's constituent controls.

        If the static Config.CurrentCompatibilityMode.isFormFieldNameCaseInsensitive() property is set to true, the grouping of the controls by name is case insensitive and this method always returns the name in lower case.

        Since a form field is simply a group of controls with the same name, the terms control name and field name are for the most part synonymous, with only a possible difference in case differentiating them.

        Returns:
        the control name shared by all of this field's constituent controls.
        See Also:
        FormControl.getName()
      • getFormControl

        public FormControl getFormControl​(java.lang.String predefinedValue)
        Returns the constituent FormControl with the specified predefined value.

        Specifying a predefined value of null returns the first control without a predefined value.

        Parameters:
        predefinedValue - the predefined value of the control to be returned, or null to return the first control without a predefined value.
        Returns:
        the constituent FormControl with the specified predefined value, or null if none exists.
        See Also:
        getFormControl(), getFormControls()
      • allowsMultipleValues

        public boolean allowsMultipleValues()
        Indicates whether the field allows multiple values.

        Returns false in any one of the following circumstances:

        • The field consists of only one control (unless it is a multiple select with more than one option)
        • The field consists entirely of radio buttons
        • The field consists entirely of submit buttons
        If none of these three conditions are met, the method returns true.
        Returns:
        true if the field allows multiple values, otherwise false.
      • getUserValueCount

        public int getUserValueCount()
        Returns the number of constituent user value controls in this field. This should in most cases be either 0 or 1.

        A value of 0 indicates the field values consist only of predefined values, which is the case when the field consists only of predefined value controls.

        A value of 1 indicates the field values consist of at most one value set by the user. It is still possible in this case to receive multiple values in the unlikely event that the HTML author mixed controls of different types with the same name, but any other values would consist only of predefined values.

        A value greater than 1 indicates that the HTML author has included more than one user value control with the same name. This would nearly always indicate an unintentional error in the HTML source document, in which case your application can either log a warning that a poorly designed form has been encountered, or take special action to try to interpret the multiple user values that might be submitted.

        Returns:
        the number of constituent user value controls in this field.
      • getPredefinedValues

        public java.util.Collection<java.lang.String> getPredefinedValues()
        Returns a collection of the predefined values of all constituent controls in this field.

        All objects in the returned collection are of type String, with no null entries.

        An interator over this collection returns the values in the order of appearance in the source document.

        Returns:
        a collection of the predefined values of all constituent controls in this field, or null if none.
        See Also:
        FormControl.getPredefinedValues()
      • getValues

        public java.util.List<java.lang.String> getValues()
        Returns a list of the field submission values in order of appearance.

        The term field submission values is used in this library to refer to the aggregate of all the submission values of a field's constituent form controls.

        All objects in the returned list are of type String, with no null entries.

        The list may contain duplicates if the this field has multiple controls with the same value.

        Returns:
        a list of the field submission values in order of appearance, guaranteed not null.
      • addValue

        public boolean addValue​(java.lang.String value)
        Adds the specified value to the field submission values of this field.

        This is achieved internally by attempting to add the value to every constituent form control until one "accepts" it.

        The return value indicates whether any of the constituent form controls accepted the value. A return value of false implies an error condition as the specified value is not compatible with this field.

        In the unusual case that this field consists of multiple form controls, but not all of them are predefined value controls, priority is given to the predefined value controls before attempting to add the value to the user value controls.

        Parameters:
        value - the new field submission value to add to this field, must not be null.
        Returns:
        true if one of the constituent form controls accepts the value, otherwise false.
      • getDebugInfo

        public java.lang.String getDebugInfo()
        Returns a string representation of this object useful for debugging purposes.
        Returns:
        a string representation of this object useful for debugging purposes.
      • toString

        public java.lang.String toString()
        Returns a string representation of this object useful for debugging purposes.

        This is equivalent to getDebugInfo().

        Overrides:
        toString in class java.lang.Object
        Returns:
        a string representation of this object useful for debugging purposes.