@lmc-eu/spirit-form-validations
TypeScript icon, indicating that this package has built-in type declarations

1.1.2 • Public • Published

@lmc-eu/spirit-form-validations

Form validations for Web and Web-Twig packages of the Spirit Design System.

Install

yarn add @lmc-eu/spirit-form-validations

or

npm install --save @lmc-eu/spirit-form-validations

Usage

Include the JavaScript file in your HTML <head> or just before the closing <body> tag.

<script src="dist/bundles/umd/spirit-form-validations.min.js"></script>

Or

<script src="dist/bundles/esm/spirit-form-validations.js" type="module"></script>

Now create a form:

<form id="form1">
  <label for="email">Email</label>
  <input type="email" id="email" required />
  <button>Subscribe</button>
</form>

… and validate it:

window.onload = () => {
    const form = document.getElementById("form1");

    // create the FormValidations instance
    const formValidations = new FormValidations(form);

    form.addEventListener('submit', function (event) {
       event.preventDefault();

       // check if the form is valid
       const valid = formValidations.validate(); // returns true or false
    });
};

Profit

The goal of this library is not to provide every possible type of validation and thus becoming a bloat. The goal is to provide most common types of validations and a neat way to add custom validators.

It automatically validates required, min, max, minlength, maxlength attributes and the value of type attributes like email, number and more… The library is built on top of native validation attributes as replace for native browser validation, not a progressive enhancement. Using the novalidate attribute the library is turning off the browser validations and does the heavy lifting itself.

FormValidations takes 3 parameters:

  • form - The form element

  • config - An object containing the configuration. Default is Spirit's configuration which is

const defaultConfig = {
  formFieldSelector: '[data-spirit-validate]',
  errorClass: 'has-danger',
  successClass: 'has-success',
  validationTextParentSelector: '[data-spirit-validate]',
  validationTextTag: 'div',
  validationTextClass: '',
  dataElementMessage: 'validation-text',
};
  • live - A boolean value indicating whether FormValidations should validate as you type, default is true

Built-in validators

Name Usage Description
required required or data-spirit-required Validates required fields
email type="email" or data-spirit-type="email" Validates email
number type="number" or data-spirit-type="number"
integer data-spirit-type="integer"
minlength minlength="10" or data-spirit-minlength="10"
maxlength maxlength="10" or data-spirit-maxlength="10"
min min="20" or data-spirit-min="20"
max max="100" or data-spirit-max="100"
pattern pattern="/[a-z]+$/i" or data-spirit-pattern="/[a-z]+$/i", \ must be escaped (replace with \\)
equals data-spirit-equals="#field-selector" Check that two fields are equal

Custom Validator

FormValidations.addValidator(nameOrElem, handler, errorMessage, priority, halt);

Add a custom validator to a field

var formValidations = new FormValidations(document.getElementById('form1'));

var element = document.getElementById('email');

// A validator to check if the first letter is capitalized
FormValidations.addElementValidator(
  element,
  function (value) {
    if (value.length && value[0] === value[0].toUpperCase()) {
      return true;
    }
    return false;
  },
  'The first character must be capitalized',
  2,
  false,
);

Add a global custom validator

A validator to check if the input value is within a specified range.

⚠️ Global validators must be added before creating the FormValidations instance.

⚠️ There are several build-in validators with reserved names, see Built-in validators section. By using the same name you can override those validators.

FormValidations.addValidator(
  'my-range',
  function (value, param1, param2) {
    return parseInt(param1) <= value && value <= parseInt(param2);
  },
  'The value (${0}) must be between ${1} and ${2}',
  5,
  false,
);

Now you can assign it to your inputs like this

<input type="text" class="form-control" data-spirit-my-range="10,30" />

Add custom error messages

<input required data-spirit-required-message="My custom message" />

Add an attribute like data-spirit-<ValidatorName>-message with the custom message as a value to show custom error messages. You can add custom messages like this for as many validators as you need. Here ValidatorName means required, email, min, max etc.

API

Initialization

FormValidations(form, config, live)

Constructor

Parameter Default Required Description
form The form element
config See above The config object
live true Whether FormValidations should validate as you type

Validation

FormValidations.validate(inputs, silent)

Validate the form or field(s)

Parameter Default Required Description
inputs When not given, the entire form is validated. Inputs can either be one DOM element or a collection of DOM elements returned by document.getElement…, document.querySelector…
silent false Does not show error messages when silent is true

FormValidations.getErrors(input)

Get the errors of the form or a specific field

Parameter Default Required Description
input When input is given, it returns the errors of that input element, otherwise returns all errors of the form as an object, using input element as key and corresponding errors as value. validate() must be called before expecting this method to return correctly.

Localization

FormValidations.setLocale(locale)

Set the current locale globally

Parameter Default Required Description
locale Error messages on new FormValidations forms will be displayed according to this locale

FormValidations.addMessages(locale, messages)

Set the current locale globally

Parameter Default Required Description
locale The corresponding locale
messages Object containing validator names as keys and error texts as values

Custom validators

FormValidations.addElementValidator(elem, fn, message, priority, halt)

Add a custom validator

Parameter Default Required Description
element The dom element where validator is applied to.
halt false Whether to stop validation of the field after this validator is applied on the field. When true, after this validator finishes validating, the rest of the validators are ignored on the current field.
message The message to show when the validation fails. It supports simple templating. ${0} for the input's value, ${1} and so on are for the attribute values. For the above example, ${0} will get replaced by myValue, ${1} by 10, ${2} by 20, ${3} by dhaka. It can also be a function which should return the error string. The values and inputs are available as function arguments
priority 1 Priority of the validator function. The higher the value, the earlier it gets called when there are multiple validators on one field.
validatorCallback The function that validates the field. The value of the input field gets passed as the first parameter, and the attribute value (split using a comma) as the subsequent parameters. For example, for <input data-spirit-my-validator="10,20,dhaka" value="myValue"/>, the validator function gets called like validatorCallback("myValue", 10, 20, "dhaka"). Inside the function this refers to the input element

FormValidations.addValidator(name, fn, message, priority, halt)

Add a global custom validator

Parameter Default Required Description
name A string, the name of the validator, you can then use data-spirit-<NAME> attribute in form fields to apply this validator
.... Other parameters same as above

Resetting

FormValidations.reset()

Reset the errors in the form

FormValidations.destroy()

Destroy the pristine object

Readme

Keywords

none

Package Sidebar

Install

npm i @lmc-eu/spirit-form-validations

Weekly Downloads

42

Version

1.1.2

License

MIT

Unpacked Size

196 kB

Total Files

38

Last publish

Collaborators

  • dlouhak
  • crishpeen
  • petrofcikmatus
  • martinhrdlicka
  • petrlz
  • ondram
  • literat
  • pavelklibani