jQuery.param()
jQuery.param( obj ) Returns: String
Description: Create a serialized representation of an array or object, suitable for use in a URL query string or Ajax request.
-
version added: 1.2jQuery.param( obj )
objAn array or object to serialize.
-
version added: 1.4jQuery.param( obj, traditional )
objAn array or object to serialize.
traditionalA Boolean indicating whether to perform a traditional "shallow" serialization.
This function is used internally to convert form element values into a serialized string representation (See .serialize() for more information).
As of jQuery 1.3, the return value of a function is used instead of the function as a String.
As of jQuery 1.4, the $.param() method serializes deep objects recursively to accommodate modern scripting languages and frameworks such as PHP and Ruby on Rails. You can disable this functionality globally by setting jQuery.ajaxSettings.traditional = true;.
If the object passed is in an Array, it must be an array of objects in the format returned by .serializeArray()
[{name:"first",value:"Rick"},
{name:"last",value:"Astley"},
{name:"job",value:"Rock Star"}]
Note: Because some frameworks have limited ability to parse serialized arrays, we should exercise caution when passing an obj argument that contains objects or arrays nested within another array.
In jQuery 1.4 HTML5 input elements are serialized, as well.
We can display a query string representation of an object and a URI-decoded version of the same as follows:
var myObject = {
a: {
one: 1,
two: 2,
three: 3
},
b: [1,2,3]
};
var recursiveEncoded = $.param(myObject);
var recursiveDecoded = decodeURIComponent($.param(myObject));
alert(recursiveEncoded);
alert(recursiveDecoded);
The values of recursiveEncoded and recursiveDecoded are alerted as follows:
a%5Bone%5D=1&a%5Btwo%5D=2&a%5Bthree%5D=3&b%5B%5D=1&b%5B%5D=2&b%5B%5D=3
a[one]=1&a[two]=2&a[three]=3&b[]=1&b[]=2&b[]=3
To emulate the behavior of $.param() prior to jQuery 1.4, we can set the traditional argument to true:
var myObject = {
a: {
one: 1,
two: 2,
three: 3
},
b: [1,2,3]
};
var shallowEncoded = $.param(myObject, true);
var shallowDecoded = decodeURIComponent(shallowEncoded);
alert(shallowEncoded);
alert(shallowDecoded);
The values of shallowEncoded and shallowDecoded are alerted as follows:
a=%5Bobject+Object%5D&b=1&b=2&b=3
a=[object+Object]&b=1&b=2&b=3
Examples:
Example: Serialize a key/value object.
<!DOCTYPE html>
<html>
<head>
<style>div { color:red; }</style>
<script src="http://code.jquery.com/jquery-1.4.4.js"></script>
</head>
<body>
<div id="results"></div>
<script>
var params = { width:1680, height:1050 };
var str = jQuery.param(params);
$("#results").text(str);
</script>
</body>
</html>Demo:
Example: Serialize a few complex objects
// <=1.3.2:
$.param({ a: [2,3,4] }) // "a=2&a=3&a=4"
// >=1.4:
$.param({ a: [2,3,4] }) // "a[]=2&a[]=3&a[]=4"
// <=1.3.2:
$.param({ a: { b:1,c:2 }, d: [3,4,{ e:5 }] }) // "a=[object+Object]&d=3&d=4&d=[object+Object]"
// >=1.4:
$.param({ a: { b:1,c:2 }, d: [3,4,{ e:5 }] }) // "a[b]=1&a[c]=2&d[]=3&d[]=4&d[2][e]=5"
Support requests, bug reports, and off-topic comments will be deleted without warning.