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:

<!-- Field -->
<input name="userName" />

<script>
    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',
                        },
                    },
                },
            },
        });
    });
</script>

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:

<html>
    <head>
        <link rel="stylesheet" href="/vendors/@form-validation/umd/styles/index.min.css" />
    </head>
    <body>
        <form id="demoForm" method="POST">
            ...
            <!-- Declare the validator rules -->
            <input
                name="userName"
                data-fv-not-empty="true"
                data-fv-not-empty___message="The username is required"
                data-fv-string-length="true"
                data-fv-string-length___min="6"
                data-fv-string-length___message="The name must be more than 6 characters long"
            />
        </form>

        <script src="https://cdnjs.cloudflare.com/ajax/libs/es6-shim/0.35.3/es6-shim.min.js"></script>
        <script src="/vendors/@form-validation/umd/bundle/popular.min.js"></script>

        <script>
            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: ...,
                            }),
                        },
                    }
                );
            });
        </script>
    </body>
</html>

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.

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:

notEmpty validator

// Programmatic mode
notEmpty: {
    message: ...,
}

// Declarative mode
data-fv-not-empty="true"
data-fv-not-empty___message="..."

stringLength validator

// Programmatic mode
stringLength: {
    min: ...,
    max: ...,
    utf8Bytes: ...,
}

// Declarative mode
data-fv-string-length="true"
data-fv-string-length___min="..."
data-fv-string-length___max="..."
data-fv-string-length___utf8-bytes="..."

uri validator

// Programmatic mode
uri: {
    allowLocal: ...,
    message: ...,
    allowEmptyProtocol: ...,
}

// Declarative mode
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:

<div class="mb2">
    <label>
        <input type="checkbox" name="size[]" value="s" data-fv-not-empty="true" data-fv-not-empty___message="The size is required" />
        S
    </label>
</div>
<div class="mb2">
    <label><input type="checkbox" name="size[]" value="m" /> M</label>
</div>
<div class="mb2">
    <label><input type="checkbox" name="size[]" value="l" /> L</label>
</div>
<div class="mb2">
    <label><input type="checkbox" name="size[]" value="xl" /> XL</label>
</div>

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

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:

<form
    id="demoForm"
    method="POST"
    data-fvp-trigger="true"
    data-fvp-trigger___class="FormValidation.plugins.Trigger"
    data-fvp-tachyons="true"
    data-fvp-tachyons___class="FormValidation.plugins.Tachyons"
    data-fvp-submit-button="true"
    data-fvp-submit-button___class="FormValidation.plugins.SubmitButton"
    data-fvp-icon="true"
    data-fvp-icon___class="FormValidation.plugins.Icon"
    data-fvp-icon___valid="fa fa-check"
    data-fvp-icon___invalid="fa fa-times"
    data-fvp-icon___validating="fa fa-refresh"
>
    ...
</form>

<script>
    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(),
            },
        });
    });
</script>

It serves the same functionalities such as declaring plugins as

<form id="demoForm">...</form>

<script>
    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',
                }),
            },
        });
    });
</script>

Using the npm packages

If you are using a bundler such as Webpack, Rollup, Parcel or Vite, etc., to bundle your application, then it's recommended to use the FormValidation NPM packages.

Install the packages:

$ npm install @form-validation/bundle
$ npm install @form-validation/plugin-declarative

Import and use the Alias plugin:

import { formValidation } from '@form-validation/bundle/popular';
import { Declarative } from '@form-validation/plugin-declarative';

formValidation(
    document.getElementById('demoForm'),
    {
        fields: {
            ...
        },
        plugins: {
            declarative: new Declarative({
                html5Input: ...,
                prefix: ...,
            }),
            ...
        },
    }
);

Basic example

Declarative plugin

Changelog

v2.2.0

Setting the enabled attribute to false doesn't work

v2.0.0

Add the npm package

v1.7.0

Parse validator options of element attributes when a field is added via the addField() method
Fixed an issue that the plugin doesn't set the correct values for boolean options. For example, it transformts data-fv-between___inclusive="false" to inclusive: 'false', not inclusive: false.

v1.4.0

Support the plugin declarations

v1.0.0

First release

Bulma plugin DefaultSubmit plugin

Declarative plugin

Usage

Options for plugin declarations

Using the npm packages

Basic example

See also

Changelog