You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: entries/jQuery.xml
+56-48
Original file line number
Diff line number
Diff line change
@@ -42,73 +42,76 @@
42
42
<desc>Accepts a string containing a CSS selector which is then used to match a set of elements.</desc>
43
43
<longdesc>
44
44
<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>
45
-
<pre><code>$('div.foo');</code></pre>
45
+
<pre><code>$( "div.foo" );</code></pre>
46
46
<p>If no elements match the provided selector, the new jQuery object is "empty"; that is, it contains no elements and has <code><ahref="http://api.jquery.com/length/">.length</a></code> property of 0.</p>
47
47
<h4id="selector-context">Selector Context</h4>
48
-
<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>
48
+
<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>
49
49
<pre><code>
50
-
$('div.foo').click(function() {
51
-
$('span', this).addClass('bar');
50
+
$( "div.foo" ).click(function() {
51
+
$( "span", this).addClass( "bar" );
52
52
});
53
53
</code></pre>
54
54
<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>
55
-
<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>
55
+
<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>
56
+
56
57
<h4id="using-dom-elements">Using DOM elements</h4>
57
58
<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>
58
-
<p><strong>Note:</strong>These formulations are meant to consume only DOM elements; feeding mixed data to the elementArray form is particularly discouraged.</p>
59
+
<p><strong>Note:</strong>These formulations are meant to consume only DOM elements; feeding mixed data to the elementArray form is particularly discouraged.</p>
59
60
<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>
60
61
<pre><code>
61
-
$('div.foo').click(function() {
62
+
$( "div.foo" ).click(function() {
62
63
$(this).slideUp();
63
64
});
64
65
</code></pre>
65
66
<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>
66
67
<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>
<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>
76
+
74
77
<h4id="returning-empty-set">Returning an Empty Set</h4>
75
78
<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><ahref="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>
76
79
<h4id="working-with-plain-objects">Working With Plain Objects</h4>
77
80
<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>
78
81
<pre><code>
79
82
// define a plain object
80
-
var foo = {foo:'bar', hello:'world'};
83
+
var foo = {foo: "bar", hello: "world"};
81
84
82
-
// wrap this with jQuery
83
-
var $foo = $(foo);
85
+
// Pass it to the jQuery function
86
+
var $foo = $(foo);
84
87
85
88
// test accessing property values
86
-
var test1 = $foo.prop('foo'); // bar
89
+
var test1 = $foo.prop( "foo" ); // bar
87
90
88
91
// test setting property values
89
-
$foo.prop('foo', 'foobar');
90
-
var test2 = $foo.prop('foo'); // foobar
92
+
$foo.prop( "foo", "foobar" );
93
+
var test2 = $foo.prop( "foo" ); // foobar
91
94
92
95
// test using .data() as summarized above
93
-
$foo.data('keyName', 'someValue');
94
-
console.log($foo); // will now contain a jQuery{randomNumber} property
96
+
$foo.data( "keyName", "someValue");
97
+
console.log($foo); // will now contain a jQuery{randomNumber} property
95
98
96
99
// test binding an event name and triggering
97
-
$foo.bind('eventName', function (){
98
-
console.log('eventName was called');
100
+
$foo.bind( "eventName", function (){
101
+
console.log("eventName was called");
99
102
});
100
103
101
-
$foo.trigger('eventName'); // logs 'eventName was called'
104
+
$foo.trigger( "eventName" ); // logs "eventName was called"
102
105
</code></pre>
103
-
<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>
106
+
<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>
104
107
<pre><code>
105
-
$foo.triggerHandler('eventName'); // also logs 'eventName was called'
108
+
$foo.triggerHandler( "eventName" ); // also logs "eventName was called"
106
109
</code></pre>
107
110
</longdesc>
108
111
<example>
109
112
<desc>Find all p elements that are children of a div element and apply a border to them.</desc>
@@ -155,58 +158,63 @@ $foo.triggerHandler('eventName'); // also logs 'eventName was called'
155
158
<longdesc>
156
159
<h4id="creating-new-elements">Creating New Elements</h4>
157
160
<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>
<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 (with optional closing tag or quick-closing) — <code>$('<img />')</code> or <code>$('<img>')</code>, <code>$('<a></a>')</code> or <code>$('<a>')</code> — jQuery creates the element using the native JavaScript <code>createElement()</code> function.</p>
160
-
<p>When passing in complex HTML, some browsers may not generate a DOM that exactly replicates the HTML source provided. As mentioned, jQuery uses 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>
161
-
<p>Filtering isn't, however, 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 <ahref="http://code.google.com/p/html5shiv/">compatibility layer</a>.</p>
<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 (with optional closing tag or quick-closing) — <code>$( "<img />" )</code> or <code>$( "<img>" )</code>, <code>$( "<a></a>" )</code> or <code>$( "<a>" )</code> — jQuery creates the element using the native JavaScript <code>createElement()</code> function.</p>
163
+
<p>When passing in complex HTML, some browsers may not generate a DOM that exactly replicates the HTML source provided. As mentioned, jQuery uses 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>
164
+
<p>Filtering isn't, however, 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 <ahref="http://code.google.com/p/html5shiv/">compatibility layer</a>.</p>
162
165
<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>
<p>Tags that cannot contain elements may be quick-closed or not:</p>
165
-
<pre><code>$('<img />');
166
-
$('<input>');
168
+
<pre><code>$( "<img />" );
169
+
$( "<input>" );
167
170
</code></pre>
168
171
<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>
169
172
<pre><code>
170
-
var el = $('1<br/>2<br/>3'); // returns [<br>, "2", <br>]
<p>As of jQuery 1.4, the second argument to <code>jQuery()</code> can accept a plain object consisting of a superset of the properties that can be passed to the <ahref="/attr">.attr()</a> method. Furthermore, any <ahref="/category/events/">event type</a> can be passed in, and the following jQuery methods can be called: <ahref="/val">val</a>, <ahref="/css">css</a>, <ahref="/html">html</a>, <ahref="/text">text</a>, <ahref="/data">data</a>, <ahref="/width">width</a>, <ahref="/height">height</a>, or <ahref="/offset">offset</a>.</p>
175
178
<p><strong>As of jQuery 1.8</strong>, any jQuery instance method (a method of <code>jQuery.fn</code>) can be used as a property of the object passed to the second parameter:</p>
176
179
<pre><code>
177
180
$( "<div></div>", {
178
-
append: "<span>hello</span>"
181
+
"class": "my-div",
182
+
on: {
183
+
touchstart: function( event ) {
184
+
// do something
185
+
}
186
+
}
179
187
}).appendTo( "body" );
180
188
</code></pre>
181
189
<p>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>
182
-
<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>
190
+
<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>
183
191
<p>Unsupported in IE:</p>
184
192
<pre><code>
185
-
$('<input />', {
186
-
type: 'text',
187
-
name: 'test'
188
-
}).appendTo("body");
193
+
$( "<input />", {
194
+
type: "text",
195
+
name: "test"
196
+
}).appendTo("body");
189
197
</code></pre>
190
198
<p>Supported workaround:</p>
191
199
<pre><code>
192
-
$('<input type="text" />').attr({
193
-
name: 'test'
194
-
}).appendTo("body");
200
+
$( "<input type="text" />" ).attr({
201
+
name: "test"
202
+
}).appendTo("body");
195
203
</code></pre>
196
204
</longdesc>
197
205
<example>
198
206
<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.</desc>
<desc>Binds a function to be executed when the DOM has finished loading.</desc>
223
231
<longdesc>
224
-
<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>
232
+
<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>
225
233
</longdesc>
226
234
<example>
227
235
<desc>Execute the function when the DOM is ready to be used.</desc>
0 commit comments