PageRenderTime 48ms CodeModel.GetById 19ms RepoModel.GetById 1ms app.codeStats 0ms

/1.4.2/docs/jQuery/index.html

https://github.com/mustardamus/jquery-api-scrape
HTML | 246 lines | 239 code | 7 blank | 0 comment | 0 complexity | 8105510b4438f5115ab3b104f4127e4d MD5 | raw file
    

  1. <!DOCTYPE html>
    2. 

  2. <html lang='en'><head><meta http-equiv='content-type' content='text/html; charset=UTF-8' /></head><body>
    3. 

  3. <div class="entry-content">

    4. 

  4.         <div class="entry-title roundTop">

    5. 

  5. 				<h1 class="jq-clearfix">jQuery()</h1>

    6. 

  6.   				<div class="entry-meta">Categories:

    7. 

  7.   					<span class="category"><a href="http://api.jquery.com/category/core/" title="View all posts in Core">Core</a></span>  

    8. 

  8.     

    9. 

  9.   				</div>

    10. 

  10. </div>

    11. 

  11. 

  12. <fieldset class="toc">
    13. 

  13. <legend>Contents:</legend>
    14. 

  14. <ul class="toc-list">
    15. 

  15. <li>
    16. 

  16. <a href="#jQuery1">jQuery( selector, [ context ] ) </a><ul>
    17. 

  17. <li>jQuery( selector, [ context ] )
    18. 

  18. 	  					</li>
    19. 

  19. <li>jQuery( element )
    20. 

  20. 	  					</li>
    21. 

  21. <li>jQuery( elementArray )
    22. 

  22. 	  					</li>
    23. 

  23. <li>jQuery( jQuery object )
    24. 

  24. 	  					</li>
    25. 

  25. <li>jQuery()
    26. 

  26. 	  					</li>
    27. 

  27. </ul>
    28. 

  28. </li>
    29. 

  29. <li>
    30. 

  30. <a href="#jQuery2">jQuery( html, [ ownerDocument ] ) </a><ul>
    31. 

  31. <li>jQuery( html, [ ownerDocument ] )
    32. 

  32. 	  					</li>
    33. 

  33. <li>jQuery( html, props )
    34. 

  34. 	  					</li>
    35. 

  35. </ul>
    36. 

  36. </li>
    37. 

  37. <li>
    38. 

  38. <a href="#jQuery3">jQuery( callback ) </a><ul><li>jQuery( callback )
    39. 

  39. 	  					</li></ul>
    40. 

  40. </li>
    41. 

  41. </ul>
    42. 

  42. </fieldset>
    43. 

  43. <div class="entry method" id="jQuery1">
    44. 

  44. <h2 class="jq-clearfix roundTop section-title">
    45. 

  45. <span class="name">jQuery( selector, [ context ] )</span> <span class="returns">Returns: <a class="return" href="http://docs.jquery.com/Types#jQuery">jQuery</a></span>
    46. 

  46. </h2>
    47. 

  47. <div class="jq-box roundBottom entry-details">
    48. 

  48. <p class="desc"><strong>Description: </strong>Accepts a string containing a CSS selector which is then used to match a set of elements.</p>
    49. 

  49. <ul class="signatures">
    50. 

  50. <li class="signature" id="jQuery-selector-context">
    51. 

  51. <h4 class="name">
    52. 

  52. <span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>jQuery( selector, [ context ] )</h4>
    53. 

  53. <p class="arguement"><strong>selector</strong>A string containing a selector expression</p>
    54. 

  54. <p class="arguement"><strong>context</strong>A DOM Element, Document, or jQuery to use as context</p>
    55. 

  55. </li>
    56. 

  56. <li class="signature" id="jQuery-element">
    57. 

  57. <h4 class="name">
    58. 

  58. <span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>jQuery( element )</h4>
    59. 

  59. <p class="arguement"><strong>element</strong>A DOM element to wrap in a jQuery object.</p>
    60. 

  60. </li>
    61. 

  61. <li class="signature" id="jQuery-elementArray">
    62. 

  62. <h4 class="name">
    63. 

  63. <span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>jQuery( elementArray )</h4>
    64. 

  64. <p class="arguement"><strong>elementArray</strong>An array containing a set of DOM elements to wrap in a jQuery object.</p>
    65. 

  65. </li>
    66. 

  66. <li class="signature" id="jQuery-jQueryobject">
    67. 

  67. <h4 class="name">
    68. 

  68. <span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>jQuery( jQuery object )</h4>
    69. 

  69. <p class="arguement"><strong>jQuery object</strong>An existing jQuery object to clone.</p>
    70. 

  70. </li>
    71. 

  71. <li class="signature" id="jQuery"><h4 class="name">
    72. 

  72. <span class="versionAdded">version added: <a href="/category/version/1.4/">1.4</a></span>jQuery()</h4></li>
    73. 

  73. </ul>
    74. 

  74. <div class="longdesc">
    75. 

  75. <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>
    76. 

  76. <pre>$('div.foo');</pre>
    77. 

  77. <h4 id="selector-context">Selector Context</h4>
    78. 

  78. <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, if within a callback function we wish to do a search for an element, we can restrict that search:</p>
    79. 

  79. <pre>
    80. 

  80. $('div.foo').click(function() {
    81. 

  81.   $('span', this).addClass('bar');
    82. 

  82. });
    83. 

  83. </pre>
    84. 

  84. <p>Since we've restricted the span selector to the context of <code>this</code>, only spans within the clicked element will get the additional class.</p>
    85. 

  85. <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>
    86. 

  86. <h4 id="using-dom-elements">Using DOM elements</h4>
    87. 

  87. <p>The second and third formulations of this function allow us to create a jQuery object using a DOM element or elements that we have already found in some other way. 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>
    88. 

  88. <pre>
    89. 

  89. $('div.foo').click(function() {
    90. 

  90.   $(this).slideUp();
    91. 

  91. });
    92. 

  92. </pre>
    93. 

  93. <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 wrapped in a jQuery object before we can call jQuery methods on it.</p>
    94. 

  94. <p>When XML data is returned from an Ajax call, we can use the  <code>$()</code> function to wrap it in a jQuery object that we can easily work with. Once this is done, we can retrieve individual elements of the XML structure using <code>.find()</code> and other DOM traversal methods.</p>
    95. 

  95. <h4 id="cloning-jquery-objects">Cloning jQuery Objects</h4>
    96. 

  96. <p>When a jQuery object is passed as a parameter 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>
    97. 

  97. <h4 id="returning-empty-set">Returning an Empty Set</h4>
    98. 

  98. <p>As of jQuery 1.4,  calling the <code>jQuery()</code> method with <em>no arguments</em> returns an empty jQuery set. In previous versions of jQuery, this would return a set containing the document node.</p>
    99. 

  99. </div>
    100. 

  100. <h3>Examples:</h3>
    101. 

  101. <div class="entry-examples" id="entry-examples">
    102. 

  102. <div id="example-0">
    103. 

  103. <h4>Example: <span class="desc">Finds all p elements that are children of a div element.</span>
    104. 

  104. </h4>
    105. 

  105. <pre><code class="example demo-code">&lt;!DOCTYPE html&gt;
    106. 

  106. &lt;html&gt;
    107. 

  107. &lt;head&gt;
    108. 

  108.   &lt;script src="http://code.jquery.com/jquery-latest.min.js"&gt;&lt;/script&gt;
    109. 

  109. &lt;/head&gt;
    110. 

  110. &lt;body&gt;
    111. 

  111. 	&lt;p&gt;one&lt;/p&gt; &lt;div&gt;&lt;p&gt;two&lt;/p&gt;&lt;/div&gt; &lt;p&gt;three&lt;/p&gt;
    112. 

  112. &lt;script&gt;$("div &gt; p").css("border", "1px solid gray");&lt;/script&gt;
    113. 

  113. 

  114. &lt;/body&gt;
    115. 

  115. &lt;/html&gt;</code></pre>
    116. 

  116. <h4>Demo:</h4>
    117. 

  117. <div class="demo code-demo"></div>
    118. 

  118. <h4>Result:</h4>
    119. 

  119. <pre><code class="results">[ &lt;p&gt;two&lt;/p&gt; ] </code></pre>
    120. 

  120. </div>
    121. 

  121. <div id="example-1">
    122. 

  122. <h4>Example: <span class="desc">Finds all inputs of type radio within the first form in the document.</span>
    123. 

  123. </h4>
    124. 

  124. <pre><code class="example">$("input:radio", document.forms[0]);</code></pre>
    125. 

  125. </div>
    126. 

  126. <div id="example-2">
    127. 

  127. <h4>Example: <span class="desc">Finds all div elements within an XML document from an Ajax response.</span>
    128. 

  128. </h4>
    129. 

  129. <pre><code class="example">$("div", xml.responseXML);</code></pre>
    130. 

  130. </div>
    131. 

  131. <div id="example-3">
    132. 

  132. <h4>Example: <span class="desc">Sets the background color of the page to black.</span>
    133. 

  133. </h4>
    134. 

  134. <pre><code class="example">$(document.body).css( "background", "black" );</code></pre>
    135. 

  135. </div>
    136. 

  136. <div id="example-4">
    137. 

  137. <h4>Example: <span class="desc">Hides all the input elements within a form.</span>
    138. 

  138. </h4>
    139. 

  139. <pre><code class="example">$(myForm.elements).hide()</code></pre>
    140. 

  140. </div>
    141. 

  141. </div>
    142. 

  142. </div>
    143. 

  143. </div>
    144. 

  144. <div class="entry method" id="jQuery2">
    145. 

  145. <h2 class="jq-clearfix roundTop section-title">
    146. 

  146. <span class="name">jQuery( html, [ ownerDocument ] )</span> <span class="returns">Returns: <a class="return" href="http://docs.jquery.com/Types#jQuery">jQuery</a></span>
    147. 

  147. </h2>
    148. 

  148. <div class="jq-box roundBottom entry-details">
    149. 

  149. <p class="desc"><strong>Description: </strong>Creates DOM elements on the fly from the provided string of raw HTML.</p>
    150. 

  150. <ul class="signatures">
    151. 

  151. <li class="signature" id="jQuery-html-ownerDocument">
    152. 

  152. <h4 class="name">
    153. 

  153. <span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>jQuery( html, [ ownerDocument ] )</h4>
    154. 

  154. <p class="arguement"><strong>html</strong>A string of HTML to create on the fly. Note that this parses HTML, <strong>not</strong> XML.</p>
    155. 

  155. <p class="arguement"><strong>ownerDocument</strong>A document in which the new elements will be created</p>
    156. 

  156. </li>
    157. 

  157. <li class="signature" id="jQuery-html-props">
    158. 

  158. <h4 class="name">
    159. 

  159. <span class="versionAdded">version added: <a href="/category/version/1.4/">1.4</a></span>jQuery( html, props )</h4>
    160. 

  160. <p class="arguement"><strong>html</strong>A string defining a single, standalone, HTML element (e.g. &lt;div/&gt; or &lt;div&gt;&lt;/div&gt;).</p>
    161. 

  161. <p class="arguement"><strong>props</strong>An map of attributes, events, and methods to call on the newly-created element.</p>
    162. 

  162. </li>
    163. 

  163. </ul>
    164. 

  164. <div class="longdesc">
    165. 

  165. <h4 id="creating-new-elements">Creating New Elements</h4>
    166. 

  166. <p>If a string is passed as the parameter to  <code>$()</code>, jQuery examines the string to see if it looks like HTML (i.e., it has <code>&lt;tag ... &gt;</code> somewhere within the string). If not, the string is interpreted as a selector expression, as explained above. But if the string appears to be an HTML snippet, jQuery attempts to create new DOM elements as described by the HTML. Then a jQuery object is created and returned that refers to these elements. We can perform any of the usual jQuery methods on this object:</p>
    167. 

  167. <pre>$('&lt;p id="test"&gt;My &lt;em&gt;new&lt;/em&gt; text&lt;/p&gt;').appendTo('body');</pre>
    168. 

  168. <p>When the HTML is more complex than a single tag without attributes, as it is in the above example, the actual creation of the elements is handled by the browser's <code>innerHTML</code> mechanism. Specifically, jQuery creates a new &lt;div&gt; element and sets the innerHTML property of the element to the HTML snippet that was passed in. When the parameter has a single tag, such as  <code>$('&lt;img /&gt;')</code> or  <code>$('&lt;a&gt;&lt;/a&gt;')</code>, jQuery creates the element using the native JavaScript <code>createElement()</code> function.</p>
    169. 

  169. <p>To ensure cross-platform compatibility, the snippet must be well-formed. Tags that can contain other elements should be paired with a closing tag:</p>
    170. 

  170. <pre>$('&lt;a href="http://jquery.com"&gt;&lt;/a&gt;');</pre>
    171. 

  171. <p>Alternatively, jQuery allows XML-like tag syntax (with or without a space before the slash):</p>
    172. 

  172. <pre>$('&lt;a/&gt;');</pre>
    173. 

  173. <p>Tags that cannot contain elements may be quick-closed or not:</p>
    174. 

  174. <pre>$('&lt;img /&gt;');
    175. 

  175. $('&lt;input&gt;');
    176. 

  176. </pre>
    177. 

  177. <p>As of jQuery 1.4, we can pass a map of properties to the second argument. This argument accepts a superset of properties that can be passed to the <a href="/attr">.attr()</a> method. Furthermore, any <a href="/category/events/">event type</a> can be passed in, and the following jQuery methods can be called: <a href="/val">val</a>, <a href="/css">css</a>, <a href="/html">html</a>, <a href="/text">text</a>, <a href="/data">data</a>, <a href="/width">width</a>, <a href="/height">height</a>, or <a href="/offset">offset</a>. Note that Internet Explorer will not allow you to create an <code>input</code> element and change its type; you must specify the type using <code>'&lt;input type="checkbox" /&gt;'</code> for example.</p>
    178. 

  178. </div>
    179. 

  179. <h3>Examples:</h3>
    180. 

  180. <div class="entry-examples" id="entry-examples-1">
    181. 

  181. <div id="example-1-0">
    182. 

  182. <h4>Example: <span class="desc">Creates a div element (and all of its contents) dynamically, and appends it to the body element. Internally, an element is created and its innerHTML property set to the given markup. It is therefore both quite flexible and limited.</span>
    183. 

  183. </h4>
    184. 

  184. <pre><code class="example">$("&lt;div&gt;&lt;p&gt;Hello&lt;/p&gt;&lt;/div&gt;").appendTo("body")</code></pre>
    185. 

  185. </div>
    186. 

  186. <div id="example-1-1">
    187. 

  187. <h4>Example: <span class="desc">Create some DOM elements.</span>
    188. 

  188. </h4>
    189. 

  189. <pre><code class="example">$("&lt;div/&gt;", {
    190. 

  190.   "class": "test",
    191. 

  191.   text: "Click me!",
    192. 

  192.   click: function(){
    193. 

  193.     $(this).toggleClass("test");
    194. 

  194.   }
    195. 

  195. }).appendTo("body");
    196. 

  196. 

  197. $("&lt;input&gt;", {
    198. 

  198.   type: "text",
    199. 

  199.   val: "Test",
    200. 

  200.   focusin: function() {
    201. 

  201.     $(this).addClass("active");
    202. 

  202.   },
    203. 

  203.   focusout: function() {
    204. 

  204.     $(this).removeClass("active");
    205. 

  205.   }
    206. 

  206. }).appendTo("form");</code></pre>
    207. 

  207. </div>
    208. 

  208. </div>
    209. 

  209. </div>
    210. 

  210. </div>
    211. 

  211. <div class="entry method" id="jQuery3">
    212. 

  212. <h2 class="jq-clearfix roundTop section-title">
    213. 

  213. <span class="name">jQuery( callback )</span> <span class="returns">Returns: <a class="return" href="http://docs.jquery.com/Types#jQuery">jQuery</a></span>
    214. 

  214. </h2>
    215. 

  215. <div class="jq-box roundBottom entry-details">
    216. 

  216. <p class="desc"><strong>Description: </strong>Binds a function to be executed when the DOM has finished loading.</p>
    217. 

  217. <ul class="signatures"><li class="signature" id="jQuery-callback">
    218. 

  218. <h4 class="name">
    219. 

  219. <span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>jQuery( callback )</h4>
    220. 

  220. <p class="arguement"><strong>callback</strong>The function to execute when the DOM is ready.</p>
    221. 

  221. </li></ul>
    222. 

  222. <div class="longdesc"><p>This function behaves just like <code>$(document).ready()</code>, in that it should be used to wrap other <code>$()</code> operations on your page that depend on the DOM being ready. While this function is, technically, chainable, there really isn't much use for chaining against it.</p></div>
    223. 

  223. <h3>Examples:</h3>
    224. 

  224. <div class="entry-examples" id="entry-examples-2">
    225. 

  225. <div id="example-2-0">
    226. 

  226. <h4>Example: <span class="desc">Executes the function when the DOM is ready to be used.</span>
    227. 

  227. </h4>
    228. 

  228. <pre><code class="example">$(function(){
    229. 

  229.   // Document is ready
    230. 

  230. });</code></pre>
    231. 

  231. </div>
    232. 

  232. <div id="example-2-1">
    233. 

  233. <h4>Example: <span class="desc">Uses both the shortcut for $(document).ready() and the argument to write failsafe jQuery code using the $ alias, without relying on the global alias.</span>
    234. 

  234. </h4>
    235. 

  235. <pre><code class="example">jQuery(function($) {
    236. 

  236.   // Your code using failsafe $ alias here...
    237. 

  237. });</code></pre>
    238. 

  238. </div>
    239. 

  239. </div>
    240. 

  240. </div>
    241. 

  241. </div>
    242. 

  242. 

  243. 

    244. 

  244. 				</div>
    245. 

  245. 

  246. </body></html>
    247.