magicform

HTML form serialization and AJAX submitting library.

This library can serialize a form into JSON object, or deserialize a JSON object to fields of a form.

It also supports AJAX submitting of a form (need Promise support or es6-promise polyfill) and can enable cookies in PhoneGap/Cordova applications.

No jQuery dependency.

Usages

$3

Deserialize a JSON object into a form.

Example:
``html










`
Execute:
`js
MagicForm.parse(document.getElementById("testMultipleFieldsForm"), { id: 1, key: 2, flag: 3, reason: "hello" });
`
Result:
`html

`

More field name conventions can be found in `tests` folder.

$3

Serialize a form into a JSON object.

`html










`
Execute:
`js
MagicForm.serialize(document.getElementById("testMultipleFieldsForm"));
`
Result:
`js
{ id: "1", key: "2", flag: "3", reason: "hello" }
`

$3

Serialize a form into a JSON object, but without nested structure.

$3

Serialize a form into a query string.

$3

AJAX submit a form immediately.

The object `hooks` may contains below functions:

##### beforeSerialize(formElem: HTMLFormElement) -> Boolean
This function will be called before form data is serialized.

Return a value any other than `true` will prevent the form from submitting.

##### beforeSubmit(data: any | FormData) -> Promise | Boolean
This function will be called before submitting the form. You can modify data before submitting.

Return a value any other than `true` or `Promise.resolve(true)` will prevent the form from submitting.

##### success(response: String, xhr: XMLHttpRequest)
This function will be called after the server responds with a 200. `response` is the response text, `xhr` is the request object.

##### failed(err: Error)
This function will be called when any error occured before submit, or the server responds with any code other than 200. `err` may be undefined.

The object `opts` may contains below options:

##### serializeAsJsonToParameter: String | Boolean
If this is set to `false`, `null` or `undefined`, it will be ignored; otherwise, it will submit a form like this (`serializeAsJsonToParameter: "__json__"`):

`
__json__=%7B%22id%22%3A%223%22%2C%22key%22%3A%226%22%2C%22flag%22%3A9%2C%22reason%22%3A%22world%22%7D
`

##### url: String
If the form doesn't contain an `action` property, then this will be used as target URL.

$3

Make a form do AJAX submit when submit button is clicked.

The object `hooks` and `opts` is the same as `hooks` and `opts` in `window.MagicForm.ajaxSubmit`.

$3

Set global configurations of serializing.

where `configs` can have:

`ignoreInvisibleFields`: Do not parse or serialize a field when it's invisble (determined by getComputedStyle), default `false`

`ignoreHiddenFields`: Do not parse or serialize a field which has `type="hidden"`, default `false`

`uncheckedAsFalse`: Serialize a unchecked checkbox field as `false`, or will ignore it, default `true`

`denyCORSCredentials`: Set `XMLHttpRequest.withCredentials = false`

`alternativeCookieHeaders`: See "Alternative Cookie Headers" section below.

Alternative Cookie Headers (Needs server-side modification)

This option is to support local file based WebView applications like PhoneGap/Cordova applications which use cookies to do authentications etc.

Due to limitations of mobile WebViews, for example, on iOS, you can get the `Set-Cookie` header from `XMLHttpRequest` object, but the cookies are not persisted by WebView, nor be sent with requests;
On the other hand, on Android, you cannot get the `Set-Cookie` header, but the cookies are persisted and will be sent with requests.
`document.cookies` will be `null` on both platforms.

One solution is to use `window.localStorage`, which needs server to return cookies in some way other than `Set-Cookie`.
You can make your server to return something like `My-Set-Cookie` headers with cookies to make client can read them through `XMLHttpRequest.getResponseHeader`, and store them in something like `localStorage`.
MagicForm can support this, through the `alternativeCookieHeaders` global configuration key.

`alternativeCookieHeaders` contains following options:

`requestHeader`: If your server needs a custom header to enable cookies sent in another header, set this option to the header name.

`requestValue`: If your server needs a custom header to enable cookies sent in another header, set this option to the header value.

`cookie`: Specify the custom header name of standard header `Cookie`

`setCookie`: Specify the custom header name of standard header `Set-Cookie`

`storeTo`: Specify where to store the cookies. Options are `window.document` or `window.localStorage`

If you want to read or modify saved cookies, you can use `JSON.parse(localStorage.getItem("cookies"))` or `localStorage.setItem("cookies", JSON.stringify(obj))``.

Browser compatibility

IE 9+ (< 9 may work, not tested)

Other browsers should be fine.

You will need es6-promise polyfill on non-ES6 browsers in order to use AJAX functions.