Description: Create a serialized representation of an array or object, suitable for use in a URL query string or Ajax request.
Arguments
jQuery.param( obj )
version added: 1.2
An array or object to serialize.
jQuery.param( obj, traditional )
version added: 1.4
An array or object to serialize.
traditional
A 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;.
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 1
Serialize a key/value object.
var params = { width:1680, height:1050 };
var str = jQuery.param(params);
$("#results").text(str);
Example 1 - Full source:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<script src="http://code.jquery.com/jquery-latest.js"></script>
<script type="text/javascript" language="javascript">
$(document).ready(function(){
var params = { width:1680, height:1050 };
var str = jQuery.param(params);
$("#results").text(str);
});
</script>
<style>div { color:red; }</style>
</head>
<body>
<div id="results"></div>
</body>
</html>
Example 2
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"
Was this information helpful?
