@edkirin/formalizer v0.2.1

formalizer

Simple, but flexible and configurable form validity checker.

Features

• Written in Vanilla JavaScript, doesn't require jQuery

• Zero runtime dependencies

• Compatible with Bootstrap CSS framework
• Very small footprint - less than 8k, less than 3k gzipped

Building formalizer

Requirements

• nodejs

Build from source

$ git clone git@github.com:edkirin/formalizer.git
$ cd formalizer
$ npm install
$ npm run build

Install from npm

$ npm install @edkirin/formalizer

Basic usage

import { Formalizer } from "@edkirin/formalizer";

const formalizer = new Formalizer({
    form: document.querySelector('#myform'),
    language: 'en',
    errorReporting: 'element',
    validateOn: 'submit',
    handleSubmitButton: true
});

Constructor options

Options are set when formalizer object is created.

import { Formalizer } from "@edkirin/formalizer";

const formalizer = new Formalizer(options);

options.form : DOM element

Form element which will be handled by Formalizer. It could be provided by:

options.form = document.querySelector('#myform');

or using jQuery:

options.form = $('#myform')[0];

options.invalidClass : string

CSS class which will be applied to input field which fails to validate.

default: is-invalid

options.validClass : string

CSS class which will be applied to input field which validates correctly.

default: is-valid

options.focusOnError : bool

If true, first invalid input field will be focused on validation error.

default: true

options.onValidate : callback

Optional callback which is called after form validation occurs. Callback function is called with following parameters as object:

callback(params);

​ params.formalizer: Formalizer object, as sender

​ params.form: current form

​ params.isValid: represents actual form validity

Callback function is optional.

default: null

options.onInvalidElement : callback

Optional callback which is called after input element is detected as invalid. Callback function is called with following parameters as object:

callback(params);

​ params.formalizer: Formalizer object, as sender

​ params.form: current form

​ params.errMessage: error message with which validation failed

Callback function is optional.

default: null

options.language : string

Language code for error messages. For supported languages check src/i18n directory.

options.errorReporting : string

Defines how validation errors appear. Possible values are:

• none - No error messages are reported, just CSS classes are set on elements
• hint - Title hint on input field with error message is set.
• element - DOM element with error message is created after input field.

default: element

options.errorTemplate : string

HTML template template which will be used for creating DOM element when options.errorReporting option is set to element. Example:

options.errorTemplate = '<small class="form-text text-danger" id="%id">%message</small>';

Template must contain two template fields which will be in the run time substituted with actual values:

• %id
• %message

You don't need to set values for those fields, just provide their places in your template.

default: template above

options.validateOn : string

This option defines when validation function is triggered. Possible values are:

• manual
• submit
• input
• focus

manual

Form validation is triggered manually, by calling Formalizer method:

formalizer.validate();

submit

Form validation is triggered uppon the form submit. If form contains errors, submit is cancelled.

input

Form validation is triggered when key is pressed.

focus

Form validation is triggered when input fields focus is changed.

options.handleSubmitButton : bool

If option is set to true, Formalizer will take control over form submit button and set his enabled state according to validation result.

Note: It's not possible to use this option in conjunction with options.validateOn = 'submit'. If this is the case, validateOn will fallback to input.

default: false

API

validate()

Manually triggers form validity check, regardless of validateOn option.

const formalizer = new window.formalizer.Formalizer({
    ...
});

formalizer.validate();

reset()

Resets form and sets all elements to unvalidated state.

formalizer.reset();

raiseError(element, errorMessage)

Method manually raises error on element with provided error message.

formalizer.raiseError(
    document.querySelector('input[name="email"]'),
    "Email address already exists!"
);

Markup

Formalizer will perform validation checks on:

• input fields of type text, password, number and email
• textarea

Check if value is entered

To set field as required, use required attribute on input field.

<input type="text" name="myfield" required>

Used on:

• input fields
• textarea fields

Check length of entered text

To check length, use minlength and/or maxlength attributes on input field.

<input type="text" name="myfield" minlength="5" maxlength="10">

Used on:

• input fields
• textarea fields

Check if value is valid email

Every email input field will be automatically test for email format validity.

Used on:

• input fields of type email

Check if number is valid

Input fields of type number will be validated for number validity. Optionally, min and max values can be also validated.

<input type="number" name="myfield1" min="0" max="100">
<input type="number" name="myfield2" min="5">

Check if two fields are equal

To ensure user entered exact value in two fields, use data-validate-equalto attribute and set value to other field id.

<input type="password" id="password1" data-validate-equalto="#password2">
<input type="password" id="password2" data-validate-equalto="#password1">

Preventing validation on certain fields

To prevent validation on certain fields, use data-validate="off".

<input type="text" name="myfield" data-validate="off">

Change log

0.2.1

• Added manual raising error with raiseError() method.

0.2.0

• Added equal-to validator.

0.1.4

• Initial version.

Licence

The code is available under MIT Licence.