jQuery.param()
Categories: Collection Manipulation | Helper Functions | Forms
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.
-
jQuery.param( obj )
version added: 1.0obj An array or object to serialize.
-
jQuery.param( obj, traditional )
version added: 1.0obj 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;
.
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, developers should exercise caution when passing an
obj
argument that contains objects or arrays nested within another array.
Note: Because there is no universally agreed-upon specification for param strings, it is not possible to encode complex data structures using this method in a manner that works ideally across all languages supporting such input. Until such time that there is, the
$.param
method will remain in its current form.
In jQuery 1.4, HTML5 input elements are also serialized.
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
-
Serialize a key/value object.
HTML:
<div id="results"></div>
CSS:
div { color:red; }
Code:
var params = { width:1680, height:1050 }; var str = jQuery.param(params); $("#results").text(str);
-
Serialize a few complex objects
CSS:
div { color:red; }
Code:
// <=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"