|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Interface used to track validation errors in forms and
form element component
s (including
org.apache.tapestry.form.AbstractTextField
and its subclasses).
In addition, controls how fields that are in error are presented (they can be decorated in various ways by the delegate; the default implementation adds two red asterisks to the right of the field).
Each Form
must have its own validation delegate instance.
Starting with release 1.0.8, this interface was extensively revised (in a non-backwards compatible way) to move the tracking of errors and invalid values (during a request cycle) to the delegate. It has evolved from a largely stateless conduit for error messages into a very stateful tracker of field state.
Starting with release 1.0.9, this interface was again reworked, to allow tracking of
errors in form components
, and to allow unassociated errors to be
tracked. Unassociated errors are "global", they don't apply to any particular field.
Fields vs. Form Element Components
For most simple forms, these terms are pretty much synonymous. Your form will render normally,
and each form element component will render only once. Some of your form components will be
ValidField
components and handle most of their validation internally (with the help
of IValidator
objects). In addition, your form listener may do additional
validation and notify the validation delegate of additional errors, some of which are associated
with a particular field, some of which are unassociated with any particular field.
But what happens if you use a Foreach
or
ListEdit
inside your form? Some of your components will
render multiple times. In this case you will have multiple fields. Each field will
have a unique field name (the
element id
, which you
can see this in the generated HTML). It is this field name that the delegate keys off of, which
means that some fields generated by a component may have errors and some may not, it all works
fine (with one exception).
The Exception
The problem is that a component doesn't know its field name until its render()
method is invoked (at which point, it allocates a unique field name from the
FormBehavior.getElementId(org.apache.tapestry.form.IFormComponent)
. This is
not a problem for the field or its IValidator
, but screws things up for the
FieldLabel
.
Typically, the label is rendered before the corresponding form component. Form
components leave their last assigned field name in their
name property
. So if the form component is in any kind of loop,
the FieldLabel
will key its name, display name
and error status off of its last renderred value. So the moral of the story is don't use
FieldLabel
in this situation.
Method Summary | |
void |
clear()
Clears all tracking information. |
void |
clearErrors()
Clears all errors, but maintains user input. |
IFieldTracking |
getCurrentFieldTracking()
Returns the IFieldTracking for the current component, if any. |
java.util.List |
getErrorRenderers()
Returns a list of IRender objects, each of which will render an
error message for a field tracked by the delegate, plus any unassociated errors (for which no
specific field is identified). |
java.lang.String |
getFieldInputValue()
Returns the string submitted by the client as the value for the current field. |
java.util.List |
getFieldTracking()
Returns a List of IFieldTracking , in default order (the order in which
fields are renderred). |
java.lang.String |
getFocusField()
Returns the field to focus upon, based on prior calls to registerForFocus(IFormComponent, int) . |
boolean |
getHasErrors()
Returns true if any form component has errors. |
boolean |
isInError()
Returns true if the current field is in error (that is, had bad input submitted by the end user). |
void |
record(IFormComponent field,
java.lang.String message)
Convienience for recording a standard string messages against a field. |
void |
record(IRender errorRenderer,
ValidationConstraint constraint)
Records an error in the current component, or an unassociated error. |
void |
record(java.lang.String message,
ValidationConstraint constraint)
Records an error in the current field, or an unassociated error if there is no current field. |
void |
record(ValidatorException ex)
The error notification method, invoked during the rewind phase (that is, while HTTP parameters are being extracted from the request and assigned to various object properties). |
void |
recordFieldInputValue(java.lang.String input)
Records the user's input for the current form component. |
void |
registerForFocus(IFormComponent field,
int priority)
Registers a field for automatic focus. |
void |
reset()
Resets any tracking information for the current field. |
void |
setFormComponent(IFormComponent component)
Invoked before other methods to configure the delegate for the given form component. |
void |
writeAttributes(IMarkupWriter writer,
IRequestCycle cycle,
IFormComponent component,
IValidator validator)
Invoked just before the <input> element is closed. |
void |
writeLabelAttributes(IMarkupWriter writer,
IRequestCycle cycle,
IFormComponent component)
Invoked just before the <label> element is closed. |
void |
writeLabelPrefix(IFormComponent component,
IMarkupWriter writer,
IRequestCycle cycle)
Invoked by a FieldLabel just before writing the name of the form component. |
void |
writeLabelSuffix(IFormComponent component,
IMarkupWriter writer,
IRequestCycle cycle)
Invoked by a FieldLabel just after writing the name of the form component. |
void |
writePrefix(IMarkupWriter writer,
IRequestCycle cycle,
IFormComponent component,
IValidator validator)
Invoked before the field is rendered. |
void |
writeSuffix(IMarkupWriter writer,
IRequestCycle cycle,
IFormComponent component,
IValidator validator)
Invoked after the form component is rendered, so that the delegate may decorate the form component (if it is in error). |
Method Detail |
public void setFormComponent(IFormComponent component)
name
of the form component.
The caller should invoke this with a parameter of null to record unassociated global errors (errors not associated with any particular field).
public boolean isInError()
public java.lang.String getFieldInputValue()
public java.util.List getFieldTracking()
List
of IFieldTracking
, in default order (the order in which
fields are renderred). A caller should not change the values (the List is immutable). May
return null if no fields are in error.
public void reset()
public void clear()
public void clearErrors()
In these cases, the user input provided in the request is maintained, but any errors should be cleared out (to prevent unwanted error messages and decorations).
public void recordFieldInputValue(java.lang.String input)
public void record(ValidatorException ex)
Typically, the delegate simply invokes record(String, ValidationConstraint)
or
record(IRender, ValidationConstraint)
, but special delegates may override this
behavior to provide (in some cases) different error messages or more complicated error
renderers.
public void record(java.lang.String message, ValidationConstraint constraint)
message
- message to display (@see RenderString}constraint
- the constraint that was violated, or null if not knownpublic void record(IFormComponent field, java.lang.String message)
field
- the field to record the error message against, or null to record an unassociated
errormessage
- the error message to recordpublic void record(IRender errorRenderer, ValidationConstraint constraint)
errorRenderer
- object that will render the error message (@see RenderString}constraint
- the constraint that was violated, or null if not knownpublic void writePrefix(IMarkupWriter writer, IRequestCycle cycle, IFormComponent component, IValidator validator)
writer
- the writer to which output should be sentcycle
- the active request cyclecomponent
- the component being decoratedvalidator
- the validator for the component, or null if the component does have (or doesn't
support) a validatorpublic void writeAttributes(IMarkupWriter writer, IRequestCycle cycle, IFormComponent component, IValidator validator)
writer
- the writer to which output should be sentcycle
- the active request cyclecomponent
- the component being decoratedvalidator
- the validator for the component, or null if the component does have (or doesn't
support) a validatorpublic void writeSuffix(IMarkupWriter writer, IRequestCycle cycle, IFormComponent component, IValidator validator)
writer
- the writer to which output should be sentcycle
- the active request cyclecomponent
- the component being decoratedvalidator
- the validator for the component, or null if the component does have (or doesn't
support) a validatorpublic void writeLabelPrefix(IFormComponent component, IMarkupWriter writer, IRequestCycle cycle)
FieldLabel
just before writing the name of the form component.
public void writeLabelAttributes(IMarkupWriter writer, IRequestCycle cycle, IFormComponent component)
FieldLabel
implementation.
writer
- the writer to which output should be sentcycle
- the active request cyclecomponent
- the component field that label decoratespublic void writeLabelSuffix(IFormComponent component, IMarkupWriter writer, IRequestCycle cycle)
FieldLabel
just after writing the name of the form component.
public boolean getHasErrors()
public IFieldTracking getCurrentFieldTracking()
IFieldTracking
for the current component, if any. Useful when
displaying error messages for individual fields.
public java.util.List getErrorRenderers()
IRender
objects, each of which will render an
error message for a field tracked by the delegate, plus any unassociated errors (for which no
specific field is identified). These objects can be rendered or converted to a string (via
toString()).
IRender
.public void registerForFocus(IFormComponent field, int priority)
field
- the field requesting focuspriority
- a priority level used to determine whether the registered field becomes the focus
field. Constants for this purpose are defined in ValidationConstants
.public java.lang.String getFocusField()
registerForFocus(IFormComponent, int)
.
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |