-
-
Notifications
You must be signed in to change notification settings - Fork 10
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #19 from brainfoolong/v2-dev
V2 dev
- Loading branch information
Showing
20 changed files
with
4,586 additions
and
782 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,132 +1,198 @@ | ||
|  | ||
|
|
||
| # Form Data Json - Form input values to/from JSON | ||
| A zero dependency, cross browser library to easily get or set form input values as/from a json object. It can handle all existing input types, including multidimensional array names and file input. It is similar to native [FormData](https://developer.mozilla.org/docs/Web/API/FormData) but have some advantages: Get data as multidimensional object, writing data into forms (not just reading), reading unchecked/disabled fields as well, reading file inputs, and some other helpful features. | ||
|  | ||
|
|
||
| # 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](https://developer.mozilla.org/docs/Web/API/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) | ||
|
|
||
| ## Breaking Changes from v1 to v2 | ||
| Please [read migration guide bellow](#migration-from-v1-to-v2). v2 is a refactoring of v1 with a lot of changes/improvements. Function names have changes. Returned json data has changed. There is a migration script, when you can't change your existing code on upgrade. | ||
|
|
||
| ## Installation | ||
| Download [latest release](https://github.com/brainfoolong/form-data-json/releases/latest) and include `dist/form-data-json.min.js` into your project. | ||
| ```html | ||
| <script src="dist/form-data-json.min.js"></script> | ||
| ``` | ||
| ###### For a quick test without downloading | ||
| ###### CDN (Latest version automatically, do not use it in production because of possible breaking changes) | ||
| ```html | ||
| <script src="https://brainfoolong.github.io/form-data-json/lib/form-data-json.min.js"></script> | ||
| <script src="https://cdn.jsdelivr.net/npm/form-data-json-convert/dist/form-data-json.min.js"></script> | ||
| ``` | ||
| ###### NPM | ||
| ``` | ||
| ```cmd | ||
| npm install form-data-json-convert | ||
| // import: const {FormDataJson, FormDataJsonOptions} = require('form-data-json-convert') | ||
| // import in NodeJS: const FormDataJson = require('form-data-json-convert') | ||
| ``` | ||
|
|
||
| ## Features | ||
| * No dependency - Vanilla javascript | ||
| * Cross Browser including IE11 | ||
| * Multidimensional input name support. For example: `name="entry[123][person]"` | ||
| * Super small: ~3kB gzipped | ||
|
|
||
| ## Playground | ||
| [Test it out here.](https://brainfoolong.github.io/form-data-json/example/playground.html) | ||
|
|
||
| ## Supported Browser | ||
| * Chrome | ||
| * Firefox | ||
| * Edge (Chromium based and Old) | ||
| * Safari | ||
| * IE11 | ||
| * And probably every other that we don't test | ||
|
|
||
| ## 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 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. | ||
|
|
||
| ## How to use | ||
| ###### Read form input values | ||
| ### Read data | ||
| ```javascript | ||
| let values = FormDataJson.formToJson(document.querySelector("form")) | ||
| 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 jQuery | ||
| ``` | ||
| ###### Read form input values as a flat object (similar to native FormData() keys) | ||
| ###### Read form input values as a flat object (similar to native FormData()) | ||
| ```javascript | ||
| let values = FormDataJson.formToJson(document.querySelector("form")) | ||
| values = FormDataJson.flattenJsonFormValues(values) | ||
| let values = FormDataJson.toJson(document.querySelector("form"), {flatList: true}) | ||
| ``` | ||
| ###### Read form input values including all inputs, even disabled inputs or unchecked checkboxes | ||
| ###### Read form input values including disabled | ||
| ```javascript | ||
| let values = FormDataJson.formToJson(document.querySelector("form"), new FormDataJsonOptions({ includeDisabled: true, includeUncheckedAsNull : true })) | ||
| let values = FormDataJson.toJson(document.querySelector("form"), {includeDisabled: true}) | ||
| ``` | ||
| ###### Read with file inputs as base64 data uri | ||
| ```javascript | ||
| FormDataJson.formToJson(document.querySelector("form"), null, function(values){}) | ||
| FormDataJson.toJson(document.querySelector("form"), { | ||
| filesCallback: function (values){ | ||
| console.log(values) | ||
| } | ||
| }) | ||
| ``` | ||
| ###### Read form input values but filter out, for example, all password fields | ||
| ```javascript | ||
| let values = FormDataJson.formToJson(document.querySelector("form"), new FormDataJsonOptions({ inputFilter: function(inputElement) { return (inputElement.type || 'text') !== 'password' } })) | ||
| let values = FormDataJson.toJson(document.querySelector("form"), { | ||
| inputFilter: function (inputElement) { | ||
| return (inputElement.type || 'text') !== 'password' | ||
| } | ||
| }) | ||
| ``` | ||
|
|
||
| ###### Read a single input field | ||
| ### Write data | ||
| ```javascript | ||
| let values = FormDataJson.getInputValue(document.querySelector("input")) | ||
| FormDataJson.fromJson(document.querySelector("form"), {'name': 'BrainFooLong'}) | ||
| ``` | ||
|
|
||
| ###### Set form input values | ||
| ###### Set form input values and clear all other existing input values | ||
| ```javascript | ||
| FormDataJson.fillFormFromJsonValues(document.querySelector("form"), {'name': 'BrainFooLong'}) | ||
| FormDataJson.fromJson(document.querySelector("form"), {'name': 'BrainFooLong'}, { clearOthers: true }) | ||
| ``` | ||
|
|
||
| ###### Set form input values and unset all other existing input values | ||
| ###### Reset all input fields to their default values | ||
| ```javascript | ||
| FormDataJson.fillFormFromJsonValues(document.querySelector("form"), {'name': 'BrainFooLong'}, new FormDataJsonOptions({ unsetAllInputsOnFill: true })) | ||
| FormDataJson.reset(document.querySelector("form")) | ||
| ``` | ||
|
|
||
| ###### Set form input values but ignore, for example, password fields | ||
| ###### Clear all input fields to empty values | ||
| ```javascript | ||
| FormDataJson.fillFormFromJsonValues(document.querySelector("form"), {'name': 'BrainFooLong'}, new FormDataJsonOptions({ inputFilter: function(inputElement) { return (inputElement.type || 'text') !== 'password' } }) | ||
| FormDataJson.clear(document.querySelector("form")) | ||
| ``` | ||
|
|
||
| ###### Set a single input field | ||
| ```javascript | ||
| let values = FormDataJson.setInputValue(document.querySelector("input"), 'foo') | ||
| ###### All default options for toJson() | ||
| You can edit this defaults globally by modifying `FormDataJson.defaultOptionsToJson`. | ||
| ```javascript 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, than 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' | ||
| } | ||
| ``` | ||
|
|
||
| ###### All options and their defaults | ||
| You can edit this defaults to your needs. You can pass this options directly to the `new FormDataOptions({...})` instantiation. | ||
| ```javascript | ||
| FormDataJsonOptions.defaults = { | ||
| /** | ||
| * Include all disabled inputs in result data | ||
| * @type {boolean} | ||
| */ | ||
| includeDisabled, | ||
|
|
||
| /** | ||
| * Include checkboxes that are unchecked with a null, otherwise the key will not exist in result data | ||
| * @type {boolean} | ||
| */ | ||
| includeUncheckedAsNull, | ||
|
|
||
| /** | ||
| * Include all input buttons/submits values, otherwise the key they will not exist in result data | ||
| * @type {boolean} | ||
| */ | ||
| includeButtonValues, | ||
|
|
||
| /** | ||
| * Will unset all existing input fields in form when using fillFormFromJsonValues | ||
| * This will be helpful if you have checkboxes and want to fill from json object, but checkboxes still stay checked | ||
| * because the key not exist in the json data | ||
| * @type {boolean} | ||
| */ | ||
| unsetAllInputsOnFill, | ||
|
|
||
| /** | ||
| * If set to a function, this will receive the current input element in progress of formToJson|fillFormFromJsonValues|unsetFormInputs | ||
| * It must return bool true to allow the script to progress the input element | ||
| * If other than true is returned, than the input will be skipped | ||
| * @type {FormDataJsonOptions~inputFilterCallback|null} | ||
| */ | ||
| inputFilter | ||
| ###### All default options for fromJson() | ||
| You can edit this defaults globally by modifying `FormDataJson.defaultOptionsFromJson`. | ||
| ```javascript 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. | ||
|
|
||
| ### Migration from v1 to v2 | ||
|
|
||
| There is a migration script to drop in, to make most existing code compatible with new stuff. You should migrate existing code as soon as possible, but if you don't have time right now, you can use the migration script. Simply include `src/migration-v1-v2.js` after `dist/form-data-json.min.js`. | ||
|
|
||
| Warning: Returned data may still differ to v1, so use it with caution and test before you go into production. Most noticable change is that some objects are now real arrays, when possible. | ||
|
|
||
| Goto [changelog](https://github.com/brainfoolong/form-data-json/blob/master/CHANGELOG.md#200beta---26092021) for more details of what exactly as new and old. |
Oops, something went wrong.