com.smartgwt.client.widgets.form.validator

Class Validator

java.lang.Object

com.smartgwt.client.core.JsObject

com.smartgwt.client.core.DataClass

com.smartgwt.client.widgets.form.validator.Validator

Direct Known Subclasses:

ContainsValidator, CustomValidator, DateRangeValidator, DoesntContainValidator, FloatPrecisionValidator, FloatRangeValidator, IntegerRangeValidator, IsBooleanValidator, IsFloatValidator, IsIntegerValidator, IsOneOfValidator, IsStringValidator, LengthRangeValidator, MaskValidator, MatchesFieldValidator, RegExpValidator, RequiredIfValidator, StringCountValidator

public class Validator
extends DataClass

A validator describes a check that should be performed on a value the user is trying to save.

Validators are specified for DataSource fields via the validators property. Validators that need not be run on the server can also be specified for a specific FormItem or ListGridField.

Smart GWT supports a powerful library of ValidatorTypes which have identical behavior on both the client and the server.

Beyond this, custom validators can be defined on the client and custom validation logic added on the server. Note that the regexp and mask validator types are very flexible and can be used to perform virtually any kind of formatting check that doesn't involve some large external dataset.

Custom validators can be reused on the client by adding them to the global validator list, via the Validator.addValidator() method.

See Also:

ValidatorType

Field Summary

Fields inherited from class com.smartgwt.client.core.DataClass

factoryCreated, factoryProperties

Fields inherited from class com.smartgwt.client.core.JsObject

jsObj

Constructor Summary

Constructors

Constructor and Description
Validator()
Validator(JavaScriptObject jsObj)

Method Summary

Methods

Modifier and Type	Method and Description
static void	addValidatorDefinition(java.lang.String name, Validator validator) Register a new standard validator type for reuse, by name.
static void	create() A Validator shouldn't be created directly.
java.lang.Boolean	getClientOnly() Indicates this validator runs on the client only.
java.lang.String[]	getDependentFields() User-defined list of fields on which this validator depends.
static Validator	getOrCreateRef(JavaScriptObject jsObj)
java.lang.Boolean	getStopIfFalse() Normally, all validators defined for a field will be run even if one of the validators has already failed.
java.lang.Boolean	getStopOnError() Indicates that if this validator is not passed, the user should not be allowed to exit the field - focus will be forced back into the field until the error is corrected.
ValidatorType	getType() Type of the validator.
java.lang.String	getTypeAsString() Type of the validator.
java.lang.Boolean	getValidateOnChange() If true, validator will be validated when each item's "change" handler is fired as well as when the entire form is submitted or validated.
void	setClientOnly(java.lang.Boolean clientOnly) Indicates this validator runs on the client only.
void	setDependentFields(java.lang.String[] dependentFields) User-defined list of fields on which this validator depends.
void	setErrorMessage(java.lang.String errorMessage) Text to display if the value does not pass this validation check.
void	setStopIfFalse(java.lang.Boolean stopIfFalse) Normally, all validators defined for a field will be run even if one of the validators has already failed.
void	setStopOnError(java.lang.Boolean stopOnError) Indicates that if this validator is not passed, the user should not be allowed to exit the field - focus will be forced back into the field until the error is corrected.
void	setType(java.lang.String type) Type of the validator.
void	setType(ValidatorType type) Type of the validator.
void	setValidateOnChange(java.lang.Boolean validateOnChange) If true, validator will be validated when each item's "change" handler is fired as well as when the entire form is submitted or validated.

Methods inherited from class com.smartgwt.client.core.DataClass

applyFactoryProperties, doAddHandler, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsDoubleArray, getAttributeAsFloat, getAttributeAsInt, getAttributeAsIntArray, getAttributeAsJavaScriptObject, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsString, getAttributeAsStringArray, getAttributes, getHandlerCount, isFactoryCreated, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttributeAsJavaObject, setFactoryCreated

Methods inherited from class com.smartgwt.client.core.JsObject

equals, getJsObj, hashCode, isCreated, setJavaScriptObject, setJsObj

Methods inherited from class java.lang.Object

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

Constructor Detail

Validator

public Validator()

Validator

public Validator(JavaScriptObject jsObj)

Method Detail

getOrCreateRef

public static Validator getOrCreateRef(JavaScriptObject jsObj)

setClientOnly

public void setClientOnly(java.lang.Boolean clientOnly)

Indicates this validator runs on the client only.

Normally, if the server is trying to run validators and finds a validator that it can't execute, for safety reasons validation is considered to have failed. Use this flag to explicitly mark a validator that only needs to run on the client.

Parameters:

clientOnly - Default value is false

getClientOnly

public java.lang.Boolean getClientOnly()

Indicates this validator runs on the client only.

Normally, if the server is trying to run validators and finds a validator that it can't execute, for safety reasons validation is considered to have failed. Use this flag to explicitly mark a validator that only needs to run on the client.

Returns:

Boolean

setDependentFields

public void setDependentFields(java.lang.String[] dependentFields)

User-defined list of fields on which this validator depends. Primarily used for validators of type "custom" but can also be used to supplement applyWhen criteria.

Note : This is an advanced setting

Parameters:

dependentFields - Default value is null

See Also:

com.smartgwt.client.widgets.form.validator.Validator#setApplyWhen

getDependentFields

public java.lang.String[] getDependentFields()

User-defined list of fields on which this validator depends. Primarily used for validators of type "custom" but can also be used to supplement applyWhen criteria.

Returns:

String[]

See Also:

com.smartgwt.client.widgets.form.validator.Validator#getApplyWhen

setErrorMessage

public void setErrorMessage(java.lang.String errorMessage)

Text to display if the value does not pass this validation check.

If unspecified, default error messages exist for all built-in validators, and a generic message will be used for a custom validator that is not passed.

Parameters:

errorMessage - Default value is null

See Also:

Conditionally Required Example

setStopIfFalse

public void setStopIfFalse(java.lang.Boolean stopIfFalse)

Normally, all validators defined for a field will be run even if one of the validators has already failed. However, if stopIfFalse is set, validation will not proceed beyond this validator if the check fails.

This is useful to prevent expensive validators from being run unnecessarily, or to allow custom validators that don't need to be robust about handling every conceivable type of value.

Parameters:

stopIfFalse - Default value is false

getStopIfFalse

public java.lang.Boolean getStopIfFalse()

Normally, all validators defined for a field will be run even if one of the validators has already failed. However, if stopIfFalse is set, validation will not proceed beyond this validator if the check fails.

This is useful to prevent expensive validators from being run unnecessarily, or to allow custom validators that don't need to be robust about handling every conceivable type of value.

Returns:

Boolean

setStopOnError

public void setStopOnError(java.lang.Boolean stopOnError)

Indicates that if this validator is not passed, the user should not be allowed to exit the field - focus will be forced back into the field until the error is corrected.

This property defaults to stopOnError if unset.

Enabling this property also implies validateOnExit is automatically enabled. If this is a server-based validator, setting this property also implies that synchronousValidation is forced on.

Parameters:

stopOnError - Default value is null

getStopOnError

public java.lang.Boolean getStopOnError()

Indicates that if this validator is not passed, the user should not be allowed to exit the field - focus will be forced back into the field until the error is corrected.

This property defaults to stopOnError if unset.

Enabling this property also implies validateOnExit is automatically enabled. If this is a server-based validator, setting this property also implies that synchronousValidation is forced on.

Returns:

Boolean

setType

public void setType(ValidatorType type)

Type of the validator.

This can be one of the built-in ValidatorType, the string "custom" to define a custom validator, or the string "serverCustom" to define a server-only custom validator.

Parameters:

type - Default value is null

getType

public ValidatorType getType()

Type of the validator.

This can be one of the built-in ValidatorType, the string "custom" to define a custom validator, or the string "serverCustom" to define a server-only custom validator.

Returns:

ValidatorType

setType

public void setType(java.lang.String type)

Type of the validator.

This can be one of the built-in ValidatorType, the string "custom" to define a custom validator, or the string "serverCustom" to define a server-only custom validator.

Parameters:

type - Default value is null

getTypeAsString

public java.lang.String getTypeAsString()

Type of the validator.

This can be one of the built-in ValidatorType, the string "custom" to define a custom validator, or the string "serverCustom" to define a server-only custom validator.

Returns:

String

setValidateOnChange

public void setValidateOnChange(java.lang.Boolean validateOnChange)

If true, validator will be validated when each item's "change" handler is fired as well as when the entire form is submitted or validated. If false, this validator will not fire on the item's "change" handler.

Note that this property can also be set at the form/grid or field level; If true at any level and not explicitly false on the validator, the validator will be fired on change - displaying errors and rejecting the change on validation failure.

Parameters:

validateOnChange - Default value is null

getValidateOnChange

public java.lang.Boolean getValidateOnChange()

If true, validator will be validated when each item's "change" handler is fired as well as when the entire form is submitted or validated. If false, this validator will not fire on the item's "change" handler.

Note that this property can also be set at the form/grid or field level; If true at any level and not explicitly false on the validator, the validator will be fired on change - displaying errors and rejecting the change on validation failure.

Returns:

Boolean

create

public static void create()

A Validator shouldn't be created directly. Instead pass Properties as each Validator in validators or wherever a Validator is needed.

addValidatorDefinition

public static void addValidatorDefinition(java.lang.String name,
                          Validator validator)

Register a new standard validator type for reuse, by name. The validator passed in should be of type ValidatorType.CUSTOM.

Any new validator where setType(String) is set to the registered name will pick up all properties (error message, condition, etc) from this validator definition.

Parameters:

name - name under which validator properties will be available

validator - validator containing standard properties for reuse