wicket.markup.html.form
Class FormComponent

java.lang.Object
  extended by wicket.Component
      extended by wicket.MarkupContainer
          extended by wicket.markup.html.WebMarkupContainer
              extended by wicket.markup.html.form.FormComponent
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
AbstractTextComponent, Button, CheckBox, CheckGroup, DropDownChoice, FileUploadField, ListMultipleChoice, RadioChoice, RadioGroup

public abstract class FormComponent
extends WebMarkupContainer

An HTML form component knows how to validate itself. Validators that implement IValidator can be added to the component. They will be evaluated in the order they were added and the first Validator that returns an error message determines the error message returned by the component.

FormComponents are not versioned by default. If you need versioning for your FormComponents, you will need to call Form.setVersioned(true), which will set versioning on for the form and all form component children.

If this component is required and that fails, the error key that is used is the "RequiredValidator"; if the type conversion fails, it will use the key "TypeValidator". The keys that can be used in both are:

Author:
Jonathan Locke, Eelco Hillenius, Johan Compagner, Igor Vaynberg (ivaynberg)
See Also:
Serialized Form

Nested Class Summary
static interface FormComponent.IVisitor
          Typesafe interface to code that is called when visiting a form component.
 
Nested classes/interfaces inherited from class wicket.Component
Component.ComponentModelChange, Component.EnabledChange, Component.VisibilityChange
 
Field Summary
protected static short FLAG_CONVERT_EMPTY_INPUT_STRING_TO_NULL
          Make empty strings null values boolean.
static java.lang.String VALUE_SEPARATOR
          The value separator
 
Fields inherited from class wicket.Component
ENABLE, FLAG_RESERVED1, FLAG_RESERVED2, FLAG_RESERVED3, FLAG_RESERVED4, FLAG_RESERVED5, FLAG_RESERVED6, FLAG_RESERVED7, FLAG_RESERVED8, PATH_SEPARATOR, RENDER
 
Constructor Summary
FormComponent(java.lang.String id)
           
FormComponent(java.lang.String id, IModel model)
           
 
Method Summary
 FormComponent add(IValidator validator)
          Adds a validator to this form component.
 boolean checkRequired()
          Checks if the form component's 'required' requirement is met
 void clearInput()
          Clears the user input.
protected  void convert()
          Converts and validates the conversion of the raw input string into the object specified by getType() and records any errors.
protected  java.lang.Object convertValue(java.lang.String[] value)
          Subclasses should overwrite this if the conversion is not done through the type field and the IConverter.
 void error(java.util.List resourceKeys, java.util.Map args)
          Builds and reports an error message.
 java.lang.Object getConvertedInput()
           
 Form getForm()
           
 java.lang.String getInput()
          Gets the request parameter for this component as a string.
 java.lang.String[] getInputAsArray()
          Gets the request parameters for this component as strings.
 java.lang.String getInputName()
          Gets the string to be used for the name attribute of the form element.
 IModel getLabel()
          The value will be made available to the validator property by means of ${label}.
protected  java.lang.String getModelValue()
           
 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.
 java.lang.Class getType()
           
 java.lang.String getValidatorKeyPrefix()
           
 java.util.List getValidators()
          Gets an unmodifiable list of validators for this FormComponent.
 java.lang.String getValue()
          Gets current value for a form component.
 boolean hasRawInput()
          This method can be called to know if this component really has raw input.
protected  int inputAsInt()
          Gets the request parameter for this component as an int.
protected  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.
protected  int[] inputAsIntArray()
          Gets the request parameters for this component as ints.
protected  java.lang.String[] inputAsStringArray()
          Deprecated. Use getInputAsArray() instead
 void inputChanged()
          Used by Form to tell the FormComponent that a new user input is available
protected  void internalOnModelChanged()
          THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
 void invalid()
          Called to indicate that
 boolean isInputNullable()
          Gets whether this component's input can be null.
 boolean isMultiPart()
           
 boolean isPersistent()
           
 boolean isRequired()
           
 boolean isValid()
          Gets whether this component is 'valid'.
 boolean isValidated()
          Gets whether this component is to be validated.
protected  void onComponentTag(ComponentTag tag)
          Processes the component tag.
protected  void onDetach()
          Called to allow a component to detach resources after use.
protected  void onDisabled(ComponentTag tag)
          Called by onComponentTag(ComponentTag) when the component is disabled.
protected  void onInvalid()
          Handle invalidation
protected  void onValid()
          Handle validation
 void processInput()
          This method will retrieve the request parameter, validate it, and if valid update the model.
 FormComponent setLabel(IModel labelModel)
          The value will be made available to the validator property by means of ${label}.
 void setModelValue(java.lang.String value)
          Sets the value for a form component this value will be split the string with VALUE_SEPARATOR and calls setModelValue(String[]) with that.
 void setModelValue(java.lang.String[] value)
          Sets the value for a form component.
 FormComponent setPersistent(boolean persistent)
          Sets whether this component is to be persisted.
 FormComponent setRequired(boolean required)
          Sets the required flag
 FormComponent setType(java.lang.Class type)
          Sets the type that will be used when updating the model for this component.
protected  boolean supportsPersistence()
           
 void updateModel()
          Updates this components' model from the request, it expect that the object is already converted through the convert() call.
 void valid()
          Called to indicate that the user input is valid.
 void validate()
          Performs full validation of the form component, which consists of calling validateRequired(), validateTypeConversion(), and validateValidators().
protected  void validateRequired()
          Checks if the raw input value is not null if this component is required
protected  void validateValidators()
          Validates this component using the component's validators.
 
Methods inherited from class wicket.markup.html.WebMarkupContainer
getMarkupType, getWebPage
 
Methods inherited from class wicket.MarkupContainer
add, autoAdd, contains, findMarkupStream, get, getAssociatedMarkupStream, getMarkupStream, internalAdd, internalAttach, internalDetach, isTransparentResolver, iterator, iterator, newMarkupResourceStream, onComponentTagBody, onRender, remove, remove, removeAll, renderAll, renderAssociatedMarkup, renderComponentTagBody, replace, setMarkupStream, setModel, size, toString, toString, visitChildren, visitChildren
 
Methods inherited from class wicket.Component
add, addStateChange, checkComponentTag, checkComponentTagAttribute, continueToOriginalDestination, debug, detachBehaviors, detachModel, detachModels, error, exceptionMessage, fatal, findPage, findParent, findParentWithAssociatedMarkup, getApplication, getApplicationPages, getApplicationSettings, getBehaviors, getBehaviors, getClassRelativePath, getConverter, getEscapeModelStrings, getFeedbackMessage, getFlag, getFlag, getId, getLocale, getLocalizer, getMarkupAttributes, getMarkupId, getMetaData, getModel, getModelComparator, getModelObject, getModelObjectAsString, getOutputMarkupId, getPage, getPageFactory, getPageRelativePath, getParent, getPath, getRenderBodyOnly, getRequest, getRequestCycle, getResponse, getSession, getSizeInBytes, getString, getString, getString, getStyle, getVariation, hasErrorMessage, hasFeedbackMessage, info, initModel, internalOnAttach, internalOnDetach, isActionAuthorized, isAncestorOf, isBehaviorAccepted, isEnableAllowed, isEnabled, isHeadRendered, isIgnoreAttributeModifier, isRenderAllowed, isVersioned, isVisible, isVisibleInHierarchy, modelChanged, modelChanging, newPage, newPage, onAfterRender, onAttach, onBeforeRender, onBeginRequest, onEndRequest, onModelChanged, onModelChanging, onRender, redirectToInterceptPage, remove, render, render, renderComponent, renderComponent, renderComponentTag, rendered, renderedBehaviors, renderHead, replaceComponentTagBody, replaceWith, resetHeadRendered, sameRootModel, sameRootModel, setAuto, setEnabled, setEscapeModelStrings, setFlag, setFlag, setIgnoreAttributeModifier, setMetaData, setModelObject, setOutputMarkupId, setRedirect, setRenderBodyOnly, setResponsePage, setResponsePage, setResponsePage, setVersioned, setVisible, urlFor, urlFor, urlFor, urlFor, urlFor, visitParents, warn
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

VALUE_SEPARATOR

public static java.lang.String VALUE_SEPARATOR
The value separator


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
Constructor Detail

FormComponent

public FormComponent(java.lang.String id)
See Also:
Component.Component(String)

FormComponent

public FormComponent(java.lang.String id,
                     IModel model)
See Also:
Component.Component(String, IModel)
Method Detail

add

public final FormComponent add(IValidator validator)
Adds a validator to this form component.

Parameters:
validator - The validator
Returns:
This

checkRequired

public final boolean checkRequired()
Checks if the form component's 'required' requirement is met

Returns:
true if the 'required' requirement is met, false otherwise

clearInput

public final void clearInput()
Clears the user input.


error

public final void error(java.util.List resourceKeys,
                        java.util.Map args)
Builds and reports an error message. Typically called from a validator.

This function will iterate over the list of resource keys and try to find a resource message that matches. Each key is first tried verbatim, and then a key of form prefix.key is tried; prefix comes from getValidatorKeyPrefix().

If a message is found, any variables in it with form ${varname} will be interpolated given the arguments in the args parameter.

This method will add a few default arguments to the args map if they are not already present:

Parameters:
resourceKeys - list of resource keys to try
args - argument substituion map with format map:varname->varvalue

getConvertedInput

public final java.lang.Object getConvertedInput()
Returns:
value of input converted into appropriate type if any was set

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

getLabel

public IModel getLabel()
The value will be made available to the validator property by means of ${label}. It does not have any specific meaning to FormComponent itself.

Returns:
labelModel

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 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 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.

Returns:
The value

hasRawInput

public final boolean hasRawInput()
This method can be called to know if this component really has raw input.

Returns:
boolean if this form component has rawinput.

inputChanged

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


invalid

public final void invalid()
Called to indicate that


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

isPersistent

public final boolean isPersistent()
Returns:
True if this component supports persistence AND it has been asked to persist itself with setPersistent().

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 nescesarry as we don't want the form component models updated with invalid input.

Returns:
valid whether this component is 'valid'

isValidated

public final boolean isValidated()
Gets whether this component is to be validated.

Returns:
True if this component has one or more validators

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 setLabel(IModel 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.

Parameters:
labelModel -
Returns:
this for chaining

setModelValue

public void setModelValue(java.lang.String value)
Sets the value for a form component this value will be split the string with VALUE_SEPARATOR and calls setModelValue(String[]) with that.

Parameters:
value - The value

setModelValue

public void setModelValue(java.lang.String[] value)
Sets the value for a form component.

Parameters:
value - The value

setPersistent

public final FormComponent setPersistent(boolean persistent)
Sets whether this component is to be persisted.

Parameters:
persistent - True if this component is to be persisted.
Returns:
this for chaining

setRequired

public final FormComponent setRequired(boolean required)
Sets the required flag

Parameters:
required -
Returns:
this for chaining

setType

public final FormComponent 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 expect that the object is already converted through the convert() call. 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.


valid

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


validate

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


convert

protected final void convert()
Converts and validates the conversion of the raw input string into the object specified by getType() and records any errors. Converted value is available thorugh getConvertedInput()


convertValue

protected java.lang.Object convertValue(java.lang.String[] value)
                                 throws 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:
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

inputAsStringArray

protected final java.lang.String[] inputAsStringArray()
Deprecated. Use getInputAsArray() instead

Gets the request parameters for this component as strings.

Returns:
The values in the request for this component

internalOnModelChanged

protected void internalOnModelChanged()
Description copied from class: Component
THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT CALL OR OVERRIDE. Called anytime a model is changed via setModel or setModelObject.

Overrides:
internalOnModelChanged in class Component
See Also:
Component.internalOnModelChanged()

onComponentTag

protected void onComponentTag(ComponentTag tag)
Processes the component tag.

Overrides:
onComponentTag in class Component
Parameters:
tag - Tag to modify
See Also:
Component.onComponentTag(ComponentTag)

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

onDetach

protected void onDetach()
Description copied from class: Component
Called to allow a component to detach resources after use. The semantics of this will be tightened in Wicket 1.3 when we will add the guarantee that onDetach() be called after all framework use of a Component (in the implementation of request targets).

Overrides:
onDetach in class Component

onInvalid

protected void onInvalid()
Handle invalidation


onValid

protected void onValid()
Handle validation


supportsPersistence

protected boolean supportsPersistence()
Returns:
True if this type of FormComponent can be persisted.

validateRequired

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


validateValidators

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



Copyright © 2004-2007 Wicket developers. All Rights Reserved.