1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
|
<!DOCTYPE html>
<html lang='en'><head><meta http-equiv='content-type' content='text/html; charset=UTF-8' /></head><body>
<div class="entry-content">
<div class="entry-title roundTop">
<h1 class="jq-clearfix">jQuery()</h1>
<div class="entry-meta jq-clearfix">
Categories:
<span class="category"><a href="http://api.jquery.com/category/core/" title="View all posts in Core">Core</a></span>
</div>
</div>
<div class="toc">
<h4><span>Contents:</span></h4>
<ul class="toc-list">
<li>
<a href="#jQuery1">jQuery( selector [ , context ] ) </a><ul>
<li>jQuery( selector [, context] )
</li>
<li>jQuery( element )
</li>
<li>jQuery( object )
</li>
<li>jQuery( elementArray )
</li>
<li>jQuery( jQuery object )
</li>
<li>jQuery()
</li>
</ul>
</li>
<li>
<a href="#jQuery2">jQuery( html [ , ownerDocument ] ) </a><ul>
<li>jQuery( html [, ownerDocument] )
</li>
<li>jQuery( html, props )
</li>
</ul>
</li>
<li>
<a href="#jQuery3">jQuery( callback ) </a><ul><li>jQuery( callback )
</li></ul>
</li>
</ul>
</div>
<div id="jQuery1" class="entry method">
<h2 class="jq-clearfix roundTop section-title">
<span class="name">jQuery( selector [, context] )</span> <span class="returns">Returns: <a class="return" href="http://api.jquery.com/Types/#jQuery">jQuery</a></span>
</h2>
<div class="jq-box roundBottom entry-details">
<p class="desc"><strong>Description: </strong>Accepts a string containing a CSS selector which is then used to match a set of elements.</p>
<ul class="signatures">
<li class="signature" id="jQuery-selector-context">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>jQuery( selector [, context] )</h4>
<p class="arguement"><strong>selector</strong>A string containing a selector expression</p>
<p class="arguement"><strong>context</strong>A DOM Element, Document, or jQuery to use as context</p>
</li>
<li class="signature" id="jQuery-element">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>jQuery( element )</h4>
<p class="arguement"><strong>element</strong>A DOM element to wrap in a jQuery object.</p>
</li>
<li class="signature" id="jQuery-object">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>jQuery( object )</h4>
<p class="arguement"><strong>object</strong>A plain object to wrap in a jQuery object.</p>
</li>
<li class="signature" id="jQuery-elementArray">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>jQuery( elementArray )</h4>
<p class="arguement"><strong>elementArray</strong>An array containing a set of DOM elements to wrap in a jQuery object.</p>
</li>
<li class="signature" id="jQuery-jQuery object">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>jQuery( jQuery object )</h4>
<p class="arguement"><strong>jQuery object</strong>An existing jQuery object to clone.</p>
</li>
<li class="signature" id="jQuery"><h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.4/">1.4</a></span>jQuery()</h4></li>
</ul>
<div class="longdesc">
<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>
<pre>$('div.foo');</pre>
<h4 id="selector-context">Selector Context</h4>
<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>
<pre>
$('div.foo').click(function() {
$('span', this).addClass('bar');
});
</pre>
<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>
<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>
<h4 id="using-dom-elements">Using DOM elements</h4>
<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. 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>
<pre>
$('div.foo').click(function() {
$(this).slideUp();
});
</pre>
<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>
<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>
<pre>
$.post('url.xml', function(data) {
var $child = $(data).find('child');
})
</pre>
<h4 id="cloning-jquery-objects">Cloning jQuery Objects</h4>
<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>
<h4 id="returning-empty-set">Returning an Empty Set</h4>
<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="http://api.jquery.com/length/">.length</a></code> property of 0). In previous versions of jQuery, this would return a set containing the document node.</p>
<h4 id="working-with-plain-objects">Working With Plain Objects</h4>
<p>At present, the only operations supported on plain JavaScript objects wrapped in jQuery are: <code>.data()</code>,<code>.prop()</code>,<code>.bind()</code>, <code>.unbind()</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>
<pre>
// define a plain object
var foo = {foo:'bar', hello:'world'};
// wrap this with jQuery
var $foo = $(foo);
// test accessing property values
var test1 = $foo.prop('foo'); // bar
// test setting property values
$foo.prop('foo', 'foobar');
var test2 = $foo.prop('foo'); // foobar
// test using .data() as summarized above
$foo.data('keyName', 'someValue');
console.log($foo); // will now contain a jQuery{randomNumber} property
// test binding an event name and triggering
$foo.bind('eventName', function (){
console.log('eventName was called');
});
$foo.trigger('eventName'); // logs 'eventName was called'
</pre>
<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>
<pre>
$foo.triggerHandler('eventName'); // also logs 'eventName was called'
</pre>
</div>
<h3>Examples:</h3>
<div class="entry-examples" id="entry-examples">
<div id="example-0">
<h4>Example: <span class="desc">Find all p elements that are children of a div element and apply a border to them.</span>
</h4>
<pre class="prettyprint"><code class="example demo-code"><!DOCTYPE html>
<html>
<head>
<script src="http://code.jquery.com/jquery-1.7rc2.js"></script>
</head>
<body>
<p>one</p> <div><p>two</p></div> <p>three</p>
<script>
$("div > p").css("border", "1px solid gray");
</script>
</body>
</html></code></pre>
<h4>Demo:</h4>
<div class="demo code-demo"></div>
</div>
<div id="example-1">
<h4>Example: <span class="desc">Find all inputs of type radio within the first form in the document.</span>
</h4>
<pre class="prettyprint"><code class="example">$("input:radio", document.forms[0]);</code></pre>
</div>
<div id="example-2">
<h4>Example: <span class="desc">Find all div elements within an XML document from an Ajax response.</span>
</h4>
<pre class="prettyprint"><code class="example">$("div", xml.responseXML);</code></pre>
</div>
<div id="example-3">
<h4>Example: <span class="desc">Set the background color of the page to black.</span>
</h4>
<pre class="prettyprint"><code class="example">$(document.body).css( "background", "black" );</code></pre>
</div>
<div id="example-4">
<h4>Example: <span class="desc">Hide all the input elements within a form.</span>
</h4>
<pre class="prettyprint"><code class="example">$(myForm.elements).hide()</code></pre>
</div>
</div>
</div>
</div>
<div id="jQuery2" class="entry method">
<h2 class="jq-clearfix roundTop section-title">
<span class="name">jQuery( html [, ownerDocument] )</span> <span class="returns">Returns: <a class="return" href="http://api.jquery.com/Types/#jQuery">jQuery</a></span>
</h2>
<div class="jq-box roundBottom entry-details">
<p class="desc"><strong>Description: </strong>Creates DOM elements on the fly from the provided string of raw HTML.</p>
<ul class="signatures">
<li class="signature" id="jQuery-html-ownerDocument">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>jQuery( html [, ownerDocument] )</h4>
<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>
<p class="arguement"><strong>ownerDocument</strong>A document in which the new elements will be created</p>
</li>
<li class="signature" id="jQuery-html-props">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.4/">1.4</a></span>jQuery( html, props )</h4>
<p class="arguement"><strong>html</strong>A string defining a single, standalone, HTML element (e.g. <div/> or <div></div>).</p>
<p class="arguement"><strong>props</strong>An map of attributes, events, and methods to call on the newly-created element.</p>
</li>
</ul>
<div class="longdesc">
<h4 id="creating-new-elements">Creating New Elements</h4>
<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><tag ... ></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. You can perform any of the usual jQuery methods on this object:</p>
<pre>$('<p id="test">My <em>new</em> text</p>').appendTo('body');</pre>
<p>If 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. In most cases, jQuery creates a new <div> 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>$('<img />')</code> or <code>$('<a></a>')</code>, jQuery creates the element using the native JavaScript <code>createElement()</code> function.</p>
<p>When passing in complex HTML, some browsers may not generate a DOM that exactly replicates the HTML source provided. As mentioned, we use the browser's <code>.innerHTML</code> property to parse the passed HTML and insert it into the current document. During this process, some browsers filter out certain elements such as <code><html></code>, <code><title></code>, or <code><head></code> elements. As a result, the elements inserted may not be representative of the original string passed.</p>
<p> Filtering isn't however just limited to these tags. For example, Internet Explorer prior to version 8 will also convert all <code>href</code> properties on links to absolute URLs, and Internet Explorer prior to version 9 will not correctly handle HTML5 elements without the addition of a separate <a href="http://code.google.com/p/html5shiv/">compatibility layer</a>.</p>
<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>
<pre>$('<a href="http://jquery.com"></a>');</pre>
<p>Alternatively, jQuery allows XML-like tag syntax (with or without a space before the slash):</p>
<pre>$('<a/>');</pre>
<p>Tags that cannot contain elements may be quick-closed or not:</p>
<pre>$('<img />');
$('<input>');
</pre>
<p>When passing HTML to <code>jQuery()</code>, please also note that text nodes are not treated as DOM elements. With the exception of a few methods (such as <code>.content()</code>), they are generally otherwise ignored or removed. E.g:</p>
<pre>
var el = $('1<br/>2<br/>3'); // returns [<br>, "2", <br>]
el = $('1<br/>2<br/>3 >'); // returns [<br>, "2", <br>, "3 &gt;"]
</pre>
<p>This behaviour is expected. </p>
<p>As of jQuery 1.4, the second argument to <code>jQuery()</code> can accept a map consisting of a superset of the 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>. The name <code>"class"</code> must be quoted in the map since it is a JavaScript reserved word, and <code>"className"</code> cannot be used since it is not the correct attribute name. </p>
<p><strong>Note:</strong> Internet Explorer will not allow you to create an <code>input</code> or <code>button</code> element and change its type; you must specify the type using <code>'<input type="checkbox" />'</code> for example. A demonstration of this can be seen below:</p>
<p>Unsupported in IE:</p>
<pre>
$('<input />', {
type: 'text',
name: 'test'
}).appendTo("body");
</pre>
<p>Supported workaround:</p>
<pre>
$('<input type="text" />').attr({
name: 'test'
}).appendTo("body");
</pre>
</div>
<h3>Examples:</h3>
<div class="entry-examples" id="entry-examples-1">
<div id="example-1-0">
<h4>Example: <span class="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.</span>
</h4>
<pre class="prettyprint"><code class="example">$("<div><p>Hello</p></div>").appendTo("body")</code></pre>
</div>
<div id="example-1-1">
<h4>Example: <span class="desc">Create some DOM elements.</span>
</h4>
<pre class="prettyprint"><code class="example">$("<div/>", {
"class": "test",
text: "Click me!",
click: function(){
$(this).toggleClass("test");
}
}).appendTo("body");</code></pre>
</div>
</div>
</div>
</div>
<div id="jQuery3" class="entry method">
<h2 class="jq-clearfix roundTop section-title">
<span class="name">jQuery( callback )</span> <span class="returns">Returns: <a class="return" href="http://api.jquery.com/Types/#jQuery">jQuery</a></span>
</h2>
<div class="jq-box roundBottom entry-details">
<p class="desc"><strong>Description: </strong>Binds a function to be executed when the DOM has finished loading.</p>
<ul class="signatures"><li class="signature" id="jQuery-callback">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.0/">1.0</a></span>jQuery( callback )</h4>
<p class="arguement"><strong>callback</strong>The function to execute when the DOM is ready.</p>
</li></ul>
<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>
<h3>Examples:</h3>
<div class="entry-examples" id="entry-examples-2">
<div id="example-2-0">
<h4>Example: <span class="desc">Execute the function when the DOM is ready to be used.</span>
</h4>
<pre class="prettyprint"><code class="example">$(function(){
// Document is ready
});
</code></pre>
</div>
<div id="example-2-1">
<h4>Example: <span class="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.</span>
</h4>
<pre class="prettyprint"><code class="example">jQuery(function($) {
// Your code using failsafe $ alias here...
});</code></pre>
</div>
</div>
</div>
</div>
</div>
</body></html>
|
