Custom validators

You can add custom validators through v2.Validator.add(). The method accepts a single parameter; the validator as an object literal:

v2.Validator.add({
  name: 'validator-name',
  message: 'Default error message',
  params: ['a', 'list', 'of', 'named', 'parameters'],
  aliases: ['list', 'of', 'alternative', 'names'],
  acceptEmpty: true,
  fn: function(field, value, params) {
    // Should return true if field/value is valid
  }
});

Parameters

name

The primary name of the validator. This is the name you use with v2.$v('name'); and v2.Validator.get('name'); (core API), "field".is("name"); (DSL API) and class="name" (HTML extension).

Parameter is required

fn

This is the method that performs the validation. It receives three arguments, the last one (parameters) may be empty.

field is an instance of v2.InputElement, or one of its subclasses. It wraps a label and one or more input/select/textarea elements, and provides convenience such as getValue, getLabel, getName, setName, visible and getParent.
value is basically the value of field.getValue(). There is some overhead in fetching the value, and since Validatious already uses it, it passes it along, allowing for an ever so small performance gain.
params is an array of parameters registered with the field validator. In the HTML extension, these are the values separated by underscores: class="myval_1" (params[0] === 1).

Parameter is required

message

This is the default error message. It may use named parameters. Parameters can be interpolated into the default message through ${param-name}. All messages have access to ${field}, which resolves to the field name of the validated field.

If the validator takes any parameters, they can also be interpolated into the message, through the name given through the params parameter.

params

The params parameter provides a mapping between any parameters being sent to the validation method and names to refer to them by when interpolating in the error message.

Example: If the fn function uses the value in params[0], you may give this a name by setting params: ['myparam']. In the error message you can then do message: "${field} should obey ${myparam}". When a field fails this message, ${field} will be replaced with the field name, and ${myparam} with the value of the validator function's params[0].

aliases

An array of additional names for the validator. May make sense especially for the DSL API to be able to refer to a validator by different names.

acceptEmpty

Decides if the validator should pass (return true) when the value is empty. This is usually a good idea because you can leave it up to the required validator to specifically check for emptiness. One benefit of this approach is more fine grained error reporting, helping the user.

Default value is true

Example

The following is an example of a validator that checks that a password contains atleast one lowercase letter, one uppercase letter and one number. This is a simple validator; it has no aliases or parameters and it uses the default of accepting empty values.

v2.Validator.add({
  name: 'password',
  fn: function(field, value, params) {
    return /^(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?!.*\s).*$/.test(value);
  }
});

Validators should be added in a separate file or script block which is included after the Validatious source.

Next: Custom error display | Back to Core API features index

Validatious 2.0