Declarative plugin

Provide the ability of declaring validator options via HTML attributes

Usage

As you know, you can declare the field validators in programmatic way:






document.addEventListener('DOMContentLoaded', function(e) {
    FormValidation.formValidation(
        document.getElementById('demoForm'),
        {
            fields: {
                userName: {
                    validators: {
                        notEmpty: {
                            message: 'The username is required'
                        },
                        stringLength: {
                            min: 6,
                            message: 'The name must be more than 6 characters long'
                        },
                    }
                }
            },
        }
    );
});

This plugin allows to set the validator options by using equivalent HTML attributes. The following piece of code demonstrates how the Declarative plugin does it:




    


    
...
document.addEventListener('DOMContentLoaded', function(e) { FormValidation.formValidation( document.getElementById('demoForm'), { // You don't need to declare the field validator here anymore plugins: { ..., declarative: new FormValidation.plugins.Declarative({ html5Input: ..., prefix: ..., }), }, } ); });

The sample code above assumes that the FormValidation files are placed inside the vendors directory. You might need to change the path depending on where you place them on the server.

Options

Option Type Description
html5Input Boolean Set it to true to enable the validators automatically based on the input type or particular HTML 5 attributes. By default, it's set to false. Look at the HTML 5 example below for more information.
prefix String The prefix of attributes. By default, it is set to data-fv-

The HTML attribute is a combination of prefix-validator___option, where

  • prefix is replaced with the prefix option above
  • validator is replaced with the lowercase of validator's name. Any uppercase characters found in validator's name has to be turned into a dash (-) followed by its lowsercase
  • option is replaced with the lowsercase of validator's option. Any uppercase characters found in validator's option has to be turned into a dash (-) followed by its lowsercase

Below is a few examples of declaring validator options in both programmatic and declarative modes:

Validator Programmatic mode Declarative mode
notEmpty

notEmpty: {
    message: ...,
}    

data-fv-not-empty="true"
data-fv-not-empty___message="..."
stringLength

stringLength: {
    min: ...,
    max: ...,
    utf8Bytes: ...,
}    

data-fv-string-length="true"
data-fv-string-length___min="..."
data-fv-string-length___max="..."
data-fv-string-length___utf8-bytes="..."
uri

uri: {
    allowLocal: ...,
    message: ...,
    allowEmptyProtocol: ...,
}    

data-fv-uri="true"
data-fv-uri___allow-local="..."
data-fv-uri___message="..."
data-fv-uri___allow-empty-protocol="..."

If there are multiple elements having the same name, you just need to set the HTML attribute to one of them. For example:


There are some validators which not all options are configurable via HTML attribute. Refer to each validator documentation to see exactly the equivalent HTML attribute for each option.

In that case, you can use both programmatic and declarative modes to set the validator options.

Basic example

Example: Using HTML 5 inputs and attributes

When the html5Input option is set to true, the Declarative plugin will automatically enable the validators for the following input type and HTML 5 attributes:

HTML 5 attribute Equivalent validator
max="..." lessThan
min="..." greaterThan
maxlength="..." stringLength
minlength="..." stringLength
pattern="..." regexp
required notEmpty
type="color" color
type="email" emailAddress
type="range" between
type="url" uri