control-freak-ide/Control-Freak-Documentation/jQuery/docs/entries/jQuery.param.json

{"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<div id=\"results\"></div>\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    <p>This function is used internally to convert form element values into a serialized string representation (See <a href=\"/serialize/\">.serialize()</a> for more information).</p>\n    <p>As of jQuery 1.3, the return value of a function is used instead of the function as a String.</p>\n    <p>As of jQuery 1.4, the <code>$.param()</code> 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 <code>jQuery.ajaxSettings.traditional = true;</code>.</p>\n    <p>As of jQuery 1.8, the <code>$.param()</code> method no longer uses <code>jQuery.ajaxSettings.traditional</code> as its default setting and will default to <code>false</code>. For best compatibility across versions, call <code>$.param()</code> with an explicit value for the second argument and do not use defaults.</p>\n    <p>If the object passed is in an Array, it must be an array of objects in the format returned by <a href=\"/serializeArray/\">.serializeArray()</a></p>\n    <pre><code>\n[\n  { name: \"first\", value: \"Rick\" },\n  { name: \"last\", value: \"Astley\" },\n  { name: \"job\", value: \"Rock Star\" }\n]\n    </code></pre>\n    <div class=\"warning\">\n      <p><strong>Note:</strong> Because some frameworks have limited ability to parse serialized arrays, developers should exercise caution when passing an <code>obj</code> argument that contains objects or arrays nested within another array.</p>\n    </div>\n    <div class=\"warning\">\n      <p><strong>Note:</strong> 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.</p>\n    </div>\n    <p>In jQuery 1.4, HTML5 input elements are also serialized.</p>\n    <p>We can display a query string representation of an object and a URI-decoded version of the same as follows:</p>\n    <pre><code>\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    </code></pre>\n    <p>The values of <code>recursiveEncoded</code> and <code>recursiveDecoded</code> are alerted as follows:</p>\n    <p>\n      <samp>a%5Bone%5D=1&amp;a%5Btwo%5D=2&amp;a%5Bthree%5D=3&amp;b%5B%5D=1&amp;b%5B%5D=2&amp;b%5B%5D=3</samp>\n      <br/>\n      <samp>a[one]=1&amp;a[two]=2&amp;a[three]=3&amp;b[]=1&amp;b[]=2&amp;b[]=3</samp>\n    </p>\n    <p>To emulate the behavior of <code>$.param()</code> prior to jQuery 1.4, we can set the <code>traditional</code> argument to <code>true</code>:</p>\n    <pre><code>\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</code></pre>\n    <p>The values of <code>shallowEncoded</code> and <code>shallowDecoded</code> are alerted as follows:</p>\n    <p>\n      <samp>a=%5Bobject+Object%5D&amp;b=1&amp;b=2&amp;b=3</samp>\n      <br/>\n      <samp>a=[object+Object]&amp;b=1&amp;b=2&amp;b=3</samp>\n    </p>\n  "}]}