Forms-and-fields NPM

Forms and Fields

GitHub Workflow Status

A library to validation fields and submission forms.

For validation you can use required validator, one of validator validators (e.g. isEmail) or custom validator (including AJAX).

Usage

HTML:

<form class="js-form">
    <div>
        <input type="text" name="email" class="js-email"/>
    </div>
    <button type="submit">Submit</button>
</form>

JS:

import Form from 'forms-and-fields';
import Field from 'forms-and-fields';
import SubmissionResult from 'forms-and-fields';

const form = new Form('.js-form', [
   new Field('.js-email', ['required', 'isEmail'], {
        invalidMessages: {
            required: 'Email is required',
            isEmail: 'Invalid email'
        }
   })
], {
    onAfterFieldValidate: (validationResult) => {
        console.log(validationResult);
    },
    submit: (formData) => {
        console.log(formData);
        // here can be AJAX-request
        return new SubmissionResult(true);
    }
});

form.listen();

Console:

When you submit form with empty email:

ValidationResult {result: false, message: "Email is required"}

When you submit form with invalid email:

ValidationResult {result: false, message: "Invalid email"}

When you submit form with valid email:

ValidationResult {result: true, message: ""}
FormData {...}

Extended example:

See more extended examples in sandbox

Installation

npm install forms-and-fields

Documentation

Common

For validation and submission form you need create Form object (with needed Field objects) and call listen method.

Form validation is all fields validation and form is valid when all fields are valid.

For validation separate fields you need create Field object and call listen method.

Custom validators must return ValidationResult (can return Promise, so you can use AJAX).

Form submit callback must return SubmissionResult (can return Promise, so you can use AJAX).

Validation is triggered when user submits form. Form is not submitting if form is invalid.

`ValidationResult` class

Method	Description
constructor(result: `boolean`, message?: `string` = '')	Initializes validation result object
isValid(): `bool`	Returns boolean validation result
hasMessage(): `bool`	Returns validation result message existing
setMessage(message: `string`): `void`	Sets validation result message
getMessage(): `string`	Returns validation result message

`SubmissionResult` class

Method	Description
constructor(result: `boolean`, data?: `object` = {})	Initializes submission result object with any data
isSuccess(): `boolean`	Returns boolean submission result
getData(): `object`	Returns data

Fields

`Field` class

Method	Description
constructor (fieldSelector: `string`, validators?: `object`, options?: `object` = {})	Initializes field object with validators (see `Field` validators) and options (see `Field` options) for field with `fieldSelector` selector
setOptions(options: `object`): `void`	Sets options (see `Field` options)
listen(): `void`	Starts listening field for triggering validation and trimming (if enabled)
isValid(force: `boolean`): `Promise<boolean>`	Returns boolean validation result (if field not yet validated or `force` is `true` then field is validated).
validate(): `Promise<void>`	Validates field

`Field` validators

Array of validators. Each validator can be string (name of validator) or function (custom validator). Allowed validator names: required or one of validator validators (e.g. isEmail). It is allowed only required validator for checkbox, select, radio and file input elements.

`Field` options

Option	Type	Default	Description
formElement	`HTMLElement`	`document`	Form element that contains field
validMessage	`string`	`''`	Message about valid value that passing to `ValidationResult`
invalidMessages	`object`	`{}`	Messages about invalid value for each validator that passing to `ValidationResult`. E.g. `{isEmail: 'Invalid Email'}`
defaultInvalidMessage	`string`	`'Invalid value.'`	Message about invalid value that passing to `ValidationResult` (if not found in `invalidMessages`)
validateOnChange	`boolean`	`false`	Whether to validate on change field value
validateOnType	`boolean`	`false`	Whether to validate on typing field value
typingDelay	`number`	1000	It is considered that user is typing when time between taps less than this value (ms)
onTypingStart	`function`	`null`	It is triggered when user has started typing. Passes arguments: `value: string, fieldElement: HTMLElement, formElement: HTMLElement`
onTypingEnd	`function`	`null`	It is triggered when user has finished typing. Passes arguments: `value: string, fieldElement: HTMLElement, formElement: HTMLElement`
onChange	`function`	`null`	It is triggered when user has changed field. Passes arguments: `value: string, fieldElement: HTMLElement, formElement: HTMLElement`
validatorParams	`object`	`{}`	Params for validator. (E.g. `{isEmail: {allow_utf8_local_part: false}}`)
trimEnabled	`boolean`	`true`	Whether to trim field value on validation
onBeforeValidate	`function`	`null`	It is triggered before field validation. Passes arguments: `fieldElement: HTMLElement, formElement: HTMLElement`
onAfterValidate	`function`	`null`	It is triggered after field validation. Passes arguments: `validationResult: ValidationResult, fieldElement: HTMLElement, formElement: HTMLElement`

Forms

`Form` class

Method	Description
constructor(formSelector: `string`, fields?: `object` = [], options?: `object` = {})	Initializes form object with fields (see `Field` class) and options (see `Form` options) for form with `formSelector` selector
listen(): `void`	Starts listening form for triggering validation, trimming (if enabled, for each field) and submission
isValid(force: `boolean`): `Promise<boolean>`	Returns boolean validation result (calls `isValid` method for each field)
validate(): `Promise<void>`	Validates form (each field)

`Form` options

Form supports all Field options (besides formElement) and sets this options to each form field (Field options have higher priority).

Also Form supports following options:

Option	Type	Default	Description
onBeforeValidate	`function`	`null`	It is triggered before form validation. Passes argument `formElement: HTMLElement`
onAfterValidate	`function`	`null`	It is triggered after form validation. Passes arguments: `isValid: boolean, formElement: HTMLElement`
onBeforeSubmit	`function`	`null`	It is triggered when user submits form and before validation. Passes `formData: FormData, formElement: HTMLElement`
submit	`function`	`null`	Submit function. It is triggered when user submits form and after validation. Must return `SubmissionResult` (can return `Promise`, so you can use AJAX). If exception occurred it is equivalent to `submit` returned `SubmissionResult` with `false` (error is logged to console). Passes `formData: FormData, formElement: HTMLElement`
onAfterSubmit	`function`	`null`	It is triggered after submission. Passes `submissionResult: SubmissionResult, formElement: HTMLElement`
onAfterSubmitSuccess	`function`	`null`	It is triggered after submission and `submit` function returned `SubmissionResult` with `true`. Passes `submissionResultData: object, formElement: HTMLElement`
onAfterSubmitError	`function`	`null`	It is triggered after submission and `submit` function returned `SubmissionResult` with `false`. Passes `submissionResultData: object, formElement: HTMLElement`
onBeforeFieldValidate	`function`	`null`	It is triggered before each field validation. Passes arguments: `fieldElement: HTMLElement, formElement: HTMLElement`
onAfterFieldValidate	`function`	`null`	It is triggered after each field validation. Passes arguments: `validationResult: ValidationResult, fieldElement: HTMLElement, formElement: HTMLElement`

To set onBeforeValidate or onAfterValdiate to each form field use onBeforeFieldValidate or onAfterFieldValidate, because onBeforeValidate and onAfterValidate are for form.

CSS classes

Special CSS classes are added dynamically to form and fields on validation and submission:

f-field-validating
f-field-valid
f-field-invalid
f-form-validating
f-form-valid
f-form-invalid
f-form-submitting
f-form-submit-success
f-form-submit-error

You can wrap one field by container element with js-f-field-container css class and then special classes will be added to it. This is especially useful for checkboxes and radio elements.