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.
OptionTypeDescription
html5InputBooleanSet 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
prefixStringThe 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:
// Programmatic mode
notEmpty: {
message: ...,
}
// Declarative mode
data-fv-not-empty="true"
data-fv-not-empty___message="..."
// 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="..."
// 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
OptionTypeDescription
pluginPrefixStringThe 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

See also

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