Widget: Form Validation

Details

How to Use: Create a form on your document, and get a reference to it. Create a config object (documentation below). Pass both the form and the config object into deque.configureFormValidation. The inputs on your form can use the following types of data-attributes in order to ensure validation.

Data Attributes

data-feedback-type

This is the only attribute that lives on the form element instead of on an input element. The accepted values are "top" and "inline". If you use 'top', then when the form is validated all feedback will be enumerated at the top of the form, and focus will go to the notification region. If you use 'inline', feedback will be specified using tooltips on invalide inputs, and focus will go to the first invalid input.

data-validate

This takes a space-delimited list of the validators you want to run against the input. For instance, you might say data-validate="require pattern" - in this instance, you'd be asking the validator to run the 'require' and 'pattern' checks.

data-validate-errormessage-NAME

For every required check, you can provide a custom error message. For instance, if you want the error message to say 'Hey this field was required!' on an input where you specified data-validate='require', you would add the field data-validate-errormessage-required='Hey this filed was required!'. If you don't provide a custom message, a validator shoul have a default it can use.

data-validate-XXXXX

For custom validators (see below) it's sometimes necessary to pass in custom data attributes. By convention these should follow the format data-validate-XXX. For example, if you specified data-validate='foo', you could also pass in data-validate-foo-value='7' and your custom foo validator would be able to read that in and use it in the evaluation.

Default Validators

This tool ships with several validators ready for use. Any of these can be overridden by custom validators if you pass a validation function with the same name in on the config object.

required

This ensures that the tagged input has a value. Its default error message is 'failed to provide a required value.'. It has no additional requirements.

maxChars

This ensures that the tagged input has no more than a specified number of characters. Its default error message is 'Value length exceeds threshold of ' + threshold, and it requires a threshold value to be specified by means of the maxlength attribute on the input.

isEmail

This checks the input against a regex for properly formatted email addresses. The default error message is 'value must be a valid email address'. It has no additional requirements.

pattern

This checks the input against a custom regex pattern. The default error message is 'Value did not match pattern <' + pattern + '>'. The pattern is specified by setting the pattern attribute on the input element, and this is required.

isNumeric

This checks to ensure that the input is numeric. It can be used on a text input, but you should specify type="number" on your input for safety. Its default error message is 'input is not a numeric value' and it has no additional requirements.

passwordStrength

This validator is designed to work in tandem with the deque password quality evaluator. To use it, make sure you first pass in a passwordEvaluator function in on your config object (see below). You must then specify a minimum password quality, on a scale from 0-4, using the attribute data-validate-password-strength. The default error message is `Your password quality is ${quality + 1}/5 but needs to be at least ${threshold + 1}/5` (those +1's are there to make the zero-based quality index more human-readable).

Config Object

passwordEvaluator

This is an optional function for use with the password quality feedback component. If you provide this function, it must take a string as input (the user's password) and return a number between 0 and 4 as output. A 0 means the provided password is unacceptable, a 4 means it's great. You can choose to implement this logic however you see fit. If this function is present, it will be applied to any input[type='password'] fields in your code and they'll get a visual feedback meter. These fields will also be eligible for validation under the passwordStrength built-in validator.

[custom validators]

If you choose to perform any sort of custom validation, you may attach your custom validators to your config object. The name of your validator function is what you must specify in the data-validate attribute of any inputs you want to use it against. For instance, in the example above, we use a custom allcaps validator. We do this by adding allcaps: function(input) { ... } to the config object, and then adding the string 'allcaps' to the data-validate field for the pet name input.

Writing Custom Validators

To write a custom validation function you have to understand how this validation system works. It's all wired up using the data-attributes as described above. The validator function itself is called against the input fields it's attached to whenever the form is submitted.

In addition to returning true or false, the validator also attaches a special data attribute to the input in the event that it fails. The attribute's name is data-validate-failed-VALIDATOR-NAME, and the value is the error message. You can specify a custom error message on a per-input basis as described above, but your validator should define its own fallback message in case the user doesn't specify one.

Here's how the custom allcaps validation function looks, which we're using above.

function(input) {
   let value = input.value;
   const val = value === value.toUpperCase();
   if (!val) {
     let errorMessage = input.getAttribute('data-validate-errormessage-allcaps') || 'The value of this input field must be ALL CAPS to be valid.';
     input.setAttribute('data-validate-failed-allcaps', errorMessage);
   } else {
input.removeAttribute('data-validate-failed-allcaps');
   }
   return val;
}