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.
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.
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" }
Serialize a form into a JSON object, but without nested structure.
Serialize a form into a query string.
AJAX submit a form immediately.
The object hooks
may contains below functions:
This function will be called before form data is serialized.
Return a value any other than true
will prevent the form from submitting.
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.
This function will be called after the server responds with a 200. response
is the response text, xhr
is the request object.
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:
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
If the form doesn't contain an action
property, then this will be used as target URL.
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
.
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.
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))
.
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.