rincler/forms-and-fields

A library to validation fields and submission forms

Forms and Fields

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.

License

This library is released under the MIT license.