FinalForm
HTML form fields parser
Installation
Using npm:
npm i -S finalform
Usage
There are two ways to use FinalForm:
- A quick form parser
- A more advanced custom form parser
Quick Form Parser
Simply pass a form element into the parseForm
method.
finalform;
Example
;const form = document;const formObj = finalform;
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
;const form = document;const formObj = finalform;
Custom Form Parser
Creating a Custom Parser
Create a custom parser using the createParser
method.
const customParser = finalform;
Running the Parser
const customParser = finalform;customParser;
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: Booleancompress: Booleanescape: BooleancheckboxFormat: Stringmap: 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;parser;
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.
const customParser = finalform;const parsedForm = parser;console; // ironman@stark.comconsole; // 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)
const customParser = finalform;const parsedForm = parser;console; // ironman@stark.comconsole; // 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.
const customParser = finalform;const parsedForm = parser;console; // ironman@stark.comconsole; // 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.
const customParser = finalform;const parsedForm = parser;console; // ''console; // falseconsole; // [ 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.
const customParser = finalform;parser;
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 validmsg
string - an optional string to give more context to the errormeta
object - an object to store any additional meta information relating to the validation
Example
let emailValidationCount = 0;const customParser = finalform;
Order of Operations
This is the order of operations that the Custom Parser Options are processed:
- Merge
forms
andcustomFields
pick
mapNames
validations
asyncValidations
values
transforms:trim
,compress
,escape
,map