{"name":"jQuery.param","type":"method","title":"jQuery.param()","deprecated":null,"removed":null,"desc":"Create a serialized representation of an array or object, suitable for use in a URL query string or Ajax request. ","categories":["miscellaneous/collection-manipulation","forms","ajax/helper-functions","version/1.2","version/1.4"],"entries":[{"return":"String","signatures":[{"added":"1.2","argument":{"type":[{"name":"Array"},{"name":"PlainObject"}],"desc":"An array or object to serialize.","name":"obj"}},{"added":"1.4","argument":[{"type":[{"name":"Array"},{"name":"PlainObject"}],"desc":"An array or object to serialize.","name":"obj"},{"desc":"A Boolean indicating whether to perform a traditional \"shallow\" serialization.","name":"traditional","type":"Boolean"}]}],"examples":[{"desc":"Serialize a key/value object.","code":"\nvar params = { width:1680, height:1050 };\nvar str = jQuery.param( params );\n$( \"#results\" ).text( str );\n","css":"\n div {\n color: red;\n }\n","html":"\n
\n"},{"desc":"Serialize a few complex objects","code":"\n// <=1.3.2:\n$.param({ a: [ 2, 3, 4 ] }); // \"a=2&a=3&a=4\"\n// >=1.4:\n$.param({ a: [ 2, 3, 4 ] }); // \"a[]=2&a[]=3&a[]=4\"\n\n// <=1.3.2:\n$.param({ a: { b: 1, c: 2 }, d: [ 3, 4, { e: 5 } ] });\n// \"a=[object+Object]&d=3&d=4&d=[object+Object]\"\n\n// >=1.4:\n$.param({ a: { b: 1, c: 2 }, d: [ 3, 4, { e: 5 } ] });\n// \"a[b]=1&a[c]=2&d[]=3&d[]=4&d[2][e]=5\"\n","css":"\n div {\n color: red;\n }\n"}],"longdesc":"\n

This function is used internally to convert form element values into a serialized string representation (See .serialize() for more information).

\n

As of jQuery 1.3, the return value of a function is used instead of the function as a String.

\n

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;.

\n

As of jQuery 1.8, the $.param() method no longer uses jQuery.ajaxSettings.traditional as its default setting and will default to false. For best compatibility across versions, call $.param() with an explicit value for the second argument and do not use defaults.

\n

If the object passed is in an Array, it must be an array of objects in the format returned by .serializeArray()

\n 
\n[\n  { name: \"first\", value: \"Rick\" },\n  { name: \"last\", value: \"Astley\" },\n  { name: \"job\", value: \"Rock Star\" }\n]\n
\n
\n

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.

\n
\n
\n

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. Use JSON format as an alternative for encoding complex data instead.

\n
\n

In jQuery 1.4, HTML5 input elements are also serialized.

\n

We can display a query string representation of an object and a URI-decoded version of the same as follows:

\n 
\nvar myObject = {\n  a: {\n    one: 1,\n    two: 2,\n    three: 3\n  },\n  b: [ 1, 2, 3 ]\n};\nvar recursiveEncoded = $.param( myObject );\nvar recursiveDecoded = decodeURIComponent( $.param( myObject ) );\n\nalert( recursiveEncoded );\nalert( recursiveDecoded );\n
\n

The values of recursiveEncoded and recursiveDecoded are alerted as follows:

\n

\n a%5Bone%5D=1&a%5Btwo%5D=2&a%5Bthree%5D=3&b%5B%5D=1&b%5B%5D=2&b%5B%5D=3\n
\n a[one]=1&a[two]=2&a[three]=3&b[]=1&b[]=2&b[]=3\n

\n

To emulate the behavior of $.param() prior to jQuery 1.4, we can set the traditional argument to true:

\n 
\nvar myObject = {\n  a: {\n    one: 1,\n    two: 2,\n    three: 3\n  },\n  b: [ 1, 2, 3 ]\n};\nvar shallowEncoded = $.param( myObject, true );\nvar shallowDecoded = decodeURIComponent( shallowEncoded );\n\nalert( shallowEncoded );\nalert( shallowDecoded );\n
\n

The values of shallowEncoded and shallowDecoded are alerted as follows:

\n

\n a=%5Bobject+Object%5D&b=1&b=2&b=3\n
\n a=[object+Object]&b=1&b=2&b=3\n

\n "}]}