Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rory660/deepforms
Send deep nested JSON-encoded objects from HTML forms
https://github.com/rory660/deepforms
forms html javascript json nested-objects node-js
Last synced: about 1 month ago
JSON representation
Send deep nested JSON-encoded objects from HTML forms
- Host: GitHub
- URL: https://github.com/rory660/deepforms
- Owner: rory660
- License: mit
- Created: 2020-04-14T15:06:44.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2022-12-30T20:16:05.000Z (almost 2 years ago)
- Last Synced: 2024-09-17T00:38:17.615Z (2 months ago)
- Topics: forms, html, javascript, json, nested-objects, node-js
- Language: JavaScript
- Homepage:
- Size: 251 KB
- Stars: 13
- Watchers: 1
- Forks: 0
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](#)
[](#) [](#) [](https://app.circleci.com/pipelines/github/rory660/deepforms)
Send deep nested JSON-encoded objects from HTML forms, in a single function call. [Check it out on npm!](https://www.npmjs.com/package/deepforms)
# Installation
_In the browser:_
Include the script from a node CDN such as _jsdelivr_:
```html
```
---
_As an Express middleware:_
run `npm install deepforms` in your package and place `require("deepforms")` in your node script.
# Features
- Allows forms to be sent as JSON strings representing deep objects
- Aggregates data from form fields that share a name attribute into a list
- Can be imported as an express middleware in node.js to parse the sent JSON
- Submits form data with the same method, action, target, etc as the original form, with no extra code required
# API
_When imported as a frontend JS library:_
### `submitDeepForm(formId)`
Arguments : The id of the form element to be submitted.
Submits the form as a deep nested JSON string containing the form data.
---
_When imported as a Node.js module:_
### `parser(req, res, next)`
Arguments: request object, response object, next function in middleware chain
Express middleware that parses the deep form JSON string from `req.body.deepFormJSON`, if it exists, and places the parsed object in `req.deepFormData`.
# Usage
## Sending Forms
A form can be sent as a deep form by invoking `window.deepforms.submitDeepForm()`. Deep form data will be submitted as a single key `"deepFormJSON"` mapped to a JSON string containing the deep object.
### Field names
Form field names can be written using '.' syntax to represent layers of nesting in an object. For example:
```html
```
will be entered into the form object as:
```js
deepFormObject["user"]["name"] = "testUser";
```
### Multiple fields sharing the same name
If multiple fields in the form share a name, then their values will be parsed as a list:
```html
```
will be entered into the form object as:
```js
deepFormObject["color"] = ["blue", "red"];
```
### `submitDeepForm()`
In order to submit a form as a deep form, invoke `submitDeepForm` as follows:
```html
```
Clicking the button will cause the form to be parsed as an object:
```json
{
"user" : {
"name" : "testUser"
},
"color" : ["blue", "red"]
}
```
and sent as a JSON string to the "/submitForm" route. Deep form data is always sent as a key/value pair with the key `"deepFormJSON"` and the JSON string as the value. The example above would be sent as:
```
deepFormJSON : '{"user":{"name":"testUser"},"color":["blue","red"]}}'
```
---
## WARNING!
When you call `submitDeepForm` from an element's onclick event, make sure that the element is either:
- __Not__ contained within the form.
- Has its `type` field set to something other than `"submit"`.
Button elements inside forms will default to `type="submit"`, causing them to submit the form normally, rather than through the library function.
---
## Parsing Forms
Form data is always sent as the following key/value pair:
```
deepFormJSON =
```
### Express Middleware
Importing deepforms as a Node.js module exposes the `parser` middleware, which can be used in Express servers:
```js
const express = require("express")
const deepforms = require("deepforms")
const app = express()
app.use(deepforms.parser)
```
When the deep form parser is set as an Express middleware, any deep form sent to the server will be automatically parsed as an object and placed in `req.deepFormData`.
With the earlier example of `user.name = "testUser"` and `color = ["blue", "red"]`, the parser would cause `req` to contain the following:
```js
req.deepFormData == {
"user" : {
"name" : "testUser"
},
"color" : ["blue", "red"]
};
```
### Parsing the JSON directly
The JSON string can be found in the `deepFormJSON` field of the request body (or URL parameter if a GET request is sent). It can be simply parsed through `JSON.parse`:
```js
const deepFormData = JSON.parse(req.body.deepFormJSON)
```
## Author
[deepforms is created and maintained by Rory Brown](https://www.rorybrown.info)