Package 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
All Implemented Interfaces:
HasHandlers
Direct Known Subclasses:
ContainsValidator, CustomValidator, DateRangeValidator, DoesntContainValidator, EqualsValidator, FloatPrecisionValidator, FloatRangeValidator, InSetValidator, IntegerRangeValidator, IsBooleanValidator, IsFloatValidator, IsIntegerValidator, IsOneOfValidator, IsStringValidator, LengthRangeValidator, MaskValidator, MatchesFieldValidator, NotEqualValidator, NotInSetValidator, 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 DataSourceField.validators property and are executed in the order in which they are defined. 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 addValidator() method.

See Also:

  • Constructor Details

    • Validator

      public Validator()

    • Validator

      public Validator(JavaScriptObject jsObj)

  • Method Details

    • getOrCreateRef

      public static Validator getOrCreateRef(JavaScriptObject jsObj)

    • setApplyWhen

      public Validator setApplyWhen(AdvancedCriteria applyWhen)
      Used to create a conditional validator based on criteria. The criteria defines when the validator applies. The form current values or ListGrid record is used as reference for the criteria. If the criteria match, then the validator will be processed. Otherwise the validator is skipped and assumed valid.

      To use an applyWhen criteria the form or grid must use a DataSource.

      NOTE: applyWhen is not supported for "binary" fields.

      Server and client use

      Conditional validators are enforced both on the server and on the client-side when defined on a DataSource field as shown in the examples below. Note the applyWhen element is treated as a Criterion. 
        <!-- Normal format -->
  <field name="age" type="integer">
    <validators>
      <validator type="integerRange" min="0" max="100">
        <applyWhen operator="or">
          <criteria>
            <criterion fieldName="restrictAge" operator="equals" value="true"/>
            <criterion fieldName="gender" operator="equals" value="female"/>
          </criteria> 
        </applyWhen>
      </validator>
    </validators>
  </field>
 
  <!-- Conditional requirement -->
  <field name="reason" type="text">
    <validators>
      <validator type="required">
        <applyWhen fieldName="willAttend" operator="equals" value="false"/>
      </validator>
    </validators>
  </field>
      The last example above shows an alternate to the requiredIf validator using a shorthand format which is only available for client-side use. On the client the reason field will change appearance to match other required or non-required fields when willAttend changes. Note that using applyWhen for a validator of type required as in the example may result in validation request being set to the server where a fetch is made against the DataSource. For more details, see the discussion at the end of the DataSourceField.required help topic.

      Component XML and client-only use

      Conditional validators can also be applied to Component XML similarly to provide client-only validations or read-only state management. A common use case is conditionally displaying or enabling fields. Use the readOnly validator with an applyWhen value to control the read-only appearance of a field. The example below shows a field which is hidden when willAttend=true. 
        <!-- field definition within a Component XML DynamicForm -->
  <field name="reason" type="text">
    <validators>
      <validator type="readOnly" fieldAppearance="hidden">
        <applyWhen fieldName="willAttend" operator="equals" value="true"/>
      </validator>
    </validators>
  </field>

      Conditional validators can be applied to DynamicForm or ListGrid fields in Java code as well.

      Note : This is an advanced setting

      Parameters:
      applyWhen - New applyWhen value. Default value is null
      Returns:
      Validator instance, for chaining setter calls

    • getApplyWhen

      public AdvancedCriteria getApplyWhen()
      Used to create a conditional validator based on criteria. The criteria defines when the validator applies. The form current values or ListGrid record is used as reference for the criteria. If the criteria match, then the validator will be processed. Otherwise the validator is skipped and assumed valid.

      To use an applyWhen criteria the form or grid must use a DataSource.

      NOTE: applyWhen is not supported for "binary" fields.

      Server and client use

      Conditional validators are enforced both on the server and on the client-side when defined on a DataSource field as shown in the examples below. Note the applyWhen element is treated as a Criterion. 
        <!-- Normal format -->
  <field name="age" type="integer">
    <validators>
      <validator type="integerRange" min="0" max="100">
        <applyWhen operator="or">
          <criteria>
            <criterion fieldName="restrictAge" operator="equals" value="true"/>
            <criterion fieldName="gender" operator="equals" value="female"/>
          </criteria> 
        </applyWhen>
      </validator>
    </validators>
  </field>
 
  <!-- Conditional requirement -->
  <field name="reason" type="text">
    <validators>
      <validator type="required">
        <applyWhen fieldName="willAttend" operator="equals" value="false"/>
      </validator>
    </validators>
  </field>
      The last example above shows an alternate to the requiredIf validator using a shorthand format which is only available for client-side use. On the client the reason field will change appearance to match other required or non-required fields when willAttend changes. Note that using applyWhen for a validator of type required as in the example may result in validation request being set to the server where a fetch is made against the DataSource. For more details, see the discussion at the end of the DataSourceField.required help topic.

      Component XML and client-only use

      Conditional validators can also be applied to Component XML similarly to provide client-only validations or read-only state management. A common use case is conditionally displaying or enabling fields. Use the readOnly validator with an applyWhen value to control the read-only appearance of a field. The example below shows a field which is hidden when willAttend=true. 
        <!-- field definition within a Component XML DynamicForm -->
  <field name="reason" type="text">
    <validators>
      <validator type="readOnly" fieldAppearance="hidden">
        <applyWhen fieldName="willAttend" operator="equals" value="true"/>
      </validator>
    </validators>
  </field>

      Conditional validators can be applied to DynamicForm or ListGrid fields in Java code as well.

      Returns:
      Current applyWhen value. Default value is null

    • setCheckComponentData

      public Validator setCheckComponentData(ClientUniquenessCheckCondition checkComponentData)
      For a validator of type "isUnique" in a dataBoundComponent, under what circumstances should uniqueness checking be performed against the component's data set?

      Only applies to validators within a multiple dataArity component like a ListGrid.

      Parameters:
      checkComponentData - New checkComponentData value. Default value is "both"
      Returns:
      Validator instance, for chaining setter calls

    • getCheckComponentData

      public ClientUniquenessCheckCondition getCheckComponentData()
      For a validator of type "isUnique" in a dataBoundComponent, under what circumstances should uniqueness checking be performed against the component's data set?

      Only applies to validators within a multiple dataArity component like a ListGrid.

      Returns:
      Current checkComponentData value. Default value is "both"

    • setClientOnly

      public Validator setClientOnly(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 - New clientOnly value. Default value is false
      Returns:
      Validator instance, for chaining setter calls

    • getClientOnly

      public 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:
      Current clientOnly value. Default value is false

    • setCondition

      public Validator setCondition(String condition)
      For a validator that is not a built-in ValidatorType, a Callback, function, or JavaScript expression to evaluate to see if this validator passes or fails.

      Because the validator declaration itself is passed as a parameter to condition(), you can effectively parameterize the validator. For example, to create a validator that checks that the value is after a certain date:

       
      { type:"custom", afterDate:new Date(), 
        condition:"value.getTime() > validator.afterDate.getTime()" }
      Reusable validators, like the above, can be registered as a standard validatorType by calling addValidator().

      Note that, if a field is declared with a builtin FieldType, the value passed in will already have been converted to the specified type, if possible.

      For the required parameters, see the documentation for ValidatorConditionCallback.

      Parameters:
      condition - New condition value. Default value is null
      Returns:
      Validator instance, for chaining setter calls
      See Also:

    • getCondition

      public String getCondition()
      For a validator that is not a built-in ValidatorType, a Callback, function, or JavaScript expression to evaluate to see if this validator passes or fails.

      Because the validator declaration itself is passed as a parameter to condition(), you can effectively parameterize the validator. For example, to create a validator that checks that the value is after a certain date:

       
      { type:"custom", afterDate:new Date(), 
        condition:"value.getTime() > validator.afterDate.getTime()" }
      Reusable validators, like the above, can be registered as a standard validatorType by calling addValidator().

      Note that, if a field is declared with a builtin FieldType, the value passed in will already have been converted to the specified type, if possible.

      For the required parameters, see the documentation for ValidatorConditionCallback.

      Returns:
      Current condition value. Default value is null
      See Also:

    • setDependentFields

      public Validator setDependentFields(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 that for validators run on the server, fields required due to dependentFields but not present in the DSRequest.data of an update because they haven't changed will be filled in from the server DataSource.

      Note : This is an advanced setting

      Parameters:
      dependentFields - New dependentFields value. Default value is null
      Returns:
      Validator instance, for chaining setter calls
      See Also:

    • getDependentFields

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

      Note that for validators run on the server, fields required due to dependentFields but not present in the DSRequest.data of an update because they haven't changed will be filled in from the server DataSource.

      Returns:
      Current dependentFields value. Default value is null
      See Also:

    • setErrorMessage

      public Validator setErrorMessage(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.

      Server-side this string evaluates in a Velocity context where the variables $value and $fieldName are available and refer to the supplied value and the field name, respectively. Note that if the validator is intended to run both on the client and server, you shouldn't use these velocity vars as they will not be expanded on the client and the user may then see raw uninterpolated strings.

      Parameters:
      errorMessage - New errorMessage value. Default value is null
      Returns:
      Validator instance, for chaining setter calls
      See Also:

    • setStopIfFalse

      public Validator setStopIfFalse(Boolean stopIfFalse)
      Normally, all validators defined for a field will be run in the order in which they are defined 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 - New stopIfFalse value. Default value is false
      Returns:
      Validator instance, for chaining setter calls

    • getStopIfFalse

      public Boolean getStopIfFalse()
      Normally, all validators defined for a field will be run in the order in which they are defined 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:
      Current stopIfFalse value. Default value is false

    • setStopOnError

      public Validator setStopOnError(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 FormItem.stopOnError if unset.

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

      Parameters:
      stopOnError - New stopOnError value. Default value is null
      Returns:
      Validator instance, for chaining setter calls

    • getStopOnError

      public 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 FormItem.stopOnError if unset.

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

      Returns:
      Current stopOnError value. Default value is null

    • setType

      public Validator 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 - New type value. Default value is null
      Returns:
      Validator instance, for chaining setter calls

    • 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:
      Current type value. Default value is null

    • setType

      public Validator setType(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 - New type value. Default value is null
      Returns:
      Validator instance, for chaining setter calls

    • getTypeAsString

      public 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:
      Current type value. Default value is null

    • setValidateOnChange

      public Validator setValidateOnChange(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 - New validateOnChange value. Default value is null
      Returns:
      Validator instance, for chaining setter calls

    • getValidateOnChange

      public 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:
      Current validateOnChange value. Default value is null

    • create

      public static void create()
      A Validator shouldn't be created directly. Instead pass Properties as each Validator in FormItem.validators or wherever a Validator is needed.

    • addValidatorDefinition

      public static void addValidatorDefinition(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