formValidityState

EventEmitter that monitors a form element's validity, applying classes and emitting events accordingly.

This module will monitor all forms on a page matching the selector option, applying a class name invalidClass to invalid fields and the form itself. The module also augments EventEmitter, providing more granular control to manage a form's state.

Form and field validity states are determined as fields are updated with native HTML5 form validation. Therefore all validation rules (such as required, min/max values, and pattern matching) should be set directly in the HTML as they would be normally.

Form submission is prevented if a form is in an invalid state when submitted. An event is emitted providing the original submit event as a parameter. This allows the developer to prevent submission regardless of the form's state.

Installation

Install via npm:

$ npm i form-validity-state -S

Usage

Default implementation (auto-initialization):

var FormState = require('form-validity-state');
var formState = new FormState();

Manual initialization:

var FormState = require('form-validity-state');
var formState = new FormState({autoInitialize: false});

// Attach your listeners or whatever 
// else needs doing before the module
// queries the DOM and begins monitoring
formState.initialize();

Options

| Param | Type | Default | Description | | --- | --- | --- | --- | | options.invalidClass | string | "invalid" | Class to be applied to invalid forms and inputs | | options.selector | string | "form[data-validation-state]" | Selector used to query participating form elements | | options.autoInitialize | boolean | true | DOM is queried upon instantiation; set to false if you need to capture the initial "invalidated" event |

Methods

initialize() ➝ null

Manually initializes module in case event listeners should be tethered before initial validity state is established

destroy() ➝ null

Destroys the instance, removing all event listeners and DOM references

Events

invalidated

The invalidated event is broadcast when a form's validity state changes from valid to invalid

| Name | Type | Description | | --- | --- | --- | | data | object | Emitted data object | | data.evt | event | Original event | | data.formObject | object | formObject of input that event was triggered from |

submit-blocked

The submit-blocked event is broadcast when a form's submission is prevented because it is in an invalid state

| Name | Type | Description | | --- | --- | --- | | data | object | Emitted data object | | data.evt | event | Original event | | data.formObject | object | formObject of input that event was triggered from |

submit-allowed

The submit-allowed event is broadcast when a form's submission is allowed because it is in a valid state

| Name | Type | Description | | --- | --- | --- | | data | object | Emitted data object | | data.evt | event | Original event | | data.formObject | object | formObject of input that event was triggered from |

change

The change event is broadcast when a field's "change" event is triggered

| Name | Type | Description | | --- | --- | --- | | data | object | Emitted data object | | data.evt | event | Original event | | data.formObject | object | formObject of input that event was triggered from |

input

The input event is broadcast when a field's "input" event is triggered

| Name | Type | Description | | --- | --- | --- | | data | object | Emitted data object | | data.evt | event | Original event | | data.formObject | object | formObject of input that event was triggered from |

form-validated

The form-validated event is broadcast when a form's validity state changes from invalid to valid

| Name | Type | Description | | --- | --- | --- | | data | object | Emitted data object | | data.evt | event | Original event | | data.formObject | object | formObject of input that event was triggered from |

form-invalidated

The form-invalidated event is broadcast when a form's validity state changes from valid to invalid

| Name | Type | Description | | --- | --- | --- | | data | object | Emitted data object | | data.evt | event | Original event | | data.formObject | object | formObject of input that event was triggered from |

field-validated

The field-validated event is broadcast when a field's validity state changes from invalid to valid

| Name | Type | Description | | --- | --- | --- | | data | object | Emitted data object | | data.evt | event | Original event | | data.formObject | object | formObject of input that event was triggered from |

field-invalidated

The field-invalidated event is broadcast when a field's validity state changes from valid to invalid

| Name | Type | Description | | --- | --- | --- | | data | object | Emitted data object | | data.evt | event | Original event | | data.formObject | object | formObject of input that event was triggered from |