org.apache.tapestry.valid
Interface IValidationDelegate

All Superinterfaces:

Serializable

All Known Implementing Classes:

ValidationDelegate

public interface IValidationDelegate
extends Serializable

Interface used to track validation errors in forms and form element components (including TextField 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 ForBean 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 FieldLabelwill key its name, display name and error status off of its last renderred value. So the moral of the story is don't use FieldLabelin this situation.

Author:

Howard Lewis Ship

Method Summary

void	afterLabelText(IMarkupWriter writer, IRequestCycle cycle, IFormComponent component) Invoked just before the closing </label> tag is written.
void	beforeLabelText(IMarkupWriter writer, IRequestCycle cycle, IFormComponent component) Invoked just before the actual field label text is written, right after all attributes and informal parameters are done being printed on the <label> tag.
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.
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).
String	getFieldInputValue() Returns the string submitted by the client as the value for the current field.
List	getFieldTracking() Returns a List of IFieldTracking, in default order (the order in which fields are renderred).
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, 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(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(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

setFormComponent

void setFormComponent(IFormComponent component)

Invoked before other methods to configure the delegate for the given form component. Sets the current field based on the 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).

Since:

1.0.8

isInError

boolean isInError()

Returns true if the current field is in error (that is, had bad input submitted by the end user).

Since:

1.0.8

getFieldInputValue

String getFieldInputValue()

Returns the string submitted by the client as the value for the current field.

Since:

1.0.8

getFieldTracking

List getFieldTracking()

Returns a 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

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

void clear()

Clears all tracking information.

Since:

1.0.10

clearErrors

void clearErrors()

Clears all errors, but maintains user input. This is useful when a form has been submitted for a semantic other than "process this data". A common example of this is a dependent drop down list; selecting an option in one drop down list forces a refresh submit of the form, to repopulate the options in a second, dependent drop down list.

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

Since:

3.0.1

recordFieldInputValue

void recordFieldInputValue(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

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)or record(IRender, ValidationConstraint), but special delegates may override this behavior to provide (in some cases) different error messages or more complicated error renderers.

record

void record(String message,
            ValidationConstraint constraint)

Records an error in the current field, or an unassociated error if there is no current field.

Parameters:

message - message to display (@see RenderString}

constraint - the constraint that was violated, or null if not known

Since:

1.0.9

record

void record(IFormComponent field,
            String message)

Convienience for recording a standard string messages against a field.

Parameters:

field - the field to record the error message against, or null to record an unassociated error

message - the error message to record

Since:

4.0

record

void record(IRender errorRenderer,
            ValidationConstraint constraint)

Records an error in the current component, or an unassociated error. The maximum flexibility recorder.

Parameters:

errorRenderer - object that will render the error message (@see RenderString}

constraint - the constraint that was violated, or null if not known

writePrefix

void writePrefix(IMarkupWriter writer,
                 IRequestCycle cycle,
                 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).

Parameters:

writer - the writer to which output should be sent

cycle - the active request cycle

component - the component being decorated

validator - the validator for the component, or null if the component does have (or doesn't support) a validator

writeAttributes

void writeAttributes(IMarkupWriter writer,
                     IRequestCycle cycle,
                     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). *

Parameters:

writer - the writer to which output should be sent

cycle - the active request cycle

component - the component being decorated

validator - the validator for the component, or null if the component does have (or doesn't support) a validator

Since:

1.0.5

writeSuffix

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

Parameters:

writer - the writer to which output should be sent

cycle - the active request cycle

component - the component being decorated

validator - the validator for the component, or null if the component does have (or doesn't support) a validator

writeLabelPrefix

void writeLabelPrefix(IFormComponent component,
                      IMarkupWriter writer,
                      IRequestCycle cycle)

Invoked by a FieldLabel just before writing the name of the form component.

writeLabelAttributes

void writeLabelAttributes(IMarkupWriter writer,
                          IRequestCycle cycle,
                          IFormComponent component)

Invoked just before the <label> element is closed. The delegate can write additional attributes. This is often used to set the CSS class of the label so that it can be displayed differently, if in error (or required). Any attributes written here will be overriden by any informal parameters specified in the FieldLabel implementation.

Parameters:

writer - the writer to which output should be sent

cycle - the active request cycle

component - the component field that label decorates

Since:

4.0.1

beforeLabelText

void beforeLabelText(IMarkupWriter writer,
                     IRequestCycle cycle,
                     IFormComponent component)

Invoked just before the actual field label text is written, right after all attributes and informal parameters are done being printed on the <label> tag.

Example, writing content would go here:

<label class="error"> >>here<< LABEL TEXT </label>

Parameters:

writer - The writer to use.

cycle - Current request cycle.

component - Field label is bound to.

afterLabelText

void afterLabelText(IMarkupWriter writer,
                    IRequestCycle cycle,
                    IFormComponent component)

Invoked just before the closing </label> tag is written.

Example, writing content would go here:

<label class="error"> LABEL TEXT >>here<< </label>

Parameters:

writer - The writer to use.

cycle - Current request cycle.

component - Field label is bound to.

writeLabelSuffix

void writeLabelSuffix(IFormComponent component,
                      IMarkupWriter writer,
                      IRequestCycle cycle)

Invoked by a FieldLabel just after writing the name of the form component.

getHasErrors

boolean getHasErrors()

Returns true if any form component has errors.

getCurrentFieldTracking

IFieldTracking getCurrentFieldTracking()

Returns the IFieldTracking for the current component, if any. Useful when displaying error messages for individual fields.

Since:

3.0.2

getErrorRenderers

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). These objects can be rendered or converted to a string (via toString()).

Returns:

non-empty List of IRender.

registerForFocus

void registerForFocus(IFormComponent field,
                      int priority)

Registers a field for automatic focus. The goal is for the first field that is in error to get focus; failing that, the first required field; failing that, any field.

Parameters:

field - the field requesting focus

priority - a priority level used to determine whether the registered field becomes the focus field. Constants for this purpose are defined in ValidationConstants.

Since:

4.0

getFocusField

String getFocusField()

Returns the field to focus upon, based on prior calls to registerForFocus(IFormComponent, int).

Returns:

the field name, or null if no field should receive focus.

Since:

4.0