org.apache.tapestry.valid
Class ValidationDelegate

java.lang.Object
  org.apache.tapestry.valid.ValidationDelegate

All Implemented Interfaces:

java.io.Serializable, IValidationDelegate

public class ValidationDelegate
extends java.lang.Object
implements IValidationDelegate

A base implementation of IValidationDelegatethat can be used as a managed bean. This class is often subclassed, typically to override presentation details.

Since:

1.0.5

Author:

Howard Lewis Ship

See Also:

Serialized Form

Constructor Summary

ValidationDelegate()

Method Summary

void	clear() Clears all tracking information.
void	clearErrors() Clears all errors, but maintains user input.
protected FieldTracking	findCurrentTracking() Finds or creates the field tracking for the setFormComponent(IFormComponent) current component.
java.util.List	getAssociatedTrackings() Returns a Listof IFieldTrackings.
protected FieldTracking	getComponentTracking() Returns the IFieldTrackingfor the current component, if any.
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 all the field trackings as an unmodifiable List.
IRender	getFirstError() A convienience, as most pages just show the first error on the page.
java.lang.String	getFocusField() Returns the focus field, or null if no form components registered for focus (i.e., they were all disabled).
boolean	getHasErrors() Returns true if any form component has errors.
java.util.List	getUnassociatedTrackings() Like getAssociatedTrackings(), but returns only the unassociated trackings.
boolean	isInError() Returns true if the current field is in error (that is, had bad input submitted by the end user).
protected boolean	isInError(IFormComponent component) Checks to see if the field is in error.
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 error information about the currently selected component, or records unassociated (with any field) errors.
void	record(java.lang.String message, ValidationConstraint constraint) Invokes record(IRender, ValidationConstraint), after wrapping the message parameter in a RenderString.
void	record(ValidatorException ex) Invokes record(String, ValidationConstraint), or record(IRender, ValidationConstraint)if the error renderer propertyis not null.
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) Does nothing.
void	writeLabelAttributes(IMarkupWriter writer, IRequestCycle cycle, IFormComponent component) Does nothing by default.
void	writeLabelPrefix(IFormComponent component, IMarkupWriter writer, IRequestCycle cycle) If the form component is in error, places a <font color="red"< around it.
void	writeLabelSuffix(IFormComponent component, IMarkupWriter writer, IRequestCycle cycle) Closes the <font> element,started by writeLabelPrefix(IFormComponent,IMarkupWriter,IRequestCycle), if the form component is in error.
void	writePrefix(IMarkupWriter writer, IRequestCycle cycle, IFormComponent component, IValidator validator) Does nothing.
void	writeSuffix(IMarkupWriter writer, IRequestCycle cycle, IFormComponent component, IValidator validator) Default implementation; if the current field is in error, then a suffix is written.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ValidationDelegate

public ValidationDelegate()

Method Detail

clear

public void clear()

Description copied from interface: IValidationDelegate

Clears all tracking information.

Specified by:

clear in interface IValidationDelegate

clearErrors

public void clearErrors()

Description copied from interface: IValidationDelegate

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

Specified by:

clearErrors in interface IValidationDelegate

writeLabelPrefix

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

If the form component is in error, places a <font color="red"< around it. Note: this will only work on the render phase after a rewind, and will be confused if components are inside any kind of loop.

Specified by:

writeLabelPrefix in interface IValidationDelegate

writeLabelAttributes

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

Does nothing by default. 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.

Specified by:

writeLabelAttributes in interface IValidationDelegate

Parameters:

writer - the writer to which output should be sent

cycle - the active request cycle

component - the component field that label decorates

writeLabelSuffix

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

Closes the <font> element,started by writeLabelPrefix(IFormComponent,IMarkupWriter,IRequestCycle), if the form component is in error.

Specified by:

writeLabelSuffix in interface IValidationDelegate

getComponentTracking

protected FieldTracking getComponentTracking()

Returns the IFieldTrackingfor the current component, if any. The IFieldTrackingis usually created in record(String, ValidationConstraint)or in record(IRender, ValidationConstraint).

Components may be rendered multiple times, with multiple names (provided by the Form, care must be taken that this method is invoked after the Form has provided a unique IFormComponent.getName()for the component.

Returns:

the FieldTracking, or null if the field has no tracking.

See Also:

setFormComponent(IFormComponent)

setFormComponent

public void setFormComponent(IFormComponent component)

Description copied from interface: IValidationDelegate

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

Specified by:

setFormComponent in interface IValidationDelegate

isInError

public boolean isInError()

Description copied from interface: IValidationDelegate

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

Specified by:

isInError in interface IValidationDelegate

getFieldInputValue

public java.lang.String getFieldInputValue()

Description copied from interface: IValidationDelegate

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

Specified by:

getFieldInputValue in interface IValidationDelegate

getFieldTracking

public java.util.List getFieldTracking()

Returns all the field trackings as an unmodifiable List.

Specified by:

getFieldTracking in interface IValidationDelegate

getCurrentFieldTracking

public IFieldTracking getCurrentFieldTracking()

Description copied from interface: IValidationDelegate

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

Specified by:

getCurrentFieldTracking in interface IValidationDelegate

Since:

3.0.2

reset

public void reset()

Description copied from interface: IValidationDelegate

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.

Specified by:

reset in interface IValidationDelegate

record

public void record(ValidatorException ex)

Invokes record(String, ValidationConstraint), or record(IRender, ValidationConstraint)if the error renderer propertyis not null.

Specified by:

record in interface IValidationDelegate

record

public void record(java.lang.String message,
                   ValidationConstraint constraint)

Invokes record(IRender, ValidationConstraint), after wrapping the message parameter in a RenderString.

Specified by:

record in interface IValidationDelegate

Parameters:

message - message to display (@see RenderString}

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

record

public void record(IRender errorRenderer,
                   ValidationConstraint constraint)

Records error information about the currently selected component, or records unassociated (with any field) errors.

Currently, you may have at most one error per field (note the difference between field and component), but any number of unassociated errors.

Subclasses may override the default error message (based on other factors, such as the field and constraint) before invoking this implementation.

Specified by:

record in interface IValidationDelegate

Parameters:

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

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

Since:

1.0.9

record

public void record(IFormComponent field,
                   java.lang.String message)

Description copied from interface: IValidationDelegate

Convienience for recording a standard string messages against a field.

Specified by:

record in interface IValidationDelegate

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

recordFieldInputValue

public void recordFieldInputValue(java.lang.String input)

Description copied from interface: IValidationDelegate

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.

Specified by:

recordFieldInputValue in interface IValidationDelegate

findCurrentTracking

protected FieldTracking findCurrentTracking()

Finds or creates the field tracking for the setFormComponent(IFormComponent) current component. If no current component, an unassociated error is created and returned.

Since:

3.0

writePrefix

public void writePrefix(IMarkupWriter writer,
                        IRequestCycle cycle,
                        IFormComponent component,
                        IValidator validator)

Does nothing. Override in a subclass to decoreate fields.

Specified by:

writePrefix in interface IValidationDelegate

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

public void writeAttributes(IMarkupWriter writer,
                            IRequestCycle cycle,
                            IFormComponent component,
                            IValidator validator)

Does nothing. Override in a subclass to decorate fields.

Specified by:

writeAttributes in interface IValidationDelegate

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

writeSuffix

public void writeSuffix(IMarkupWriter writer,
                        IRequestCycle cycle,
                        IFormComponent component,
                        IValidator validator)

Default implementation; if the current field is in error, then a suffix is written. The suffix is: &nbsp;<font color="red">**</font>.

Specified by:

writeSuffix in interface IValidationDelegate

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

getHasErrors

public boolean getHasErrors()

Description copied from interface: IValidationDelegate

Returns true if any form component has errors.

Specified by:

getHasErrors in interface IValidationDelegate

getFirstError

public IRender getFirstError()

A convienience, as most pages just show the first error on the page.

As of release 1.0.9, this returns an instance of IRender, not a String.

isInError

protected boolean isInError(IFormComponent component)

Checks to see if the field is in error. This will not work properly in a loop, but is only used by FieldLabel. Therefore, using FieldLabelin a loop (where the IFormComponentis renderred more than once) will not provide correct results.

getAssociatedTrackings

public java.util.List getAssociatedTrackings()

Returns a Listof IFieldTrackings. This is the master list of trackings, except that it omits and trackings that are not associated with a particular field. May return an empty list, or null.

Order is not determined, though it is likely the order in which components are laid out on in the template (this is subject to change).

getUnassociatedTrackings

public java.util.List getUnassociatedTrackings()

Like getAssociatedTrackings(), but returns only the unassociated trackings. Unassociated trackings are new (in release 1.0.9), and are why interface IFieldTrackingis not very well named.

The trackings are returned in an unspecified order, which (for the moment, anyway) is the order in which they were added (this could change in the future, or become more concrete).

getErrorRenderers

public java.util.List getErrorRenderers()

Description copied from interface: IValidationDelegate

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

Specified by:

getErrorRenderers in interface IValidationDelegate

Returns:

non-empty List of IRender.

registerForFocus

public void registerForFocus(IFormComponent field,
                             int priority)

Description copied from interface: IValidationDelegate

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.

Specified by:

registerForFocus in interface IValidationDelegate

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

public java.lang.String getFocusField()

Returns the focus field, or null if no form components registered for focus (i.e., they were all disabled).

Specified by:

getFocusField in interface IValidationDelegate

Returns:

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