|
|||||||||
| Home >> All >> org >> apache >> tapestry >> [ valid overview ] | PREV CLASS NEXT CLASS | ||||||||
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD |
DETAIL: FIELD | CONSTR | METHOD | ||||||||
org.apache.tapestry.valid
Interface IValidationDelegate
- All Known Implementing Classes:
- ValidationDelegate
- public interface IValidationDelegate
Interface used to track validation errors in forms and org.apache.tapestry.form.IFormComponents (including org.apache.tapestry.form.AbstractTextField and its subclasses).
In addition, controls how fields that are in error are presented (they can be marked in various ways by the delegate; the default implementation adds two red asterisks to the right of the field).
The interface is designed so that a single instance can be shared with many instances of org.apache.tapestry.form.IFormComponent.
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 (with any field) errors to be tracked.
Fields vs. Form Components
For most simple forms, these terms are pretty much synonymous.
Your form will render normally, and each form 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 org.apache.tapestry.components.Foreach or
org.apache.tapestry.form.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 (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 IForm.getElementId(org.apache.tapestry.form.IFormComponent)>IForm.getElementId(org.apache.tapestry.form.IFormComponent) 55 .
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 55 . So if the form component is in any kind of loop, the FieldLabel will key its name, display name 55 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. |
java.lang.String |
getFieldInputValue()
Returns the string submitted by the client as the value for the current field. |
java.util.List |
getFieldTracking()
Returns a java.util.List of IFieldTracking, in default order (the order in which fields are renderred). |
boolean |
getHasErrors()
Returns true if any form component has errors. |
boolean |
isInError()
Returns true if the current component is in error (that is, had bad input submitted by the end user). |
void |
record(org.apache.tapestry.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 |
reset()
Resets any tracking information for the current field. |
void |
setFormComponent(org.apache.tapestry.form.IFormComponent component)
Invoked before other methods to configure the delegate for the given form component. |
void |
writeAttributes(org.apache.tapestry.IMarkupWriter writer,
org.apache.tapestry.IRequestCycle cycle,
org.apache.tapestry.form.IFormComponent component,
IValidator validator)
Invoked just before the <input> element is closed. |
void |
writeLabelPrefix(org.apache.tapestry.form.IFormComponent component,
org.apache.tapestry.IMarkupWriter writer,
org.apache.tapestry.IRequestCycle cycle)
Invoked by a FieldLabel just before writing the name of the form component. |
void |
writeLabelSuffix(org.apache.tapestry.form.IFormComponent component,
org.apache.tapestry.IMarkupWriter writer,
org.apache.tapestry.IRequestCycle cycle)
Invoked by a FieldLabel just after writing the name of the form component. |
void |
writePrefix(org.apache.tapestry.IMarkupWriter writer,
org.apache.tapestry.IRequestCycle cycle,
org.apache.tapestry.form.IFormComponent component,
IValidator validator)
Invoked before the field is rendered. |
void |
writeSuffix(org.apache.tapestry.IMarkupWriter writer,
org.apache.tapestry.IRequestCycle cycle,
org.apache.tapestry.form.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 |
setFormComponent
public void setFormComponent(org.apache.tapestry.form.IFormComponent component)
- Invoked before other methods to configure the delegate for the given
form component. Sets the current field based on
the name 55 of the form component
(which is almost always a ValidField).
The caller should invoke this with a parameter of null to record unassociated global errors (errors not associated with any particular field).
- Since:
- 1.0.8
isInError
public boolean isInError()
- Returns true if the current component is in error (that is, had bad input
submitted by the end user).
- Since:
- 1.0.8
getFieldInputValue
public java.lang.String getFieldInputValue()
- Returns the string submitted by the client as the value for
the current field.
- Since:
- 1.0.8
getFieldTracking
public java.util.List getFieldTracking()
- Returns a java.util.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.
- Since:
- 1.0.8
reset
public void reset()
- Resets any tracking information for the current field. This will
clear the field's inError flag, and set its error message and invalid input value
to null.
- Since:
- 1.0.8
clear
public void clear()
- Clears all tracking information.
- Since:
- 1.0.10
recordFieldInputValue
public void recordFieldInputValue(java.lang.String input)
- Records the user's input for the current form component. Input should
be recorded even if there isn't an explicit error, since later form-wide
validations may discover an error in the field.
- Since:
- 3.0
record
public 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).
Typically, the delegate simply invokes
record(String, ValidationConstraint)55 orrecord(IRender, ValidationConstraint)55 , but special delegates may override this behavior to provide (in some cases) different error messages or more complicated error renderers.
record
public 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.
- Since:
- 1.0.9
record
public void record(org.apache.tapestry.IRender errorRenderer, ValidationConstraint constraint)
- Records an error in the current component, or an unassociated error.
The maximum flexibility recorder.
writePrefix
public void writePrefix(org.apache.tapestry.IMarkupWriter writer, org.apache.tapestry.IRequestCycle cycle, org.apache.tapestry.form.IFormComponent component, IValidator validator)
- Invoked before the field is rendered. If the field is in error,
the delegate may decorate the field in some way (to highlight its
error state).
writeAttributes
public void writeAttributes(org.apache.tapestry.IMarkupWriter writer, org.apache.tapestry.IRequestCycle cycle, org.apache.tapestry.form.IFormComponent component, IValidator validator)
- Invoked just before the <input> element is closed.
The delegate can write additional attributes. This is often used
to set the CSS class of the field so that it can be displayed
differently, if in error (or required).
- Since:
- 1.0.5
writeSuffix
public void writeSuffix(org.apache.tapestry.IMarkupWriter writer, org.apache.tapestry.IRequestCycle cycle, org.apache.tapestry.form.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).
writeLabelPrefix
public void writeLabelPrefix(org.apache.tapestry.form.IFormComponent component, org.apache.tapestry.IMarkupWriter writer, org.apache.tapestry.IRequestCycle cycle)
- Invoked by a FieldLabel just before writing the name
of the form component.
writeLabelSuffix
public void writeLabelSuffix(org.apache.tapestry.form.IFormComponent component, org.apache.tapestry.IMarkupWriter writer, org.apache.tapestry.IRequestCycle cycle)
- Invoked by a FieldLabel just after writing the name
of the form component.
getHasErrors
public boolean getHasErrors()
- Returns true if any form component has errors.
|
|||||||||
| Home >> All >> org >> apache >> tapestry >> [ valid overview ] | PREV CLASS NEXT CLASS | ||||||||
|
SUMMARY: JAVADOC | SOURCE | DOWNLOAD | NESTED | FIELD | CONSTR | METHOD |
DETAIL: FIELD | CONSTR | METHOD | ||||||||