Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/insin/get-form-data

Gets form and field data via form.elements
https://github.com/insin/get-form-data

forms javascript

Last synced: 3 days ago
JSON representation

Gets form and field data via form.elements

Awesome Lists containing this project

README 

        
# get-form-data



[![Travis][build-badge]][build]

[![npm package][npm-badge]][npm]

[![Coveralls][coveralls-badge]][coveralls]



Gets form data - or data for a named form field - via `form.elements`.



Data is retrieved in a format similar to request parameters which would be sent if the form was submitted, so this module is suitable for extracting form data on the client side for projects which implement isomorphic handling of form submission.



## Install



```

npm install get-form-data

```



Browser bundles area available, which export a global `getFormData` function.



* [get-form-data.js](https://unpkg.com/get-form-data/umd/get-form-data.js) (development version)

* [get-form-data.min.js](https://unpkg.com/get-form-data/umd/get-form-data.min.js) (compressed production version)



## Usage



### Getting form data



To get data for an entire form, use the `getFormData()` function:



```html



  ...

  Product:

  

    T-shirt

    Hat

    Shoes

  



  Quantity:

  



  Express shipping

  
Do you want to use Express Shipping?


  


     Yes

     No

  



  Terms of Service:

  
I have read and agree to the Terms of Service.


   Yes

  ...



```

```javascript

let form = document.querySelector('#productForm')



let data = getFormData(form)



console.log(JSON.stringify(data))

```

```json

{"product": "1", "quantity": "9", "shipping": "express", "tos": true}

```



### Getting field data



To get data for individual form fields (which may contain multiple form inputs with the same name), use the `getFieldData()` function, which is exposed as a property of `getFormData`:



```html



  ...

  Sizes:

  


     S

     M

     L

  


  ...



```

```javascript

let form = document.querySelector('#tshirtForm')



let sizes = getFormData.getFieldData(form, 'sizes')



console.log(JSON.stringify(sizes))

```

```

["M", "L"]

```



### Trimming user input



To trim user input, pass a `trim: true` option to `getFormData()` or `getFieldData()`:



```html



  ...

  Username:

  



  Password:

  

  ...



```

```javascript

let form = document.querySelector('#signupForm')



let data = getFormData(form, {trim: true})



console.log(JSON.stringify(data))

```

```

{"username": "AzureDiamond", "password": "hunter2"}

```



### Including disabled inputs



Disabled inputs are ignored by default; to include their data, pass an `includeDisabled: true` option to `getFormData()` or `getFieldData()`.



```javascript

let data = getFormData(form, {includeDisabled: true})

```



### File Inputs



Where possible, data extracted from `` will be native

[`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) objects.



If the `.files` property is not available, the `.value` property will be used to provide data instead.



## API



### `getFormData(form: HTMLFormElement[, options: Object])`



Extracts data from a ``'s `.elements` collection - in order to use `.elements`, form inputs must have `name` or `id` attributes. Since multiple inputs can't have the same `id` and a `name` allows an input to qualify as a successful control for form submission, `name` attributes are preferred and will be given priority if both are present.



The following options can be configured:



* `trim: Boolean` (default: `false`) - if `true`, leading and trailing whitespace will be trimmed from user input in text entry form inputs.

* `includeDisabled: Boolean` (default: `false`) - if `true`, disabled inputs will not be ignored.



#### Return type: `Object`



Properties in the returned data object are mostly consistent with what would have been sent as request parameters if the form had been submitted:



* Disabled inputs are ignored by default.

* Text inputs will always contribute a value, which will be `''` if they are empty.

* Checkbox inputs will only contribute a value if they are checked, in which case their `value` attribute will be used.

* Form elements which represent multiple values (select-multiple, or multiple inputs with the same name, file inputs with `multiple`) will only contribute a value if they have at least one value to submit. Their values will always be held in an `Array`, even if there is only one.



Exceptions to this are:



* If a checked checkbox doesn't have a `value` attribute, its value will be `true`. Normally it would default to `'on'` when submitted, but this isn't as useful a default on the client.

* Buttons are completely ignored, as it's only possible to determine which button counts as successful after it's been used to submit the form.



### `getFieldData(form: HTMLFormElement, fieldName: String[, options: Object])`



> `getFieldData()` is a named export when using ES modules, otherwise it's also available as `getFormData.getFieldData()`



Extracts data for a named field from a  ``'s `.elements` collection.



Options are as documented for `getFormData`.



#### Return type: `null | boolean | string | string[] | File | File[]`



This function is used by `getFormData()`, so the documentation for individual return values above also applies.



`null` will be returned if the field is non-existent, disabled, or shouldn't contribute a value (e.g. unchecked checkboxes, multiple selects with no selections, file inputs with no selections).



## MIT Licensed



[build-badge]: https://img.shields.io/travis/insin/get-form-data/master.svg?style=flat-square

[build]: https://travis-ci.org/insin/get-form-data



[npm-badge]: https://img.shields.io/npm/v/get-form-data.svg?style=flat-square

[npm]: https://www.npmjs.org/package/get-form-data



[coveralls-badge]: https://img.shields.io/coveralls/insin/get-form-data/master.svg?style=flat-square

[coveralls]: https://coveralls.io/github/insin/get-form-data