FinalForm

HTML form fields parser

Installation

Using npm:

npm i -S finalform

Usage

There are two ways to use FinalForm:

1. A quick form parser
2. A more advanced custom form parser

Quick Form Parser

Simply pass a form element into the parseForm method.

finalform.parseForm(HTMLElement[, {/* values options */}]);

Example

import finalform from 'finalform';

const form = document.querySelector('#myForm');
const formObj = finalform.parseForm(form);

Values Config

Pass an object of options as the second parameter to modify the values.

Available Options:

| Option | Type | Description | Default Value | | -------------- | ------------- | ------------------------------ | ------------- | |trim|Boolean|removes spaces from beginning/end of string|true| |compress|Boolean|compress multiple sequential blank spaces to a single space|true| |escape|Boolean|Converts certain characters to corresponding HTML entities|false| |checkboxFormat|String ('object', 'array')|whether checkbox result should be an object of true, false or an array of just the true values|'object'| |map|Function @param inputValue@param inputName@param inputType@return newValue| map all of the parsed values to new value|null|

Example

import finalform from 'finalform';

const form = document.querySelector('#myForm');
const formObj = finalform.parseForm(form, {
    trim: false,
    compress: false,
    escape: true,
    checkboxFormat: 'object'
    map: (value, name, type) => value // do something to value
});

Custom Form Parser

Creating a Custom Parser

Create a custom parser using the createParser method.

const customParser = finalform.createParser({ /* parser options */ });

Running the Parser

const customParser = finalform.createParser({ /* parser options */ });
customParser.parse();

Custom Parser Options

There are a handful of options to specify in the custom parser. Here is an example of all of the available properties (a description of each is given after the example):

| Option | Type | Description | Default Value | | -------------- | ------------- | ------------------------------ | ------------- | |forms|Array|array of HTML elements to parse|[]| |mapNames|Object|map the html element names to new name|{}| |pick|Array|filter fields in parsed output|{}| |customFields|Object|define custom fields that may not be derived from any HTML element|{}| |validations|Object|synchronous validations to run on specified fields|{}| |asyncValidations|Object|asynchronous validations to run on specified fields|{}| |values|Object|(See Values Config section)|

{
  forms: [],
  mapNames: {},
  pick: [],
  customFields: {},
  validations: {},
  asyncValidations: {},
  values: {
    trim: Boolean,
    compress: Boolean,
    escape: Boolean,
    checkboxFormat: String,
    map: Function,
  }
}

Adding Forms to Custom Parser

You can add as many forms as you want to the custom parser using the forms array, it will parse them all at one.

const customParser = finalform.createParser({ forms: [HTMLElement, /*etc*/] });
parser.parse();

Changing Field Names in the Output

If you want to take the output of the parser and plug it into another API, you will probably want to change the name of some of the fields.

<input type="text" name="user-email" value="[email protected]" />
<input type="text" name="user-company" value="Stark Industries" />

const customParser = finalform.createParser({
  /*other options...*/
  mapNames: {
    'user-email': 'Email',
    'user-company': 'Company'
  }
});
const parsedForm = parser.parse();

console.log(parsedForm.Email); // [email protected]
console.log(parsedForm.Company); // Stark Industries

Picking Specified Fields

If you want to take the output of the parser and plug it into another API, you will probably want to only pick a few fields from the output.

(This feature is based off of Lodash's pick)

<input type="text" name="email" value="[email protected]" />
<input type="text" name="company" value="Stark Industries" />

const customParser = finalform.createParser({
  /*other options...*/
  pick: ['email']
});
const parsedForm = parser.parse();

console.log(parsedForm.email); // [email protected]
console.log(parsedForm.company); // undefined

Adding Custom Fields to the Parser

You can attach custom fields to the parser. This allows you to pull in additional data that may not be associated with any form.

<input type="text" name="email" value="[email protected]" />
<input type="text" name="company" value="Stark Industries" />

const customParser = finalform.createParser({
  /* other options... */
  customFields: {
    location: () => {
      // do some calculations
      return 'Manhattan';
    }
  }
});
const parsedForm = parser.parse();

console.log(parsedForm.email); // [email protected]
console.log(parsedForm.location); // Manhattan

Syncronous Validations

You can specify validations to run against all of the values and return whether it is valid or not.

You can return a boolean or an object with the format { isValid: Boolean, msg: String } for easy error messages.

<input type="text" name="email" value="" />
<input type="text" name="company" value="Stark Industries" />

const customParser = finalform.createParser({
  /* other options... */
  validations: {
    email: value => {
      if (email.trim().length)
        return true;
      else
        return { isValid: false, msg: 'Field is required' }
    }
  }
});
const parsedForm = parser.parse();

console.log(parsedForm.email); // ''
console.log(parsedForm.isValid); // false
console.log(parsedForm.invalidFields); // [ Object ]

Asyncronous Validations

Asynchronous validations are good if you need to hit up a server before validating some fields.

You can return a boolean or an object with the format { isValid: Boolean, msg: String } for easy error messages.

When using asynchronous validations the parse method will return a promise.

<input type="text" name="email" value="[email protected]" />
<input type="text" name="company" value="Stark Industries" />

const customParser = finalform.createParser({
  /* other options... */
  asyncValidations: {
    email: (value, done) => {
      // query the server to see if email is taken
      // ...
      const emailAvailable = isEmailAvailable(value); 
      // ...

      if (emailAvailable)
        return done(true);
      else
        return done({ isValid: false, msg: 'Email already used' });
    }
  }
});

parser.parse().then(parsedForm => {
  console.log(parsedForm.email); // [email protected]
  console.log(parsedForm.isValid); // false
  console.log(parsedForm.invalidFields); // [ Object ]
});

Validation Return Object

The object that can be returned from both synchronous and asynchronous validations takes the following properties:

• isValid boolean - specifies the validation is valid
• msg string - an optional string to give more context to the error
• meta object - an object to store any additional meta information relating to the validation

Example

let emailValidationCount = 0;
const customParser = finalform.createParser({
  /* other options... */
  validations: {
    email: value => {
      if (email.trim().length)
        return true;
      else {
        return {
          isValid: false,
          msg: 'Field is required',
          meta: {
            validationCount: emailValidationCount++,
            isEmpty: email.trim().length === 0
          }
        };
      }
    }
  }
});

Order of Operations

This is the order of operations that the Custom Parser Options are processed:

1. Merge forms and customFields
2. pick
3. mapNames
4. validations
5. asyncValidations
6. values transforms: trim, compress, escape, map