jQuery.param()

jQuery

previous page next page

jQuery.param()

Categories: Miscellaneous > Collection Manipulation | Forms | Ajax > Helper Functions

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 )

  • version added: 1.4jQuery.param( obj, traditional )

    • obj
      Type: Array or PlainObject
      An array or object to serialize.
    • traditional
      Type: Boolean
      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()

1
2
3
[{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:

1
2
3
4
5
6
7
8
9
10
11
12
13
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:

1
2
3
4
5
6
7
8
9
10
11
12
13
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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
                                  

                                    

                                      
                                        <!DOCTYPE html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <head>
                                      
                                    

                                  

                                  

                                    

                                        <style>div { color:red; }</style>
                                    

                                  

                                  

                                    

                                        <script src="http://code.jquery.com/jquery-latest.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>

Example: Serialize a few complex objects

1
2
3
4
5
6
7
8
9
10
 
                                  

                                    

                                      
                                        // <=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"
 POWERED BYHERONOTE
previous page start next page