Form Data Json - Form input values to/from JSON (And a bit more...)
A zero dependency, cross browser library to easily get or set/manipulate form input values as/from a json object. It can handle all input types, including multidimensional array names and file input. Native FormData is limited to reading only, we have way more:
- Read data as multidimensional object or as a flat list (similar to FormData)
- Write data into forms
- Read unchecked/disabled fields as well
- Read file inputs as base64, arraybuffer, etc...
- Clear forms
- Reset forms to their defaults
- And, you don't even need a
<form>element, we accept every container, even the<body> - Super small: ~3kB gzipped
- Cross Browser including IE11 (Yes, the ugly one also)
Installation
Download latest release and include dist/form-data-json.min.js into your project.
<script src="dist/form-data-json.min.js"></script>CDN (Latest version automatically, do not use it in production because of possible breaking changes)
<script src="https://cdn.jsdelivr.net/npm/form-data-json-convert/dist/form-data-json.min.js"></script>NPM
npm install form-data-json-convert
// import in NodeJS: const FormDataJson = require('form-data-json-convert')What's not supported
- Write to
<input type="file">It's impossible in javascript to set values for file inputs, for security reasons. However, reading file input as base64 data uri string is supported.
How to use
Read data
let values = FormDataJson.toJson(document.querySelector("form")) // with native element
let values = FormDataJson.toJson("#form-id") // with selector
let values = FormDataJson.toJson($("#form-id")) // with jQueryRead form input values as a flat object (similar to native FormData())
let values = FormDataJson.toJson(document.querySelector("form"), {flatList: true})Read form input values including disabled
let values = FormDataJson.toJson(document.querySelector("form"), {includeDisabled: true})Read with file inputs as base64 data uri
FormDataJson.toJson(document.querySelector("form"), {
filesCallback: function (values){
console.log(values)
}
})Read form input values but filter out, for example, all password fields
let values = FormDataJson.toJson(document.querySelector("form"), {
inputFilter: function (inputElement) {
return (inputElement.type || 'text') !== 'password'
}
})Write data
FormDataJson.fromJson(document.querySelector("form"), {'name': 'BrainFooLong'})Set form input values and clear all other existing input values
FormDataJson.fromJson(document.querySelector("form"), {'name': 'BrainFooLong'}, { clearOthers: true })Reset all input fields to their default values
FormDataJson.reset(document.querySelector("form"))Clear all input fields to empty values
FormDataJson.clear(document.querySelector("form"))All default options for toJson()
You can edit this defaults globally by modifying FormDataJson.defaultOptionsToJson.
{
/**
* Include all disabled field values
* @type {boolean}
*/
'includeDisabled': false,
/**
* Include all button field values
* @type {boolean}
*/
'includeButtonValues': false,
/**
* Include all unchecked radio/checkboxes as given value when they are unchecked
* If undefined, than the unchecked field will be ignored in output
* @type {*}
*/
'uncheckedValue': undefined,
/**
* A function, where first parameter is the input field to check for
* Must return true if the field should be included
* All other return values, as well as no return value, will skip the input field in the progress
* @type {function|null}
*/
'inputFilter': null,
/**
* Does return an array list, with same values as native Array.from(new FormData(form))
* A list will look like [["inputName", "inputValue"], ["inputName", "inputValue"]]
* The input name will not be changed and the list can contain multiple equal names
* @type {boolean}
*/
'flatList': false,
/**
* If true, then this does skip empty fields from the output
* Empty is considered to be:
* An empty array (for multiple selects/checkboxes)
* An empty input field (length = 0)
* This does recursively remove keys
* Example: {"agb":"1", "user" : [{"name" : ""},{"name" : ""}]} will be {"agb":"1"}
* @type {boolean}
*/
'skipEmpty': false,
/**
* A function that will be called when all file fields are read as base64 data uri
* First passed parameter to this function are the form values including all file data
* Note: If set, the original return value from toJson() returns null
* @type {function|null}
*/
'filesCallback': null,
/**
* By default, files are read as base64 data url
* Possible values are: readAsDataURL, readAsBinaryString, readAsText, readAsArrayBuffer
* @type {string}
*/
'fileReaderFunction': 'readAsDataURL',
/**
* If true than values try to be a real Array instead of Object where possible
* If false than all values that are multiple (multiple select, same input names checkboxes, unnamed array indexes, etc...) will be objects
* @type {boolean}
*/
'arrayify': true
}All default options for fromJson()
You can edit this defaults globally by modifying FormDataJson.defaultOptionsFromJson.
{
/**
* Does expect the given values are in a flatList, previously exported with toJson
* Instead of the default bevhiour with nested objects
* @type {boolean}
*/
'flatList': false,
/**
* If true, than all fields that are not exist in the passed values object, will be cleared/emptied
* Not exist means, the value must be undefined
* @type {boolean}
*/
'clearOthers': false,
/**
* If true, than all fields that are not exist in the passed values object, will be reset
* Not exist means, the value must be undefined
* @type {boolean}
*/
'resetOthers': false,
/**
* If true, when a fields value has changed, a "change" event will be fired
* @type {boolean}
*/
'triggerChangeEvent': false
}How to contribute
- Please write an issue before you start programming.
- Always test the official supported browsers.
- Write all tests in
docs/tests/test.html. Each new option must have an own test.