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 for field declarations

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 prefixName-validatorName___optionName, where

  • prefixName is replaced with the prefix option above
  • validatorName 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
  • optionName 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.

Options for plugin declarations

Notice

The plugin declaration isn't supported when using with ES6 module.
Option Type Description
pluginPrefix String The prefix of plugin declaration attributes. By default, it is set to data-fvp-

The HTML attribute is a combination of prefixName-pluginName___optionName, where

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

Each plugin declaration requires an attribute named prefixName-pluginName___class which indicates the plugin class. All the plugin declarations need to be set for the form element.

Following is a simple code that demonstrates how to declare the attributes for plugins:


...
document.addEventListener('DOMContentLoaded', function(e) { const form = document.getElementById('demoForm'); FormValidation.formValidation(form, { plugins: { // You have to register the Declarative plugin only declarative: new FormValidation.plugins.Declarative() } }); });

It serves the same functionalities such as declaring plugins as


...
document.addEventListener('DOMContentLoaded', function(e) { const form = document.getElementById('demoForm'); FormValidation.formValidation(form, { plugins: { declarative: new FormValidation.plugins.Declarative(), // Other plugins trigger: new FormValidation.plugins.Trigger(), tachyons: new FormValidation.plugins.Tachyons(), submitButton: new FormValidation.plugins.SubmitButton(), icon: new FormValidation.plugins.Icon({ valid: 'fa fa-check', invalid: 'fa fa-times', validating: 'fa fa-refresh', }), } }); });

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

Changelog

  • v1.4.0: Support the plugin declarations
  • v1.0.0: First release