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

window.MagicForm.parse(formElem: HTMLFormElement, data: any)

Deserialize a JSON object into a form.

Example:

<form id="testMultipleFieldsForm">
    <input type="hidden" class="f-id" name="id">
    <input type="text" class="f-key" name="key">
    <input type="number" class="f-flag" name="flag">
    <input type="text" class="f-reason" name="reason">
</form>

Execute:

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

Result:

<form id="testMultipleFieldsForm">
    <input type="hidden" class="f-id" name="id" value="1">
    <input type="text" class="f-key" name="key" value="2">
    <input type="number" class="f-flag" name="flag" value="3">
    <input type="text" class="f-reason" name="reason" value="hello">
</form>

More field name conventions can be found in tests folder.

window.MagicForm.serialize(formElem: HTMLFormElement) -> any

Serialize a form into a JSON object.

<form id="testMultipleFieldsForm">
    <input type="hidden" class="f-id" name="id" value="1">
    <input type="text" class="f-key" name="key" value="2">
    <input type="number" class="f-flag" name="flag" value="3">
    <input type="text" class="f-reason" name="reason" value="hello">
</form>

Execute:

MagicForm.serialize(document.getElementById("testMultipleFieldsForm"));

Result:

{ id: "1", key: "2", flag: "3", reason: "hello" }

window.MagicForm.serializeSimple(formElem: HTMLFormElement) -> any

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

window.MagicForm.serializePlain(formElem: HTMLFormElement) -> String

Serialize a form into a query string.

window.MagicForm.ajaxSubmit(formElem: HTMLFormElement, hooks: any, opts: any) -> Promise

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.

window.MagicForm.ajaxify(formElem: HTMLFormElement, hooks: any, opts: any)

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.

window.MagicForm.setConfigs(configs: any)

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.