1 line
18 KiB
JSON
1 line
18 KiB
JSON
{"name":"jQuery","type":"method","title":"jQuery()","deprecated":null,"removed":null,"desc":"Return a collection of matched elements either found in the DOM based on passed argument(s) or created by passing an HTML string.","categories":["core","version/1.0","version/1.4"],"entries":[{"return":"jQuery","signatures":[{"added":"1.0","argument":[{"desc":"A string containing a selector expression","name":"selector","type":"Selector"},{"type":[{"name":"Element"},{"name":"jQuery"}],"desc":"A DOM Element, Document, or jQuery to use as context","name":"context","optional":"true"}]},{"added":"1.0","argument":{"desc":"A DOM element to wrap in a jQuery object.","name":"element","type":"Element"}},{"added":"1.0","argument":{"desc":"An array containing a set of DOM elements to wrap in a jQuery object.","name":"elementArray","type":"Array"}},{"added":"1.0","argument":{"desc":"A plain object to wrap in a jQuery object.","name":"object","type":"PlainObject"}},{"added":"1.0","argument":{"desc":"An existing jQuery object to clone.","name":"jQuery object","type":"PlainObject"}},{"added":"1.4"}],"examples":[{"desc":"Find all p elements that are children of a div element and apply a border to them.","code":"\n$( \"div > p\" ).css( \"border\", \"1px solid gray\" );\n","html":"\n<p>one</p>\n<div><p>two</p></div>\n<p>three</p>\n"},{"desc":"Find all inputs of type radio within the first form in the document.","code":"\n$( \"input:radio\", document.forms[ 0 ] );\n"},{"desc":"Find all div elements within an XML document from an Ajax response.","code":"\n$( \"div\", xml.responseXML );\n"},{"desc":"Set the background color of the page to black.","code":"\n$( document.body ).css( \"background\", \"black\" );\n"},{"desc":"Hide all the input elements within a form.","code":"\n$( myForm.elements ).hide();\n"}],"desc":"Accepts a string containing a CSS selector which is then used to match a set of elements.","longdesc":"\n <p>In the first formulation listed above, <code>jQuery()</code> — which can also be written as <code>$()</code> — searches through the DOM for any elements that match the provided selector and creates a new jQuery object that references these elements:</p>\n <pre><code>$( \"div.foo\" );</code></pre>\n <p>If no elements match the provided selector, the new jQuery object is \"empty\"; that is, it contains no elements and has <code><a href=\"/length/\">.length</a></code> property of 0.</p>\n <h4 id=\"selector-context\">Selector Context</h4>\n <p>By default, selectors perform their searches within the DOM starting at the document root. However, an alternate context can be given for the search by using the optional second parameter to the <code>$()</code> function. For example, to do a search within an event handler, the search can be restricted like so:</p>\n <pre><code>\n$( \"div.foo\" ).click(function() {\n $( \"span\", this ).addClass( \"bar\" );\n});\n </code></pre>\n <p>When the search for the span selector is restricted to the context of <code>this</code>, only spans within the clicked element will get the additional class.</p>\n <p>Internally, selector context is implemented with the <code>.find()</code> method, so <code>$( \"span\", this )</code> is equivalent to <code>$( this ).find( \"span\" )</code>.</p>\n\n <h4 id=\"using-dom-elements\">Using DOM elements</h4>\n <p>The second and third formulations of this function create a jQuery object using one or more DOM elements that were already selected in some other way.</p>\n <p><strong>Note:</strong> These formulations are meant to consume only DOM elements; feeding mixed data to the elementArray form is particularly discouraged.</p>\n <p>A common use of this facility is to call jQuery methods on an element that has been passed to a callback function through the keyword <code>this</code>:</p>\n <pre><code>\n$( \"div.foo\" ).click(function() {\n $( this ).slideUp();\n});\n </code></pre>\n <p>This example causes elements to be hidden with a sliding animation when clicked. Because the handler receives the clicked item in the <code>this</code> keyword as a bare DOM element, the element must be passed to the <code>$()</code> function before applying jQuery methods to it.</p>\n <p>XML data returned from an Ajax call can be passed to the <code>$()</code> function so individual elements of the XML structure can be retrieved using <code>.find()</code> and other DOM traversal methods.</p>\n <pre><code>\n$.post( \"url.xml\", function( data ) {\n var $child = $( data ).find( \"child\" );\n});\n </code></pre>\n\n <h4 id=\"cloning-jquery-objects\">Cloning jQuery Objects</h4>\n <p>When a jQuery object is passed to the <code>$()</code> function, a clone of the object is created. This new jQuery object references the same DOM elements as the initial one.</p>\n\n <h4 id=\"returning-empty-set\">Returning an Empty Set</h4>\n <p>As of jQuery 1.4, calling the <code>jQuery()</code> method with <em>no arguments</em> returns an empty jQuery set (with a <code><a href=\"/length/\">.length</a></code> property of 0). In previous versions of jQuery, this would return a set containing the document node.</p>\n <h4 id=\"working-with-plain-objects\">Working With Plain Objects</h4>\n <p>At present, the only operations supported on plain JavaScript objects wrapped in jQuery are: <code>.data()</code>,<code>.prop()</code>,<code>.on()</code>, <code>.off()</code>, <code>.trigger()</code> and <code>.triggerHandler()</code>. The use of <code>.data()</code> (or any method requiring <code>.data()</code>) on a plain object will result in a new property on the object called jQuery{randomNumber} (eg. jQuery123456789).</p>\n <pre><code>\n// Define a plain object\nvar foo = { foo: \"bar\", hello: \"world\" };\n\n// Pass it to the jQuery function\nvar $foo = $( foo );\n\n// Test accessing property values\nvar test1 = $foo.prop( \"foo\" ); // bar\n\n// Test setting property values\n$foo.prop( \"foo\", \"foobar\" );\nvar test2 = $foo.prop( \"foo\" ); // foobar\n\n// Test using .data() as summarized above\n$foo.data( \"keyName\", \"someValue\" );\nconsole.log( $foo ); // will now contain a jQuery{randomNumber} property\n\n// Test binding an event name and triggering\n$foo.on( \"eventName\", function () {\n console.log( \"eventName was called\" );\n});\n\n$foo.trigger( \"eventName\" ); // Logs \"eventName was called\"\n </code></pre>\n <p>Should <code>.trigger( \"eventName\" )</code> be used, it will search for an \"eventName\" property on the object and attempt to execute it after any attached jQuery handlers are executed. It does not check whether the property is a function or not. To avoid this behavior, <code>.triggerHandler( \"eventName\" )</code> should be used instead.</p>\n <pre><code>\n$foo.triggerHandler( \"eventName\" ); // Also logs \"eventName was called\"\n </code></pre>\n "},{"return":"jQuery","signatures":[{"added":"1.0","argument":[{"desc":"A string of HTML to create on the fly. Note that this parses HTML, <strong>not</strong> XML.","name":"html","type":"htmlString"},{"desc":"A document in which the new elements will be created.","name":"ownerDocument","optional":"true","type":"document"}]},{"added":"1.4","argument":[{"desc":"A string defining a single, standalone, HTML element (e.g. <div/> or <div></div>).","name":"html","type":"htmlString"},{"desc":"An object of attributes, events, and methods to call on the newly-created element.","name":"attributes","type":"PlainObject"}]}],"examples":[{"desc":"Create a div element (and all of its contents) dynamically and append it to the body element. Internally, an element is created and its innerHTML property set to the given markup.","code":"\n$( \"<div><p>Hello</p></div>\" ).appendTo( \"body\" )\n"},{"desc":"Create some DOM elements.","code":"\n$( \"<div/>\", {\n \"class\": \"test\",\n text: \"Click me!\",\n click: function() {\n $( this ).toggleClass( \"test\" );\n }\n})\n .appendTo( \"body\" );\n"}],"desc":"Creates DOM elements on the fly from the provided string of raw HTML.","longdesc":"\n <p>In the first formulation listed above, <code>jQuery()</code> — which can also be written as <code>$()</code> — searches through the DOM for any elements that match the provided selector and creates a new jQuery object that references these elements:</p>\n <pre><code>$( \"div.foo\" );</code></pre>\n <p>If no elements match the provided selector, the new jQuery object is \"empty\"; that is, it contains no elements and has <code><a href=\"/length/\">.length</a></code> property of 0.</p>\n <h4 id=\"selector-context\">Selector Context</h4>\n <p>By default, selectors perform their searches within the DOM starting at the document root. However, an alternate context can be given for the search by using the optional second parameter to the <code>$()</code> function. For example, to do a search within an event handler, the search can be restricted like so:</p>\n <pre><code>\n$( \"div.foo\" ).click(function() {\n $( \"span\", this ).addClass( \"bar\" );\n});\n </code></pre>\n <p>When the search for the span selector is restricted to the context of <code>this</code>, only spans within the clicked element will get the additional class.</p>\n <p>Internally, selector context is implemented with the <code>.find()</code> method, so <code>$( \"span\", this )</code> is equivalent to <code>$( this ).find( \"span\" )</code>.</p>\n\n <h4 id=\"using-dom-elements\">Using DOM elements</h4>\n <p>The second and third formulations of this function create a jQuery object using one or more DOM elements that were already selected in some other way.</p>\n <p><strong>Note:</strong> These formulations are meant to consume only DOM elements; feeding mixed data to the elementArray form is particularly discouraged.</p>\n <p>A common use of this facility is to call jQuery methods on an element that has been passed to a callback function through the keyword <code>this</code>:</p>\n <pre><code>\n$( \"div.foo\" ).click(function() {\n $( this ).slideUp();\n});\n </code></pre>\n <p>This example causes elements to be hidden with a sliding animation when clicked. Because the handler receives the clicked item in the <code>this</code> keyword as a bare DOM element, the element must be passed to the <code>$()</code> function before applying jQuery methods to it.</p>\n <p>XML data returned from an Ajax call can be passed to the <code>$()</code> function so individual elements of the XML structure can be retrieved using <code>.find()</code> and other DOM traversal methods.</p>\n <pre><code>\n$.post( \"url.xml\", function( data ) {\n var $child = $( data ).find( \"child\" );\n});\n </code></pre>\n\n <h4 id=\"cloning-jquery-objects\">Cloning jQuery Objects</h4>\n <p>When a jQuery object is passed to the <code>$()</code> function, a clone of the object is created. This new jQuery object references the same DOM elements as the initial one.</p>\n\n <h4 id=\"returning-empty-set\">Returning an Empty Set</h4>\n <p>As of jQuery 1.4, calling the <code>jQuery()</code> method with <em>no arguments</em> returns an empty jQuery set (with a <code><a href=\"/length/\">.length</a></code> property of 0). In previous versions of jQuery, this would return a set containing the document node.</p>\n <h4 id=\"working-with-plain-objects\">Working With Plain Objects</h4>\n <p>At present, the only operations supported on plain JavaScript objects wrapped in jQuery are: <code>.data()</code>,<code>.prop()</code>,<code>.on()</code>, <code>.off()</code>, <code>.trigger()</code> and <code>.triggerHandler()</code>. The use of <code>.data()</code> (or any method requiring <code>.data()</code>) on a plain object will result in a new property on the object called jQuery{randomNumber} (eg. jQuery123456789).</p>\n <pre><code>\n// Define a plain object\nvar foo = { foo: \"bar\", hello: \"world\" };\n\n// Pass it to the jQuery function\nvar $foo = $( foo );\n\n// Test accessing property values\nvar test1 = $foo.prop( \"foo\" ); // bar\n\n// Test setting property values\n$foo.prop( \"foo\", \"foobar\" );\nvar test2 = $foo.prop( \"foo\" ); // foobar\n\n// Test using .data() as summarized above\n$foo.data( \"keyName\", \"someValue\" );\nconsole.log( $foo ); // will now contain a jQuery{randomNumber} property\n\n// Test binding an event name and triggering\n$foo.on( \"eventName\", function () {\n console.log( \"eventName was called\" );\n});\n\n$foo.trigger( \"eventName\" ); // Logs \"eventName was called\"\n </code></pre>\n <p>Should <code>.trigger( \"eventName\" )</code> be used, it will search for an \"eventName\" property on the object and attempt to execute it after any attached jQuery handlers are executed. It does not check whether the property is a function or not. To avoid this behavior, <code>.triggerHandler( \"eventName\" )</code> should be used instead.</p>\n <pre><code>\n$foo.triggerHandler( \"eventName\" ); // Also logs \"eventName was called\"\n </code></pre>\n "},{"return":"jQuery","signatures":{"added":"1.0","argument":{"desc":"The function to execute when the DOM is ready.","name":"callback","type":"Function"}},"examples":[{"desc":"Execute the function when the DOM is ready to be used.","code":"\n$(function() {\n // Document is ready\n});\n"},{"desc":"Use both the shortcut for $(document).ready() and the argument to write failsafe jQuery code using the $ alias, without relying on the global alias.","code":"\njQuery(function( $ ) {\n // Your code using failsafe $ alias here...\n});\n"}],"desc":"Binds a function to be executed when the DOM has finished loading.","longdesc":"\n <p>In the first formulation listed above, <code>jQuery()</code> — which can also be written as <code>$()</code> — searches through the DOM for any elements that match the provided selector and creates a new jQuery object that references these elements:</p>\n <pre><code>$( \"div.foo\" );</code></pre>\n <p>If no elements match the provided selector, the new jQuery object is \"empty\"; that is, it contains no elements and has <code><a href=\"/length/\">.length</a></code> property of 0.</p>\n <h4 id=\"selector-context\">Selector Context</h4>\n <p>By default, selectors perform their searches within the DOM starting at the document root. However, an alternate context can be given for the search by using the optional second parameter to the <code>$()</code> function. For example, to do a search within an event handler, the search can be restricted like so:</p>\n <pre><code>\n$( \"div.foo\" ).click(function() {\n $( \"span\", this ).addClass( \"bar\" );\n});\n </code></pre>\n <p>When the search for the span selector is restricted to the context of <code>this</code>, only spans within the clicked element will get the additional class.</p>\n <p>Internally, selector context is implemented with the <code>.find()</code> method, so <code>$( \"span\", this )</code> is equivalent to <code>$( this ).find( \"span\" )</code>.</p>\n\n <h4 id=\"using-dom-elements\">Using DOM elements</h4>\n <p>The second and third formulations of this function create a jQuery object using one or more DOM elements that were already selected in some other way.</p>\n <p><strong>Note:</strong> These formulations are meant to consume only DOM elements; feeding mixed data to the elementArray form is particularly discouraged.</p>\n <p>A common use of this facility is to call jQuery methods on an element that has been passed to a callback function through the keyword <code>this</code>:</p>\n <pre><code>\n$( \"div.foo\" ).click(function() {\n $( this ).slideUp();\n});\n </code></pre>\n <p>This example causes elements to be hidden with a sliding animation when clicked. Because the handler receives the clicked item in the <code>this</code> keyword as a bare DOM element, the element must be passed to the <code>$()</code> function before applying jQuery methods to it.</p>\n <p>XML data returned from an Ajax call can be passed to the <code>$()</code> function so individual elements of the XML structure can be retrieved using <code>.find()</code> and other DOM traversal methods.</p>\n <pre><code>\n$.post( \"url.xml\", function( data ) {\n var $child = $( data ).find( \"child\" );\n});\n </code></pre>\n\n <h4 id=\"cloning-jquery-objects\">Cloning jQuery Objects</h4>\n <p>When a jQuery object is passed to the <code>$()</code> function, a clone of the object is created. This new jQuery object references the same DOM elements as the initial one.</p>\n\n <h4 id=\"returning-empty-set\">Returning an Empty Set</h4>\n <p>As of jQuery 1.4, calling the <code>jQuery()</code> method with <em>no arguments</em> returns an empty jQuery set (with a <code><a href=\"/length/\">.length</a></code> property of 0). In previous versions of jQuery, this would return a set containing the document node.</p>\n <h4 id=\"working-with-plain-objects\">Working With Plain Objects</h4>\n <p>At present, the only operations supported on plain JavaScript objects wrapped in jQuery are: <code>.data()</code>,<code>.prop()</code>,<code>.on()</code>, <code>.off()</code>, <code>.trigger()</code> and <code>.triggerHandler()</code>. The use of <code>.data()</code> (or any method requiring <code>.data()</code>) on a plain object will result in a new property on the object called jQuery{randomNumber} (eg. jQuery123456789).</p>\n <pre><code>\n// Define a plain object\nvar foo = { foo: \"bar\", hello: \"world\" };\n\n// Pass it to the jQuery function\nvar $foo = $( foo );\n\n// Test accessing property values\nvar test1 = $foo.prop( \"foo\" ); // bar\n\n// Test setting property values\n$foo.prop( \"foo\", \"foobar\" );\nvar test2 = $foo.prop( \"foo\" ); // foobar\n\n// Test using .data() as summarized above\n$foo.data( \"keyName\", \"someValue\" );\nconsole.log( $foo ); // will now contain a jQuery{randomNumber} property\n\n// Test binding an event name and triggering\n$foo.on( \"eventName\", function () {\n console.log( \"eventName was called\" );\n});\n\n$foo.trigger( \"eventName\" ); // Logs \"eventName was called\"\n </code></pre>\n <p>Should <code>.trigger( \"eventName\" )</code> be used, it will search for an \"eventName\" property on the object and attempt to execute it after any attached jQuery handlers are executed. It does not check whether the property is a function or not. To avoid this behavior, <code>.triggerHandler( \"eventName\" )</code> should be used instead.</p>\n <pre><code>\n$foo.triggerHandler( \"eventName\" ); // Also logs \"eventName was called\"\n </code></pre>\n "}]} |