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

      `jsObj`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Validator()`
    `Validator(com.google.gwt.core.client.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(com.google.gwt.core.client.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()` Built-in type of the validator as specified via `setType(ValidatorType)`
    `java.lang.String` | `getTypeAsString()` Type of the validator as a string value.
    `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` | `setJavaScriptObject(com.google.gwt.core.client.JavaScriptObject jsObj)`
    `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 defined as a String.
    `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

      `doAddHandler, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsDoubleArray, getAttributeAsFloat, getAttributeAsInt, getAttributeAsIntArray, getAttributeAsJavaScriptObject, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsString, getAttributeAsStringArray, getAttributes, getHandlerCount, getJsObj, 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`

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

      `equals, hashCode, isCreated, 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(com.google.gwt.core.client.JavaScriptObject jsObj)

  - ### Method Detail

    - #### getOrCreateRef

          public static Validator getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)

    - #### setJavaScriptObject

          public void setJavaScriptObject(com.google.gwt.core.client.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` - 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

    - #### 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` - 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` - 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

    - #### 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` - 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.

    - #### 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` - errorMessage Default value is null

    - #### 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` - dependentFields Default value is null

    - #### 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:
        dependent fields

    - #### setType

          public void setType(ValidatorType type)

      Type of the validator. This can be one of the built-in `ValidatorType`. Note that a validator of type ValidatorType.CUSTOM may be used to support custom validation behavior.
      Parameters:
        `type` - validator type

    - #### setType

          public void setType(java.lang.String type)

      Type of the validator defined as a String.

      This API may be used to specify a custom validator type registered via `addValidatorDefinition(String, Validator)`.

      Parameters:
        `type` - validator type

    - #### getType

          public ValidatorType getType()

      Built-in type of the validator as specified via `setType(ValidatorType)`

      Note that if a custom validator type was specified via `setType(String)` this method will return null - use `getTypeAsString()` to retrieve custom validator types.

      Returns:
        ValidatorType

    - #### getTypeAsString

          public java.lang.String getTypeAsString()

      Type of the validator as a string value. If type was specified via `setType(ValidatorType)` this method will return the underlying value of the ValidatorType enum. If type was specified via `setType(String)` the specified string will be returned.
      Returns:
        ValidatorType

    - #### 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 `com.smartgwt.client.types.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