form-serializer

jQuery Serialize Object
=======================

As seen on StackOverflow: [Convert forms to JSON LIKE A BOSS][SO].

Adds the method serializeObject to jQuery, to perform complex form
serialization into JavaScript objects.

The current implementation relies in jQuery.serializeArray() to grab the form
attributes and then create the object using the input name attributes.

This means it will serialize the inputs that are supported by
.serializeArray(), that use the standard W3C rules for [successful controls][w3c_controls]
to determine which inputs should be included; in particular:

* The input cannot be disabled and must contain a name attribute.
* No submit button value is serialized since the form is not submitted using a button.
* Data from inputs are not serialized.

Installation
------------

option 1: Bower

``sh
$ bower install jquery-serialize-object
`

option 2: Manual

Copy the dist/jquery-serialize-object.min.js to your project.

You can include the plugin in the HEAD element or at the bottom of your BODY
tag. Wherever you choose to add it, it must be included after your jQuery.

`html




`

2.0
---

Version 2.0 takes jquery-serialize-object into maturity. It is now backed by a
full test suite so you can be confident that it will work in your web app.

Moving ahead, on top of core serialization, .serializeObject will support
correct serializaton for boolean and number values, resulting valid types
for both cases.

Look forward to these >= 2.5.0

Update: >= 2.4.0 now serializes as a boolean. See
the [test][boolean] for specific behavior.


API
---

Given a basic HTML form

`html











`

.serializeObject — serializes the selected form into a JavaScript object

`js
$('form#contact').serializeObject();
//=> {user: {email: "jsmith@example.com", pets: ["cat", "dog"]}}
`

.serializeJSON — serializes the selected form into [JSON][json]

`js
$('form#contact').serializeJSON();
//=> '{"user":{"email":"jsmith@example.com","pets":["cat","dog"]}}'
`

FormSerializer.patterns — modify the patterns used to match field
names

Many of you have requested to allow - in field names or use . to nest keys.
You can now configure these to your heart's content.

[Hyphen][dash-notation] example

`js
$.extend(FormSerializer.patterns, {
validate: /^[a-z][a-z0-9_-](?:\[(?:\d|[a-z0-9_-]+)\])*$/i,
key: /[a-z0-9_-]+|(?=\[\])/gi,
named: /^[a-z0-9_-]+$/i
});
`

[Dot-notation][dot-notation] example

`js
$.extend(FormSerializer.patterns, {
validate: /^[a-z][a-z0-9_](?:\.[a-z0-9_]+)(?:\[\])?$/i
});
`

Validating and Key parsing

* validate — only valid input names will be serialized; invalid names
will be skipped

* key — this pattern parses all "keys" from the input name; You will
want to use /g as a modifier with this regexp.

Key styles

* push — pushe a value to an array

`html


`

`js
$("form").serializeObject();
//=> {foo: [a, b]}
`

* fixed — add a value to an array at a specified index

`html


`

`js
$("form").serializeObject();
//=> {foo: [, , "a", , "b"]}
`

* named — adds a value to the specified key

`html



`

`js
$("form").serializeObject();
//=> {foo: {bar: "a", bof: "b"}, hello: "world"}
`

Tests
-----

If you have [node.js][node] installed, as a convenience, you can run

`sh
$ npm test
`

If you do not have node installed, simply

`sh
$ open ./test/test.html
`


CoffeeScript
------------

CoffeeScript has been dropped for >= 2.0.0. If members of the community would
like to support this, please feel free to add a CoffeeScript version.

If you'd like to use the the 1.0.0 version, it is still available [here][legacy].


Contributing
------------

All pull requests must be backed by tests or they will be rejected.

Once you have finished your changes, build the new plugin:

`sh
$ npm run-script build
``

Do not bump the version. I will handle versioning.

[SO]: http://stackoverflow.com/a/8407771/184600
[w3c_controls]: http://www.w3.org/TR/html401/interact/forms.html#h-17.13.2
[json]: http://json.org
[node]: http://nodejs.org
[legacy]: https://github.com/macek/jquery-serialize-object/releases/tag/1.0.0
[dash-notation]: https://github.com/macek/jquery-serialize-object/issues/6
[dot-notation]: https://github.com/macek/jquery-serialize-object/issues/4
[boolean]: https://github.com/macek/jquery-serialize-object/blob/master/test/integration/encode-test.js