The Validation Criteria

In flitter-forms, each field in a form has a number of criteria it must pass to be valid. These criteria are specified by name and may take a number of arguments. Forms uses a superset of the criteria provided by the validator package, so any criteria present there will work with Forms.

Specifying Criteria

Criteria are specified in the validator schema definition. They are specified as an Array of String elements where each element is the name of some criteria. Here's an example:

const TestForm {
  	// field	criteria
  	'age':		[ 'required', 'isInt' ],
}

Here, we tell Forms that the age field is required, and it must be an integer.

Criterion Arguments

If you look at the list of criteria provided by the validator package, you may notice that many of them accept an Object of different arguments. Forms provides a way to specify these arguments. Arguments should be specified as a valid JSON object in the same String as the criterion name. It should be separated from the name by a : character. For example:

const TestForm {
  	// field			criteria
  	'age':				[ 'required', 'isInt:{"min":18}' ],
    'secret_password':	[ 'required', 'equals:its_a_secret' ],
}

Here, we tell Forms that the age field is required, and it should be an integer with a minimum value of 18, inclusive. The latter half of that criterion is a valid JSON object:

{"min":18}

We also tell Forms that the secret_password field is required and it should be equal to the string "its_a_secret". It's important to note that specifying a String as an argument without quotes is valid because it will be parsed into a JSON string. This is equally valid:

equals:"this is a bigger string"

Field Interpolation

Field values can also be interpolated as arguments in other fields. This can be useful when checking equivalence or relating numbers together. To interpolate the value of a field in the argument of another field, simply specify that field's name surrounded on both sides with $ characters, and it will be replaced with the value of the field. Here's an example:

const TestForm {
  	// field			criteria
  	'age':				[ 'required', 'isInt:{"min":13}' ],
    'parent_age':		[ 'required', 'isInt:{"min":$age$}' ],
    'strings_work_too':	[ 'required', 'equals:"$age$ years old"' ],
}

Say someone submits the form, and the age input is 15. Forms would stipulate that the age is required and must be greater than 13, the parent age is required and must be greater than 15, and the strings_work_too field is required and must be equal to "15 years old".

Available Criteria

flitter-forms ⊃ validator

The criteria in flitter-forms are a superset of those in the validator package. You can use any of the criteria listed here, with their arguments.

criteria ∉ validator

Forms also provides a few other criteria that are not a part of the validator package. Here they are:

Criterion Name Description
required The associated field must be present in the input, and must not be equal to an empty String.
verify

The associated field must have a corresponding field with the same name suffixed with _verify. The two fields must be equal.

 

For example, if the password field has the verify criterion, then password_verify must be present, and it must be equal to password.

No Comments
Back to top