Table of Contents

form_validation

Form validators that can be used directly via code or constructed from JSON to provide more dynamic validation.

Live Web Example

Using the library

Add the repo to your Flutter pubspec.yaml file.

dependencies:
  form_validation: <<version>>

Then run...

flutter packages get

Validators

The library provides a set of built-in validators while also providing a mechanism for applications to provide their own validators. All the built-in validators are able to be deserialized via JSON. They all expect an attribute of type to match a specific value when being desearialized.

Note: With the sole exception of RequiredValidator, all built in validators will pass on null or empty values.

Class Type Description
CurrencyValidator currency Ensures the value is a valid currency
EmailValidator email Ensures the value is a validly formatted email address
MaxLengthValidator max_length Ensures the value contains no more than a set number of characters
MaxNumberValidator max_number Ensures the value is no larger than a given number
MinLengthValidator min_length Ensures the value contains no fewer than a set number of characters
MinNumberValidator min_number Ensures the value is no smaller than a given number
NumberValidator number Ensures the value is a valid number
PhoneNumberValidator phone_number Ensures the value is a validly formatted phone number
RequiredValidator required Ensures the value is not null, empty, nor white space only

Validation Messages / Translations

The library provides a default set of English error messages for each validator's error message. This library provides a class named FormValidationTranslations that has a values map. In it is the default strings to use. Update that map when a different language should be used. Below are the available keys.

Key Parameters Description
form_validation_currency label Used when an invalid currency value is detected
form_validation_currency_positive label Used when a valid, but negative, currency value is detected
form_validation_email label Used when an invalid email is detected
form_validation_max_length label, length Used when a value contains more characters than length
form_validation_max_number label, number Used when a value is larger than number
form_validation_min_length label, length Used when a value contains fewer characters than length
form_validation_min_number label, number Used when a value is smaller than number
form_validation_number label Used when a number is expected but not detected
form_validation_number_decimal label Used when a number is detected, but not allowed to be a decimal
form_validation_phone_number label Used when an invalid phone number is detected
form_validation_required label Used when a value is required, but detected as null, empty, or all white space

JSON Support

The Validator class can be used to decode a list of child ValueValidator entries. Each of the built-in validators can be deserialized via JSON. In addition to being able to deserialize from JSON, each of the built-in validators supports serializing to a JSON compatible map via toJson or an actual JSON encoded string via toJsonString.

The overall struction needs to be:

{
  "validators": [
    // One or more of the JSON objects shown below
  ]
}

CurrencyValidator

{
  "allowNegative": <bool>, // Default: true; states whether negative values are allowed or not
  "type": "currency"
}

EmailValidator

{
  "type": "email"
}

MaxLengthValidator

{
  "length": <int>, // The maximum length the value may be
  "type": "max_length"
}

MaxNumberValidator

{
  "length": <int>, // The maximum number the value may be
  "type": "max_number"
}

MinLengthValidator

{
  "length": <int>, // The minimum length the value may be
  "type": "min_length"
}

MinNumberValidator

{
  "length": <int>, // The minimum number the value may be
  "type": "min_number"
}

NumberValidator

{
  "type": "number"
}

PhoneNumberValidator

{
  "type": "phone_number"
}

RequiredValidator

{
  "type": "required"
}

Custom Validators

The Validator supports custom validators being added either directly through classes extending the ValueValidator abstract class and passing them in via the constructor. Alternatively, an application may register a validator type with Validator using the registerCustomValidatorBuilder function.

Example

class MyCustomValidator extends ValueValidator {
  static const type = 'my_custom_validator';

  static MyCustomValidator fromDynamic(dynamic map) {
    MyCustomValidator({
      // initialization args go here
    });

    MyCustomValidator result;

    if (map != null) {
      assert(map['type'] == type);

      result = MyCustomValidator(
        // Do additional JSON conversion here
      )
    })

    return result;
  }

  Map<String, dynamic> toJson() => {
    // add additional attributes here
    "type": type,
  }

  String validate({
    @required BuildContext context,
    @required String label,
    @required String value,
  }) {
    String error;

    // In general, validators should pass if the value is empty.  Combine 
    // validators with the RequiredValidator to ensure a value is non-empty.
    if (value?.isNotEmpty == true) {
      // Do processing to determine if the value is valid or not
    }

    return error;
  }
}

...

void main() {
  Validator.registerCustomValidatorBuilder(
    MyCustomValidator.type,
    MyCustomValidator.fromDynamic,
  );

  // start app
} 

...

var jsonStr = '''
{
  "validators": [{
    "type": "required"
  }, {
    "type": "my_custom_validator"
  }]
}
'''

// This will create a validation chain with the RequiredValidator as well as the
// MyCustomValidator defined above
var validator = Validator.fromDynamic(json.decode(jsonStr));

Libraries

form_validation