universum.studios.android.form

Class FormValidator

java.lang.Object

universum.studios.android.form.FormValidator

public class FormValidator
extends Object

A FormValidator can be used to simplify validation process of a form with user inputs like EditTexts or CompoundButtons (CheckBox, RadioButton, ...).

Validation process can be launched via runValidation(). FormValidator runs validation process on its current assigned FormComponents that can be assigned to a validator instance via following methods:

• assignComponent(FormComponent)
• assignComponents(FormComponent[])
• assignComponentViews(int...)

Based on the validation mode (described in the section below), the validator iterates these components and invokes FormComponent.validate() upon each of them and notifies OnFormListener that can be specified via setOnFormListener(FormValidator.OnFormListener) about occurred errors and about validation result.

All current assigned form components can be obtained via getComponents(). To obtain a single component, call getComponent(int) with id of that component.

Validation modes

FormValidator supports following validation methods that are used to determine the validation flow:

• VALIDATION_MODE_BULK

  Assigned form components are validated regardless of occurred errors (OnFormListener.onValidationError(FormValidator, FormComponent)) and validation result is notified via OnFormListener.onValidationResult(FormValidator, boolean) after all form components has been validated.

• VALIDATION_MODE_SINGLE

  Assigned form components are validated until the first error occurs. Then the validation process is stopped, OnFormListener.onValidationError(...) is fired followed by OnFormListener.onValidationResult(...) with validation result set to false.

The desired validation mode can be specified via setValidationMode(int). The default one is VALIDATION_MODE_BULK.

Author:

Martin Albedinsky

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	FormValidator.OnFormListener Simple listener to receive callbacks when some validation errors occurs during form validation process and also callback with the result of validation process.
static interface	FormValidator.ValidationMode Defines an annotation for determining set of allowed validation modes for setValidationMode(int) method.

Field Summary

Fields

Modifier and Type	Field and Description
protected Context	mContext Context in which is this validator used.
protected View	mFormView View in which are placed all form component views.
static int	VALIDATION_MODE_BULK Mode used to validate all currently assigned BaseFormComponents.
static int	VALIDATION_MODE_SINGLE Unlike VALIDATION_MODE_BULK, when this mode is used, validation will be running until some validation error occurs.

Constructor Summary

Constructors

Constructor and Description
FormValidator(View formView) Same as FormValidator(View, int) with VALIDATION_MODE_BULK validation mode.
FormValidator(View formView, int mode) Creates a new instance of FormValidator for the given formView with the specified validation mode.

Method Summary

Modifier and Type	Method and Description
FormValidator	assignComponent(FormComponent component) Assigns the given form component to this validator.
FormValidator	assignComponents(FormComponent... components) Assigns the given form components to this validator.
FormValidator	assignComponentViews(int... viewIds) Assigns the set of ids of views which should be validated by this validator.
void	clearErrors() Clears the current errors of all assigned components.
FormComponent	findComponent(int componentId) Returns an instance of FormComponent with the requested id.
FormComponent	getComponent(int componentId) Returns an instance of FormComponent with the requested id.
SparseArray<FormComponent>	getComponents() Returns the set of current form components of this validator.
Context	getContext() Returns the context obtained from the context wrapper during initialization of this validator.
int	getValidationMode() Returns the current validation mode of this validator.
protected boolean	onAssignComponentForView(View componentView) Invoked to assign a new form component to this validator for the specified componentView.
boolean	runValidation() Runs validation process upon the current set of form components.
void	setOnFormListener(FormValidator.OnFormListener listener) Registers a callback to be invoked when some validation error occurs during form validation process or when validation process is finished with the validation result.
void	setSubmitView(int id) Same as setSubmitView(View) for id of the submit view that will be searched for in the form view.
void	setSubmitView(View submitView) Sets the submit view for this validator.
void	setValidationMode(int mode) Sets validation mode for this validator.

Methods inherited from class java.lang.Object

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

Field Detail

VALIDATION_MODE_BULK

public static final int VALIDATION_MODE_BULK

Mode used to validate all currently assigned BaseFormComponents. If some validation error occurs, FormValidator.OnFormListener.onValidationError(FormValidator, FormComponent) will be fired with that particular component, but validation process will continue and FormValidator.OnFormListener.onValidationResult(FormValidator, boolean) will be fired after all form components has been validated with either true or false validation result.

See Also:

Constant Field Values

VALIDATION_MODE_SINGLE

public static final int VALIDATION_MODE_SINGLE

Unlike VALIDATION_MODE_BULK, when this mode is used, validation will be running until some validation error occurs. At that time FormValidator.OnFormListener.onValidationError(FormValidator, FormComponent) will be fired with that particular component and FormValidator.OnFormListener.onValidationResult(FormValidator, boolean) will be fired with false as validation result and whole validation process stops.

See Also:

Constant Field Values

mContext

protected final Context mContext

Context in which is this validator used.

mFormView

protected final View mFormView

View in which are placed all form component views.

Constructor Detail

FormValidator

public FormValidator(@NonNull
                     View formView)

Same as FormValidator(View, int) with VALIDATION_MODE_BULK validation mode.

FormValidator

public FormValidator(@NonNull
                     View formView,
                     int mode)

Creates a new instance of FormValidator for the given formView with the specified validation mode.

Parameters:

formView - The view in which are placed all form component views.

mode - The validation mode flag. One of VALIDATION_MODE_BULK or VALIDATION_MODE_SINGLE.

Method Detail

assignComponents

public FormValidator assignComponents(@NonNull
                                      FormComponent... components)

Assigns the given form components to this validator.

Parameters:

components - Form components which should be validated by this validator.

Returns:

This validator to allow methods chaining.

assignComponent

public FormValidator assignComponent(@NonNull
                                     FormComponent component)

Assigns the given form component to this validator.

Parameters:

component - Form component which should be validated by this validator.

Returns:

This validator to allow methods chaining.

assignComponentViews

public FormValidator assignComponentViews(int... viewIds)

Assigns the set of ids of views which should be validated by this validator.

Parameters:

viewIds - The set of ids of desired views from the current context's root view for which should be auto-created FormComponents and assigned to this validator. Type of each created form component, will be resolved from the type of view.

Returns:

This validator to allow methods chaining.

runValidation

public boolean runValidation()

Runs validation process upon the current set of form components.

Note, that all current errors will be cleared via clearErrors() before validation process starts.

Returns:

True if validation was performed, false otherwise. This will return true always if there are some form components to validate.

clearErrors

public void clearErrors()

Clears the current errors of all assigned components.

See Also:

BaseFormComponent.clearError()

onAssignComponentForView

protected boolean onAssignComponentForView(@NonNull
                                           View componentView)

Invoked to assign a new form component to this validator for the specified componentView.

Note, that this is invoked in case when there was supplied a set of ids of views to this validator via assignComponentViews(int...) for which should be created and assigned form components. This will be invoked from runValidation() whenever there are view ids that has not been processed yet.

This implementation does nothing.

Parameters:

componentView - The view for which to assign new form component that will be validated by this validator.

Returns:

True to indicate that component for the view has been successfully assigned, false otherwise.

getContext

@Nullable
public Context getContext()

Returns the context obtained from the context wrapper during initialization of this validator.

Returns:

Valid context.

setSubmitView

public void setSubmitView(int id)

Same as setSubmitView(View) for id of the submit view that will be searched for in the form view.

Parameters:

id - An id of the desired submit view.

setSubmitView

public void setSubmitView(@NonNull
                          View submitView)

Sets the submit view for this validator.

Note, that this will attach to the given submitView an instance of View.OnClickListener, so any previous OnClickListener attached to this view will be replaced.

Parameters:

submitView - The view, on which click should be validation executed.

setOnFormListener

public void setOnFormListener(@Nullable
                              FormValidator.OnFormListener listener)

Registers a callback to be invoked when some validation error occurs during form validation process or when validation process is finished with the validation result.

Parameters:

listener - Listener callback to register. May be null to remove the current one.

setValidationMode

public void setValidationMode(int mode)

Sets validation mode for this validator.

Parameters:

mode - One of VALIDATION_MODE_BULK or VALIDATION_MODE_SINGLE.

getValidationMode

public int getValidationMode()

Returns the current validation mode of this validator.

Returns:

One of VALIDATION_MODE_BULK or VALIDATION_MODE_SINGLE.

getComponents

@NonNull
public SparseArray<FormComponent> getComponents()

Returns the set of current form components of this validator.

Returns:

All assigned form components.

getComponent

@Nullable
public FormComponent getComponent(int componentId)

Returns an instance of FormComponent with the requested id. Unlike findComponent(int), this will check only at the top of current components.

Parameters:

componentId - An id of the desired form component to obtain.

Returns:

An instance of requested form component with the passed id or null if there is no such a form component assigned to this validator.

findComponent

@Nullable
public FormComponent findComponent(int componentId)

Returns an instance of FormComponent with the requested id. This will traverse whole hierarchy of assigned components/component groups, to find that particular form component.

Parameters:

componentId - An id of the desired form component to find.

Returns:

An instance of requested form component with the passed id or null if there is no such a form component assigned to this validator or any of assigned form component groups does not contain form component with such an id.