Package org.apache.wicket.markup.html.form

Class FormComponent<T>

    • Field Detail

      • VALUE_SEPARATOR

        public static final java.lang.String VALUE_SEPARATOR
        The value separator
        See Also:
        Constant Field Values

      • FLAG_CONVERT_EMPTY_INPUT_STRING_TO_NULL

        protected static final short FLAG_CONVERT_EMPTY_INPUT_STRING_TO_NULL
        Make empty strings null values boolean. Used by AbstractTextComponent subclass.
        See Also:
        Constant Field Values

    • Method Detail

      • visitFormComponentsPostOrder

        public static <R> R visitFormComponentsPostOrder​(Component component,
                                                 org.apache.wicket.util.visit.IVisitor<? extends FormComponent<?>,​R> visitor)
        Visits any form components inside component if it is a container, or component itself if it is itself a form component
        Type Parameters:
        R - the type of the visitor's result
        Parameters:
        component - starting point of the traversal
        visitor - The visitor to call
        Returns:
        the visitor's result

      • visitComponentsPostOrder

        public static <R> R visitComponentsPostOrder​(Component component,
                                             org.apache.wicket.util.visit.IVisitor<Component,​R> visitor)
        Visits any form components inside component if it is a container, or component itself if it is itself a form component
        Type Parameters:
        R - the type of the visitor's result
        Parameters:
        component - starting point of the traversal
        visitor - The visitor to call
        Returns:
        the visitor's result

      • getDefaultLabel

        public final java.lang.String getDefaultLabel()
        Gets the string the component would use as a label when one was requested but no label model was set via LabeledWebMarkupContainer.getLabel(). The value of this string is usually set in a property file; if the value is not set the default value equivalent to component id will be returned.
        Returns:
        localized label

      • getDefaultLabel

        public final java.lang.String getDefaultLabel​(java.lang.String defaultValue)
        Gets the string the component would use as a label when one was requested but no label model was set via LabeledWebMarkupContainer.getLabel(). The value of this string is usually set in a property file; if the value is not set the defaultValue will be returned.
        Parameters:
        defaultValue -
        Returns:
        localized label

      • add

        public final FormComponent<T> add​(IValidator<? super T> validator)
        Adds a validator to this form component
        Parameters:
        validator - validator to be added
        Returns:
        this for chaining
        Throws:
        java.lang.IllegalArgumentException - if validator is null
        See Also:
        IValidator

      • remove

        public final FormComponent<T> remove​(IValidator<? super T> validator)
        Removes a validator from the form component.
        Parameters:
        validator - validator
        Returns:
        form component for chaining
        Throws:
        java.lang.IllegalArgumentException - if validator is null or not found
        See Also:
        IValidator, add(IValidator)

      • add

        public final FormComponent<T> add​(IValidator<? super T>... validators)
        Adds a validator to this form component.
        Parameters:
        validators - The validator(s) to be added
        Returns:
        This
        Throws:
        java.lang.IllegalArgumentException - if validator is null
        See Also:
        IValidator

      • checkRequired

        public boolean checkRequired()
        Checks if the form component's 'required' requirement is met by first checking isRequired() to see if it has to check for requirement. If that is true then by default it checks if the input is null or an empty String Strings.isEmpty(CharSequence)

        Subclasses that overwrite this method should also call isRequired() first.

        Returns:
        true if the 'required' requirement is met, false otherwise
        See Also:
        Strings.isEmpty(CharSequence), isInputNullable()

      • clearInput

        public void clearInput()
        Clears the user input.

      • error

        public void error​(IValidationError error)
        Reports a validation error against this form component. The actual error is reported by creating a ValidationErrorFeedback object that holds both the validation error and the generated error message - so a custom feedback panel can have access to both.
        Parameters:
        error - validation error

      • getConvertedInput

        public final T getConvertedInput()
        Gets the converted input. The converted input is set earlier though the implementation of convertInput(). FormComponentPanel often access this method when constructing their converted input value which is often the combination of converted values of the embedded FormComponents To access the model object resulted by the full form processing, use IGenericComponent.getModelObject() instead, that is an generified version of Component.getDefaultModelObject()
        Returns:
        value of input possibly converted into an appropriate type

      • setConvertedInput

        public final void setConvertedInput​(T convertedInput)
        Sets the converted input. This method is typically not called by clients, unless they override convertInput(), in which case they should call this method to update the input for this component instance.
        Parameters:
        convertedInput - the converted input

      • getForm

        public Form<?> getForm()
        Returns:
        The parent form for this form component

      • getInput

        public java.lang.String getInput()
        Gets the request parameter for this component as a string.
        Returns:
        The value in the request for this component

      • getInputAsArray

        public java.lang.String[] getInputAsArray()
        Gets the request parameters for this component as strings.
        Returns:
        The values in the request for this component

      • getInputName

        public java.lang.String getInputName()
        Gets the string to be used for the name attribute of the form element. Generated using the path from the form to the component, excluding the form itself. Override it if you want even a smaller name. E.g. if you know for sure that the id is unique within a form.
        Returns:
        The string to use as the form element's name attribute

      • getRawInput

        public final java.lang.String getRawInput()
        Use hasRawInput() to check if this component has raw input because null can mean 2 things: It doesn't have rawinput or the rawinput is really null.
        Returns:
        The raw form input that is stored for this formcomponent

      • getType

        public final java.lang.Class<T> getType()
        Returns:
        the type to use when updating the model for this form component

      • getValidatorKeyPrefix

        public java.lang.String getValidatorKeyPrefix()
        Returns:
        prefix used when constructing validator key messages
        See Also:
        Form.getValidatorKeyPrefix()

      • getValidators

        public final java.util.List<IValidator<? super T>> getValidators()
        Gets an unmodifiable list of validators for this FormComponent.
        Returns:
        List of validators

      • getValue

        public final java.lang.String getValue()
        Gets current value for a form component, which can be either input data entered by the user, or the component's model object if no input was provided.
        Returns:
        The value

      • hasRawInput

        public final boolean hasRawInput()
        Returns whether this component has raw input. Raw input is unconverted input straight from the client.
        Returns:
        boolean whether this component has raw input.

      • inputChanged

        public final void inputChanged()
        Used by Form to tell the FormComponent that a new user input is available

      • invalid

        public final void invalid()
        Indicate that validation of this form component failed.

      • isInputNullable

        public boolean isInputNullable()
        Gets whether this component's input can be null. By default, components that do not get input will have null values passed in for input. However, component TextField is an example (possibly the only one) that never gets a null passed in, even if the field is left empty UNLESS it had attribute disabled="disabled" set.
        Returns:
        True if this component's input can be null. Returns true by default.

      • isMultiPart

        public boolean isMultiPart()
        Returns:
        True if this component encodes data in a multipart form submit

      • isRequired

        public boolean isRequired()
        Returns:
        whether or not this component's value is required

      • isValid

        public final boolean isValid()
        Gets whether this component is 'valid'. Valid in this context means that no validation errors were reported the last time the form component was processed. This variable not only is convenient for 'business' use, but is also necessary as we don't want the form component models updated with invalid input.
        Returns:
        valid whether this component is 'valid'

      • processInput

        public final void processInput()
        This method will retrieve the request parameter, validate it, and if valid update the model. These are the same steps as would be performed by the form. This is useful when a formcomponent is used outside a form.

      • setLabel

        public FormComponent<T> setLabel​(IModel<java.lang.String> labelModel)
        The value will be made available to the validator property by means of ${label}. It does not have any specific meaning to FormComponent itself.
        Overrides:
        setLabel in class LabeledWebMarkupContainer
        Parameters:
        labelModel -
        Returns:
        this for chaining

      • setModelValue

        public void setModelValue​(java.lang.String[] value)
        Sets the value for a form component.
        Parameters:
        value - The value

      • setRequired

        public final FormComponent<T> setRequired​(boolean required)
        Sets the required flag
        Parameters:
        required -
        Returns:
        this for chaining

      • setType

        public FormComponent<T> setType​(java.lang.Class<?> type)
        Sets the type that will be used when updating the model for this component. If no type is specified String type is assumed.
        Parameters:
        type -
        Returns:
        this for chaining

      • updateModel

        public void updateModel()
        Updates this components model from the request, it expects that the object is already converted through the convertInput() call that is called by the validate() method when a form is being processed. By default it just does this: 
         setModelObject(getConvertedInput());
        DO NOT CALL THIS METHOD DIRECTLY UNLESS YOU ARE SURE WHAT YOU ARE DOING. USUALLY UPDATING YOUR MODEL IS HANDLED BY THE FORM, NOT DIRECTLY BY YOU.
        Specified by:
        updateModel in interface IFormModelUpdateListener

      • valid

        public final void valid()
        Called to indicate that the user input is valid.

      • validate

        public void validate()
        Performs full validation of the form component, which consists of calling validateRequired(), convertInput(), and validateValidators(). This method should only be used if the form component needs to be fully validated outside the form process.

      • newValidationError

        protected ValidationError newValidationError​(org.apache.wicket.util.convert.ConversionException cause)
        This method is called, when the validation triggered by convertInput() failed with a ConversionException, to construct a ValidationError based on the exception.

        Override this method to modify the ValidationError object, e.g. add a custom variable for message substitution: 

         new FormComponent<T>(id)
 {
        protected ValidationError newValidationError(ConversionException cause)
        {
                return super.newValidationError(cause).setVariable("foo", foovalue);
        }
 };
        Parameters:
        cause - the original cause
        Returns:
        ValidationError

      • convertValue

        protected T convertValue​(java.lang.String[] value)
                  throws org.apache.wicket.util.convert.ConversionException
        Subclasses should overwrite this if the conversion is not done through the type field and the IConverter. WARNING: this method may be removed in future versions. If conversion fails then a ConversionException should be thrown
        Parameters:
        value - The value can be the getInput() or through a cookie
        Returns:
        The converted value. default returns just the given value
        Throws:
        org.apache.wicket.util.convert.ConversionException - If input can't be converted

      • getModelValue

        protected java.lang.String getModelValue()
        Returns:
        Value to return when model value is needed

      • inputAsInt

        protected final int inputAsInt()
        Gets the request parameter for this component as an int.
        Returns:
        The value in the request for this component

      • inputAsInt

        protected final int inputAsInt​(int defaultValue)
        Gets the request parameter for this component as an int, using the given default in case no corresponding request parameter was found.
        Parameters:
        defaultValue - Default value to return if request does not have an integer for this component
        Returns:
        The value in the request for this component

      • inputAsIntArray

        protected final int[] inputAsIntArray()
        Gets the request parameters for this component as ints.
        Returns:
        The values in the request for this component

      • onDisabled

        protected void onDisabled​(ComponentTag tag)
        Called by onComponentTag(ComponentTag) when the component is disabled. By default, this method will add a disabled="disabled" attribute to the tag. Components may override this method to tweak the tag as they think is fit.
        Parameters:
        tag - the tag that is being rendered

      • onInvalid

        protected void onInvalid()
        Handle invalidation

      • onValid

        protected void onValid()
        Handle validation

      • shouldTrimInput

        protected boolean shouldTrimInput()
        Determines whether or not this component should trim its input prior to processing it. The default value is true
        Returns:
        True if the input should be trimmed.

      • trim

        protected java.lang.String trim​(java.lang.String string)
        Trims the input according to shouldTrimInput()
        Parameters:
        string -
        Returns:
        trimmed input if shouldTrimInput() returns true, unchanged input otherwise

      • validateRequired

        protected final void validateRequired()
        Checks if the raw input value is not null if this component is required.

      • reportRequiredError

        protected void reportRequiredError()
        Reports required error against this component

      • validateValidators

        protected final void validateValidators()
        Validates this component using the component's validators.

      • newValidatable

        public final IValidatable<T> newValidatable()
        Creates an IValidatable that can be used to validate this form component. This validatable incorporates error key lookups that correspond to this form component. This method is useful when validation needs to happen outside the regular validation workflow but error messages should still be properly reported against the form component.
        Returns:
        IValidatable for this form component

      • updateAutoLabels

        public final void updateAutoLabels​(AjaxRequestTarget target)
        Updates auto label css classes such as error/required during ajax updates when the labels may not be directly repainted in the response.
        Parameters:
        target -

      • updateCollectionModel

        public static <S> void updateCollectionModel​(FormComponent<java.util.Collection<S>> formComponent)
        Update the model of a FormComponent containing a Collection. If the model object does not yet exists, a new suitable collection is filled with the converted input and used as the new model object. Otherwise the existing collection is modified in-place, then IModel.setObject(Object) is called with the same instance: it allows the Model to be notified of changes even when Model.getObject() returns a different Collection at every invocation.
        Type Parameters:
        S - collection type
        Parameters:
        formComponent - the form component to update
        Throws:
        WicketRuntimeException - if the existing model object collection is unmodifiable and no setter exists
        See Also:
        updateModel()