In the first two variations, this method is a shortcut for .bind("click", handler), as well as for .on("click", handler) as of jQuery 1.7. In the third variation, when .click() is called without arguments, it is a shortcut for .trigger("click").

The click event is sent to an element when the mouse pointer is over the element, and the mouse button is pressed and released. Any HTML element can receive this event.

For example, consider the HTML:
+    

+      
This page describes the click event. For the deprecated .click() method, see .click().
+    
+    
The click event is sent to an element when the mouse pointer is over the element, and the mouse button is pressed and released. Any HTML element can receive this event.
+    For example, consider the HTML:
+    

 <div id="target">
   Click here
 </div>
 <div id="other">
   Trigger the handler
-</div>
-    

+</div>
+    

-

+ +

The event handler can be bound to any <div>:

$("#target").click(function() {
-  alert("Handler for .click() called.");
-});

+$( "#target" ).on( "click", function() {
+  alert( "Handler for `click` called." );
+} );
+    

Now if we click on this element, the alert is displayed:

- Handler for .click() called. + Handler for `click` called.

We can also trigger the event when a different element is clicked:

$("#other").click(function() {
-  $("#target").click();
-});

After this code executes, clicks on Trigger the handler will also alert the message.

+$( "#other" ).on( "click", function() {
+  $( "#target" ).trigger( "click" );
+} );
+    

After this code executes, clicking on Trigger the handler will also alert the message.

The click event is only triggered after this exact series of events:

• The mouse button is depressed while the pointer is inside the element.
@@ -56,24 +63,51 @@ Hide paragraphs on a page when they are clicked: - + p { + color: red; + margin: 5px; + cursor: pointer; + } + p:hover { + background: yellow; + } +]]> + - Trigger the click event on all of the paragraphs on the page: - + Trigger the click event on all the paragraphs on the page: + - - \ No newline at end of file + + + + + + Trigger the "click" event on an element. + + 1.0 + + The string "click". + + + +

See the description for .on( "click", ... ).

+ + + + + + diff --git a/entries/clone.xml b/entries/clone.xml index 1ce4883de..764b66686 100644 --- a/entries/clone.xml +++ b/entries/clone.xml @@ -18,91 +18,71 @@ Create a deep copy of the set of matched elements. -

The .clone() method performs a deep copy of the set of matched elements, meaning that it copies the matched elements as well as all of their descendant elements and text nodes. When used in conjunction with one of the insertion methods, .clone() is a convenient way to duplicate elements on a page. Consider the following HTML:

-

<div class="container">
+    
The .clone() method performs a deep copy of the set of matched elements, meaning that it copies the matched elements as well as all of their descendant elements and text nodes.
+    

+      
Note: For performance reasons, the dynamic state of certain form elements (e.g., user data typed into textarea and user selections made to a select) is not copied to the cloned elements. When cloning input elements, the dynamic state of the element (e.g., user data typed into text inputs and user selections made to a checkbox) is retained in the cloned elements.
+    
+    
When used in conjunction with one of the insertion methods, .clone() is a convenient way to duplicate elements on a page. Consider the following HTML:
+    

+<div class="container">
   <div class="hello">Hello</div>
   <div class="goodbye">Goodbye</div>
-</div>
-    
As shown in the discussion for .append(),  normally when an element is inserted somewhere in the DOM, it is moved from its old location. So, given the code:
-    
$('.hello').appendTo('.goodbye');
+</div>
+    

+

As shown in the discussion for .append(), normally when an element is inserted somewhere in the DOM, it is moved from its old location. So, given the code:

+

+$( ".hello" ).appendTo( ".goodbye" );
+    

The resulting DOM structure would be:

-

<div class="container">
+    

+<div class="container">
   <div class="goodbye">
     Goodbye
     <div class="hello">Hello</div>
   </div>
-</div>
+</div>
+    

To prevent this and instead create a copy of the element, you could write the following:

-

$('.hello').clone().appendTo('.goodbye');

+

+$( ".hello" ).clone().appendTo( ".goodbye" );
+    

This would produce:

-

<div class="container">
+    

+<div class="container">
   <div class="hello">Hello</div>
   <div class="goodbye">
     Goodbye
     <div class="hello">Hello</div>
   </div>
-</div>
-    

+</div>
+    

+

Note: When using the .clone() method, you can modify the cloned elements or their contents before (re-)inserting them into the document.

- +

Normally, any event handlers bound to the original element are not copied to the clone. The optional withDataAndEvents parameter allows us to change this behavior, and to instead make copies of all of the event handlers as well, bound to the new copy of the element. As of jQuery 1.4, all element data (attached by the .data() method) is also copied to the new copy.

However, objects and arrays within element data are not copied and will continue to be shared between the cloned element and the original element. To deep copy all data, copy each one manually:

-

var $elem = $('#elem').data( "arr": [ 1 ] ), // Original element with attached data
+    

+// Original element with attached data
+var $elem = $( "#elem" ).data( "arr", [ 1 ] ),
     $clone = $elem.clone( true )
-    .data( "arr", $.extend( [], $elem.data("arr") ) ); // Deep copy to prevent data sharing
-
+      // Deep copy to prevent data sharing
+      .data( "arr", $.extend( [], $elem.data( "arr" ) ) );
+    

As of jQuery 1.5, withDataAndEvents can be optionally enhanced with deepWithDataAndEvents to copy the events and data for all children of the cloned element.

-

+

Note: Using .clone() has the side-effect of producing elements with duplicate id attributes, which are supposed to be unique. Where possible, it is recommended to avoid cloning elements with this attribute or using class attributes as identifiers instead.

-

+ Clones all b elements (and selects the clones) and prepends them to all paragraphs. - - - When using .clone() to clone a collection of elements that are not attached to the DOM, their order when inserted into the DOM is not guaranteed. However, it may be possible to preserve sort order with a workaround, as demonstrated: - - - - \ No newline at end of file + diff --git a/entries/closest.xml b/entries/closest.xml index 996b71860..903ba1a74 100644 --- a/entries/closest.xml +++ b/entries/closest.xml @@ -14,12 +14,12 @@ A string containing a selector expression to match elements against. - A DOM element within which a matching element may be found. If no context is passed in then the context of the jQuery set will be used instead. + A DOM element within which a matching element may be found. 1.6 - + A jQuery object to match elements against. @@ -55,8 +55,8 @@ Travels up the DOM tree to the document's root element, adding each ancestor element to a temporary collection; it then filters that collection based on a selector if one is supplied - The returned jQuery object contains zero or one element for each element in the original set - The returned jQuery object contains zero or more elements for each element in the original set + The returned jQuery object contains zero or one element for each element in the original set, in document order + The returned jQuery object contains zero or more elements for each element in the original set, in reverse document order @@ -64,92 +64,114 @@ <ul id="one" class="level-1"> <li class="item-i">I</li> <li id="ii" class="item-ii">II - <ul class="level-2"> - <li class="item-a">A</li> - <li class="item-b">B - <ul class="level-3"> - <li class="item-1">1</li> - <li class="item-2">2</li> - <li class="item-3">3</li> - </ul> - </li> - <li class="item-c">C</li> - </ul> + <ul class="level-2"> + <li class="item-a">A</li> + <li class="item-b">B + <ul class="level-3"> + <li class="item-1">1</li> + <li class="item-2">2</li> + <li class="item-3">3</li> + </ul> + </li> + <li class="item-c">C</li> + </ul> </li> <li class="item-iii">III</li> </ul> - +

Suppose we perform a search for <ul> elements starting at item A:

-$('li.item-a').closest('ul')
-  .css('background-color', 'red');
-

+$( "li.item-a" ) + .closest( "ul" ) + .css( "background-color", "red" ); +

This will change the color of the level-2 <ul>, since it is the first encountered when traveling up the DOM tree.

Suppose we search for an <li> element instead:

-

$('li.item-a').closest('li')
-  .css('background-color', 'red');
-

+

+$( "li.item-a" )
+  .closest( "li" )
+  .css( "background-color", "red" );
+      

This will change the color of list item A. The .closest() method begins its search with the element itself before progressing up the DOM tree, and stops when item A matches the selector.

We can pass in a DOM element as the context within which to search for the closest element.

-

var listItemII = document.getElementById('ii');
-$('li.item-a').closest('ul', listItemII)
-  .css('background-color', 'red');
-$('li.item-a').closest('#one', listItemII)
-  .css('background-color', 'green');

+

+var listItemII = document.getElementById( "ii" );
+$( "li.item-a" )
+  .closest( "ul", listItemII )
+  .css( "background-color", "red" );
+$( "li.item-a" )
+  .closest( "#one", listItemII )
+  .css( "background-color", "green" );
+      

This will change the color of the level-2 <ul>, because it is both the first <ul> ancestor of list item A and a descendant of list item II. It will not change the color of the level-1 <ul>, however, because it is not a descendant of list item II.

Show how event delegation can be done with closest. The closest list element toggles a yellow background when it or its descendent is clicked. - + li { + margin: 3px; + padding: 3px; + background: #EEEEEE; + } + li.highlight { + background: yellow; + } +]]> + Pass a jQuery object to closest. The closest list element toggles a yellow background when it or its descendent is clicked. - + li { + margin: 3px; + padding: 3px; + background: #EEEEEE; + } + li.highlight { + background: yellow; + } +]]> + - + 1.4 - 1.8 An array or string containing a selector expression to match elements against (can also be a jQuery object). - A DOM element within which a matching element may be found. If no context is passed in then the context of the jQuery set will be used instead. + A DOM element within which a matching element may be found. Get an array of all the elements and selectors matched against the current element up through the DOM tree. -

This signature (only!) is deprecated as of jQuery 1.7 and removed in jQuery 1.8. It was primarily meant to be used internally or by plugin authors.

+
This signature (only!) is deprecated as of jQuery 1.7 and removed in jQuery 1.8. It was primarily meant to be used internally or by plugin authors.
diff --git a/entries/contains-selector.xml b/entries/contains-selector.xml index 005a05595..c471083f8 100644 --- a/entries/contains-selector.xml +++ b/entries/contains-selector.xml @@ -15,15 +15,16 @@ Finds all divs containing "John" and underlines them. +$( "div:contains('John')" ).css( "text-decoration", "underline" ); +]]> +]]> + - \ No newline at end of file + diff --git a/entries/contents.xml b/entries/contents.xml index fb0bebdca..6cfa73bae 100644 --- a/entries/contents.xml +++ b/entries/contents.xml @@ -6,42 +6,60 @@ Get the children of each element in the set of matched elements, including text and comment nodes. -

Given a jQuery object that represents a set of DOM elements, the .contents() method allows us to search throughthe immediate children of these elements in the DOM tree and construct a new jQuery object from the matching elements. The .contents() and .children() methods are similar, except that the former includes text nodes as well as HTML elements in the resulting jQuery object.

+

Given a jQuery object that represents a set of DOM elements, the .contents() method allows us to search through the immediate children of these elements in the DOM tree and construct a new jQuery object from the matching elements. The .contents() and .children() methods are similar, except that the former includes text nodes and comment nodes as well as HTML elements in the resulting jQuery object. Please note that most jQuery operations don't support text nodes and comment nodes. The few that do will have an explicit note on their API documentation page.

The .contents() method can also be used to get the content document of an iframe, if the iframe is on the same domain as the main page.

-

Consider a simple <div> with a number of text nodes, each of which is separated by two line break elements (<br />):

-

<div class="container">
-  Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed 
-  do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
-  <br /><br />
-  Ut enim ad minim veniam, quis nostrud exercitation ullamco 
+    
As of jQuery 3.2, .contents() returns contents of <template> elements as well.
+    
Consider a simple <div> with a number of text nodes, each of which is separated by two line break elements (<br>):
+    

+<div class="container">
+  Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed
+  do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  <br><br>
+  Ut enim ad minim veniam, quis nostrud exercitation ullamco
   laboris nisi ut aliquip ex ea commodo consequat.
-  <br /> <br />
-  Duis aute irure dolor in reprehenderit in voluptate velit 
+  <br><br>
+  Duis aute irure dolor in reprehenderit in voluptate velit
   esse cillum dolore eu fugiat nulla pariatur.
 </div>
-
+    

We can employ the .contents() method to help convert this blob of text into three well-formed paragraphs:

-$('.container').contents().filter(function() {
-  return this.nodeType == 3;
-})
-  .wrap('<p></p>')
-.end()
-.filter('br')
-  .remove();
-

-

This code first retrieves the contents of <div class="container"> and then filters it for text nodes, which are wrapped in paragraph tags. This is accomplished by testing the .nodeType property of the element. This DOM property holds a numeric code indicating the node's type; text nodes use the code 3. The contents are again filtered, this time for <br /> elements, and these elements are removed.

+$( ".container" ) + .contents() + .filter(function() { + return this.nodeType === 3; + }) + .wrap( "<p></p>" ) + .end() + .filter( "br" ) + .remove(); + +

This code first retrieves the contents of <div class="container"> and then filters it for text nodes, which are wrapped in paragraph tags. This is accomplished by testing the .nodeType property of the element. This DOM property holds a numeric code indicating the node's type; text nodes use the code 3. The contents are again filtered, this time for <br /> elements, and these elements are removed.

Find all the text nodes inside a paragraph and wrap them with a bold tag. - - + + - Change the background colour of links inside of an iframe. - - + Change the background color of links inside of an iframe. + + - \ No newline at end of file + + diff --git a/entries/context.xml b/entries/context.xml index bbebdb1b6..cd9c3cc41 100644 --- a/entries/context.xml +++ b/entries/context.xml @@ -1,31 +1,29 @@ - + 1.3 The DOM node context originally passed to jQuery(); if none was passed then context will likely be the document. +
+
Note: This API has been removed in jQuery 3.0.
+

The .live() method for binding event handlers uses this property to determine the root element to use for its event delegation needs.

The value of this property is typically equal to document, as this is the default context for jQuery objects if none is supplied. The context may differ if, for example, the object was created by searching within an <iframe> or XML document.

Note that the context property may only apply to the elements originally selected by jQuery(), as it is possible for the user to add elements to the collection via methods such as .add() and these may have a different context.

Determine the exact context used. - - - + + diff --git a/entries/contextmenu-shorthand.xml b/entries/contextmenu-shorthand.xml new file mode 100644 index 000000000..9b1f48736 --- /dev/null +++ b/entries/contextmenu-shorthand.xml @@ -0,0 +1,36 @@ + + + + Bind an event handler to the "contextmenu" event, or trigger that event on an element. + + 1.0 + + A function to execute each time the event is triggered. + + + + + 1.4.3 + + An object containing data that will be passed to the event handler. + + + A function to execute each time the event is triggered. + + + + + 1.0 + + +
+
This API is deprecated.
+
Instead of .contextmenu( handler ) or .contextmenu( eventData, handler ), use .on( "contextmenu", handler ) or .on( "contextmenu", eventData, handler ), respectively.
+
Instead of .contextmenu(), use .trigger( "contextmenu" ).
+
+ + + + + + diff --git a/entries/contextmenu.xml b/entries/contextmenu.xml new file mode 100644 index 000000000..63d9c179c --- /dev/null +++ b/entries/contextmenu.xml @@ -0,0 +1,105 @@ + + +Bind an event handler to the "contextmenu" event, or trigger that event on an element. + + + + Bind an event handler to the "contextmenu" event. + + 1.0 + + A function to execute each time the event is triggered. + + + + + 1.4.3 + + An object containing data that will be passed to the event handler. + + + A function to execute each time the event is triggered. + + + + +
+
This page describes the contextmenu event. For the deprecated .contextmenu() method, see .contextmenu().
+
+

The contextmenu event is sent to an element when the right button of the mouse is clicked on it, but before the context menu is displayed. In case the context menu key is pressed, the event is triggered on the html element or the currently focused element. Any HTML element can receive this event. + For example, consider the HTML:

+

+<div id="target">
+  Right-click here
+</div>
+    

+

The event handler can be bound to the <div> as follows:

+

+$( "#target" ).on( "contextmenu", function() {
+  alert( "Handler for `contextmenu` called." );
+} );
+    

+

Now right-clicking on this element displays the alert:

+

+ Handler for `contextmenu` called. +

+

To trigger the event manually, use .trigger( "contextmenu" ):

+

+$( "#target" ).trigger( "contextmenu" );
+    

+ + + To show a "Hello World!" alert box when the contextmenu event is triggered on a paragraph on the page: + + + + Right click to toggle background color. + + + + + + + + + + + + Trigger the "contextmenu" event on an element. + + 1.0 + + The string "contextmenu". + + + +

See the description for .on( "contextmenu", ... ).

+ + + + + + diff --git a/entries/css.xml b/entries/css.xml index 656869e02..85a304e82 100644 --- a/entries/css.xml +++ b/entries/css.xml @@ -1,6 +1,6 @@ - Get the value of a style property for the first element in the set of matched elements or set one or more CSS properties for every matched element. + Get the value of a computed style property for the first element in the set of matched elements or set one or more CSS properties for every matched element. @@ -9,37 +9,106 @@ A CSS property. - Get the value of a style property for the first element in the set of matched elements. + + 1.9 + + An array of one or more CSS properties. + + + Get the computed style properties for the first element in the set of matched elements. -

The .css() method is a convenient way to get a style property from the first matched element, especially in light of the different ways browsers access most of those properties (the getComputedStyle() method in standards-based browsers versus the currentStyle and runtimeStyle properties in Internet Explorer) and the different terms browsers use for certain properties. For example, Internet Explorer's DOM implementation refers to the float property as styleFloat, while W3C standards-compliant browsers refer to it as cssFloat. For consistency, you can simply use "float", and jQuery will translate it to the correct value for each browser.

-

Also, jQuery can equally interpret the CSS and DOM formatting of multiple-word properties. For example, jQuery understands and returns the correct value for both .css('background-color') and .css('backgroundColor'). Different browsers may return CSS color values that are logically but not textually equal, e.g., #FFF, #ffffff, and rgb(255,255,255).

-

Shorthand CSS properties (e.g. margin, background, border) are not supported. For example, if you want to retrieve the rendered margin, use: $(elem).css('marginTop') and $(elem).css('marginRight'), and so on.

+

The .css() method is a convenient way to get a computed style property from the first matched element, especially in light of the different ways browsers access most of those properties (the getComputedStyle() method in standards-based browsers versus the currentStyle and runtimeStyle properties in Internet Explorer prior to version 9) and the different terms browsers use for certain properties. For example, Internet Explorer's DOM implementation refers to the float property as styleFloat, while W3C standards-compliant browsers refer to it as cssFloat. For consistency, you can simply use "float", and jQuery will translate it to the correct value for each browser.

+

Also, jQuery can equally interpret the CSS and DOM formatting of multiple-word properties. For example, jQuery understands and returns the correct value for both .css( "background-color" ) and .css( "backgroundColor" ). This means mixed case has a special meaning, .css( "WiDtH" ) won't do the same as .css( "width" ), for example.

+

Note that the computed style of an element may not be the same as the value specified for that element in a style sheet. For example, computed styles of dimensions are almost always pixels, but they can be specified as em, ex, px or % in a style sheet. Different browsers may return CSS color values that are logically but not textually equal, e.g., #FFF, #ffffff, and rgb(255,255,255).

+

Retrieval of shorthand CSS properties (e.g., margin, background, border), although functional with some browsers, is not guaranteed. For example, if you want to retrieve the rendered border-width, use: $( elem ).css( "borderTopWidth" ), $( elem ).css( "borderBottomWidth" ), and so on.

+

An element should be connected to the DOM when calling .css() on it. If it isn't, jQuery may throw an error.

+

As of jQuery 1.9, passing an array of style properties to .css() will result in an object of property-value pairs. For example, to retrieve all four rendered border-width values, you could use $( elem ).css([ "borderTopWidth", "borderRightWidth", "borderBottomWidth", "borderLeftWidth" ]).

+

As of jQuery 3.2, CSS Custom Properties (also called CSS Variables) are supported: $( "p" ).css( "--custom-property" ). Note that you need to provide the property name as-is, camelCasing it won't work as it does for regular CSS properties.

- To access the background color of a clicked div. + Get the background color of a clicked div. + div { + width: 60px; + height: 60px; + margin: 5px; + float: left; + } +]]> +
+]]> + + + + Get the width, height, text color, and background color of a clicked div. + " ) ); +}); +]]> + + + + + @@ -47,8 +116,10 @@ div { width:60px; height:60px; margin:5px; float:left; } A CSS property name. - + A value to set for the property. + + @@ -56,73 +127,105 @@ div { width:60px; height:60px; margin:5px; float:left; } A CSS property name. - + A function returning the value to set. this is the current element. Receives the index position of the element in the set and the old value as arguments. + + + + + + 1.0 - A map of property-value pairs to set. + An object of property-value pairs to set. Set one or more CSS properties for the set of matched elements. -

As with the .prop() method, the .css() method makes setting properties of elements quick and easy. This method can take either a property name and value as separate parameters, or a single map of key-value pairs (JavaScript object notation).

-

Also, jQuery can equally interpret the CSS and DOM formatting of multiple-word properties. For example, jQuery understands and returns the correct value for both .css({'background-color': '#ffe', 'border-left': '5px solid #ccc'}) and .css({backgroundColor: '#ffe', borderLeft: '5px solid #ccc'}). Notice that with the DOM notation, quotation marks around the property names are optional, but with CSS notation they're required due to the hyphen in the name.

-

When using .css() as a setter, jQuery modifies the element's style property. For example, $('#mydiv').css('color', 'green') is equivalent to document.getElementById('mydiv').style.color = 'green'. Setting the value of a style property to an empty string — e.g. $('#mydiv').css('color', '') — removes that property from an element if it has already been directly applied, whether in the HTML style attribute, through jQuery's .css() method, or through direct DOM manipulation of the style property. It does not, however, remove a style that has been applied with a CSS rule in a stylesheet or <style> element. Warning: one notable exception is that, for IE 8 and below, removing a shorthand property such as border or background> will remove that style entirely from the element, regardless of what is set in a stylesheet or <style> element.

+

As with the .prop() method, the .css() method makes setting properties of elements quick and easy. This method can take either a property name and value as separate parameters, or a single object of key-value pairs.

+

Also, jQuery can equally interpret the CSS and DOM formatting of multiple-word properties. For example, jQuery understands and returns the correct value for both .css({ "background-color": "#ffe", "border-left": "5px solid #ccc" }) and .css({backgroundColor: "#ffe", borderLeft: "5px solid #ccc" }). Notice that with the DOM notation, quotation marks around the property names are optional, but with CSS notation they're required due to the hyphen in the name.

+

In jQuery 3.x or older, when a number is passed as the value, jQuery will convert it to a string and add px to the end of that string. However, there are exceptions. px is not added to keys of jQuery.cssNumber If the property requires units other than px, convert the value to a string and add the appropriate units before calling the method.

+

In jQuery 4.0 or newer, when a number is passed as the value, jQuery will only convert it to a string and add px to the end of that string for a limited set of properties - mostly related to width, height, border, margin & padding; the full list:

+
+
• setting the element position: top, right, bottom, left
+
• setting the element dimensions: width, height, min-width, min-height, max-width, max-height
+
• padding-related: padding, padding-top, padding-right, padding-bottom, padding-left
+
• margin-related: margin, margin-top, margin-right, margin-bottom, margin-left
+
• border-related: border, border-width, border-top, border-top-width, border-right, border-right-width, border-bottom, border-bottom-width, border-left, border-left-width
+
+

When using .css() as a setter, jQuery modifies the element's style property. For example, $( "#mydiv" ).css( "color", "green" ) is equivalent to document.getElementById( "mydiv" ).style.color = "green". Setting the value of a style property to an empty string — e.g. $( "#mydiv" ).css( "color", "" ) — removes that property from an element if it has already been directly applied, whether in the HTML style attribute, through jQuery's .css() method, or through direct DOM manipulation of the style property. As a consequence, the element's style for that property will be restored to whatever value was applied. So, this method can be used to cancel any style modification you have previously performed. It does not, however, remove a style that has been applied with a CSS rule in a stylesheet or <style> element. Warning: one notable exception is that, for IE 8 and below, removing a shorthand property such as border or background will remove that style entirely from the element, regardless of what is set in a stylesheet or <style> element.

+

Note: .css() doesn't support !important declarations. So, the statement $( "p" ).css( "color", "red !important" ) does not turn the color of all paragraphs in the page to red as of jQuery 3.6.0. Do not depend on that not working, though, as a future version of jQuery may add support for such declarations. It's strongly advised to use classes instead; otherwise use a jQuery plugin.

+

As of jQuery 1.8, the .css() setter will automatically take care of prefixing the property name. For example, take .css( "user-select", "none" ) in Chrome/Safari will set it as -webkit-user-select, Firefox will use -moz-user-select, and IE10 will use -ms-user-select.

As of jQuery 1.6, .css() accepts relative values similar to .animate(). Relative values are a string starting with += or -= to increment or decrement the current value. For example, if an element's padding-left was 10px, .css( "padding-left", "+=15" ) would result in a total padding-left of 25px.

As of jQuery 1.4, .css() allows us to pass a function as the property value:

-

$('div.example').css('width', function(index) {
+      

+$( "div.example" ).css( "width", function( index ) {
   return index * 50;
-});
+});
+      

This example sets the widths of the matched elements to incrementally larger values.

-

Note: If nothing is returned in the setter function (ie. function(index, style){}), or if undefined is returned, the current value is not changed. This is useful for selectively setting values only when certain criteria are met.

+

Note: If nothing is returned in the setter function (ie. function( index, style ){} ), or if undefined is returned, the current value is not changed. This is useful for selectively setting values only when certain criteria are met.

+

As of jQuery 3.2, CSS Custom Properties (also called CSS Variables) are supported: $( "p" ).css( "--custom-property", "value" ). Note that you need to provide the property name as-is, camelCasing it won't work as it does for regular CSS properties.

- To change the color of any paragraph to red on mouseover event. + Change the color of any paragraph to red on mouseover event. + p { + color: blue; + width: 200px; + font-size: 14px; + } +]]> +]]> - Increase the width of #box by 200 pixels + Increase the width of #box by 200 pixels the first time it is clicked. + #box { + background: black; + color: snow; + width: 100px; + padding: 10px; + } +]]> +
Click me to grow
+]]> - To highlight a clicked word in the paragraph. + Highlight a clicked word in the paragraph. + p { + color: blue; + font-weight: bold; + cursor: pointer; + } +]]> +
+]]> - To set the color of all paragraphs to red and background to blue: + Change the font weight and background color on mouseenter and mouseleave. - Increase the size of a div when you click it: + Increase the size of a div when you click it. + div { + width: 20px; + height: 15px; + background-color: #f33; + } +]]> + + diff --git a/entries/data.xml b/entries/data.xml index 21d5fc278..d998d38c7 100644 --- a/entries/data.xml +++ b/entries/data.xml @@ -8,8 +8,8 @@ A string naming the piece of data to set. - - The new data value; it can be any Javascript type including Array or Object. + + The new data value; this can be any Javascript type except undefined. @@ -21,36 +21,44 @@ Store arbitrary data associated with the matched elements.

The .data() method allows us to attach data of any type to DOM elements in a way that is safe from circular references and therefore from memory leaks.

-

We can set several distinct values for a single element and retrieve them later:

+

We can set several distinct values for a single element and retrieve them later:

-$('body').data('foo', 52);
-$('body').data('bar', { myType: 'test', count: 40 });
-
-$('body').data('foo'); // 52
-$('body').data(); // {foo: 52, bar: { myType: 'test', count: 40 }}
-

-

In jQuery 1.4.3 setting an element's data object with .data(obj) extends the data previously stored with that element. jQuery itself uses the .data() method to save information under the names 'events' and 'handle', and also reserves any data name starting with an underscore ('_') for internal use.

-

Prior to jQuery 1.4.3 (starting in jQuery 1.4) the .data() method completely replaced all data, instead of just extending the data object. If you are using third-party plugins it may not be advisable to completely replace the element's data object, since plugins may have also set data.

+$( "body" ).data( "foo", 52 ); +$( "body" ).data( "bar", { isManual: true } ); +$( "body" ).data( { baz: [ 1, 2, 3 ] } ); +$( "body" ).data( "foo" ); // 52 +$( "body" ).data(); // { foo: 52, bar: { isManual: true }, baz: [ 1, 2, 3 ] } + +

Using the data() method to update data does not affect attributes in the DOM. To set a data-* attribute value, use attr.

+

Prior to jQuery 1.4.3, .data( obj ) completely replaced all data. Since jQuery 1.4.3, data is instead extended by shallow merge.

+

Since jQuery 3, every two-character sequence of "-" (U+002D) followed by a lowercase ASCII letter in a key is replaced by the uppercase version of the letter, in alignment with the HTML dataset API. A statement like $( "body" ).data( { "my-name": "aValue" } ).data(); will return { myName: "aValue" }.

Due to the way browsers interact with plugins and external code, the .data() method cannot be used on <object> (unless it's a Flash plugin), <applet> or <embed> elements.

+ Store then retrieve a value from the div element. - + div { + color: blue; + } + span { + color: red; + } +]]> + @@ -68,82 +76,90 @@ $("span:last").text($("div").data("test").last); 1.4 - Return the value at the named data store for the first element in the jQuery collection, as set by data(name, value) or by an HTML5 data-* attribute. + Return arbitrary data associated with the first element in the jQuery collection, as set by data() or by an HTML5 data-* attribute. -

The .data() method allows us to attach data of any type to DOM elements in a way that is safe from circular references and therefore from memory leaks. We can retrieve several distinct values for a single element one at a time, or as a set:

+

The .data() method allows us to read data previously associated with DOM elements. We can retrieve several distinct values for a single element one at a time, or as a set:

-alert($('body').data('foo'));
-alert($('body').data());
-

-

The above lines alert the data values that were set on the body element. If no data at all was set on that element, undefined is returned.

-

-alert( $("body").data("foo")); //undefined
-$("body").data("bar", "foobar");
-alert( $("body").data("bar")); //foobar
-

+var elem = document.createElement( "span" ); +$( elem ).data( "foo" ); // undefined +$( elem ).data(); // {} + +$( elem ).data( "foo", 42 ); +$( elem ).data( "foo" ); // 42 +$( elem ).data(); // { foo: 42 } + +

Calling .data() with no parameters returns a JavaScript object containing each stored value as a property. The object can be used directly to get data values (but note that property names originally containing dashes will have been modified as described below).

+

Since jQuery 3, every two-character sequence of "-" (U+002D) followed by a lowercase ASCII letter in a key is replaced by the uppercase version of the letter, in alignment with the HTML dataset API. A statement like $( "body" ).data( { "my-name": "aValue" } ).data(); will return { myName: "aValue" }.

- HTML5 data-* Attributes + HTML5 data-* Attributes

-

As of jQuery 1.4.3 HTML 5 data- attributes will be automatically pulled in to jQuery's data object. The treatment of attributes with embedded dashes was changed in jQuery 1.6 to conform to the W3C HTML5 specification.

+

Since jQuery 1.4.3, data-* attributes are used to initialize jQuery data. An element's data-* attributes are retrieved the first time the data() method is invoked upon it, and then are no longer accessed or mutated (all values are stored internally by jQuery).

+

Every attempt is made to convert the attribute's string value to a JavaScript value (this includes booleans, numbers, objects, arrays, and null). A string is only converted to a number if doing so doesn't change its representation (for example, the string "100" is converted to the number 100, but "1E02" and "100.000" are left as strings because their numeric value of 100 serializes to "100"). When a string starts with '{' or '[', then jQuery.parseJSON is used to parse it; it must follow valid JSON syntax including quoted property names. A string not parseable as a JavaScript value is not converted.

+

To retrieve a data-* attribute value as an unconverted string, use the attr() method.

+

Since jQuery 1.6, dashes in data-* attribute names have been processed in alignment with the HTML dataset API.

For example, given the following HTML:

<div data-role="page" data-last-value="43" data-hidden="true" data-options='{"name":"John"}'></div>

-

All of the following jQuery code will work.

-

$("div").data("role") === "page";
-$("div").data("lastValue") === 43;
-$("div").data("hidden") === true;
-$("div").data("options").name === "John";

-

Every attempt is made to convert the string to a JavaScript value (this includes booleans, numbers, objects, arrays, and null) otherwise it is left as a string. To retrieve the value's attribute as a string without any attempt to convert it, use the attr() method. When the data attribute is an object (starts with '{') or array (starts with '[') then jQuery.parseJSON is used to parse the string; it must follow valid JSON syntax including quoted property names. The data- attributes are pulled in the first time the data property is accessed and then are no longer accessed or mutated (all data values are then stored internally in jQuery).

-

Calling .data() with no parameters retrieves all of the values as a JavaScript object. This object can be safely cached in a variable as long as a new object is not set with .data(obj). Using the object directly to get or set values is faster than making individual calls to .data() to get or set each value:

+

The following comparisons are all true:

-var mydata = $("#mydiv").data();
-if ( mydata.count < 9 ) {
-    mydata.count = 43;
-    mydata.status = "embiggened";
-}
-

+$( "div" ).data( "role" ) === "page"; +$( "div" ).data( "lastValue" ) === 43; +$( "div" ).data( "hidden" ) === true; +$( "div" ).data( "options" ).name === "John"; + Get the data named "blah" stored at for an element. - + div { + margin: 5px; + background: yellow; + } + button { + margin: 5px; + font-size: 14px; + } + p { + margin: 5px; + color: blue; + } + span { + color: red; + } +]]> + diff --git a/entries/dblclick-shorthand.xml b/entries/dblclick-shorthand.xml new file mode 100644 index 000000000..ad4c1887b --- /dev/null +++ b/entries/dblclick-shorthand.xml @@ -0,0 +1,36 @@ + + + + Bind an event handler to the "dblclick" event, or trigger that event on an element. + + 1.0 + + A function to execute each time the event is triggered. + + + + + 1.4.3 + + An object containing data that will be passed to the event handler. + + + A function to execute each time the event is triggered. + + + + + 1.0 + + +
+
This API is deprecated.
+
Instead of .dblclick( handler ) or .dblclick( eventData, handler ), use .on( "dblclick", handler ) or .on( "dblclick", eventData, handler ), respectively.
+
Instead of .dblclick(), use .trigger( "dblclick" ).
+
+ + + + + + diff --git a/entries/dblclick.xml b/entries/dblclick.xml index 23a3e9f17..9c4cf59a0 100644 --- a/entries/dblclick.xml +++ b/entries/dblclick.xml @@ -1,51 +1,58 @@ - - - Bind an event handler to the "dblclick" JavaScript event, or trigger that event on an element. + + +Bind an event handler to the "dblclick" event, or trigger that event on an element. + + + Bind an event handler to the "dblclick" event. - 1.0 - - A function to execute each time the event is triggered. + 1.7 + + The string "dblclick". - - - 1.4.3 - - A map of data that will be passed to the event handler. + + An object containing data that will be passed to the event handler. - + A function to execute each time the event is triggered. + - - 1.0 - -

This method is a shortcut for .bind('dblclick', handler) in the first two variations, and .trigger('dblclick') in the third. - The dblclick event is sent to an element when the element is double-clicked. Any HTML element can receive this event. +

+
This page describes the dblclick event. For the deprecated .dblclick() method, see .dblclick().
+
+

The dblclick event is sent to an element when the element is double-clicked. Any HTML element can receive this event. For example, consider the HTML:

-

<div id="target">
+    

+<div id="target">
   Double-click here
 </div>
 <div id="other">
   Trigger the handler
-</div>
-    

+</div>
+    

+

-

+ +

The event handler can be bound to any <div>:

-

$('#target').dblclick(function() {
-  alert('Handler for .dblclick() called.');
-});

+

+$( "#target" ).on( "dblclick", function() {
+  alert( "Handler for `dblclick` called." );
+} );
+    

Now double-clicking on this element displays the alert:

- Handler for .dblclick() called. + Handler for `dblclick` called.

-

To trigger the event manually, apply .dblclick() without an argument:

-

$('#other').click(function() {
-  $('#target').dblclick();
-});

-

After this code executes, (single) clicks on Trigger the handler will also alert the message.

+

To trigger the event manually, call .trigger( "dblclick" ):

+

+$( "#other" ).on( "click", function() {
+  $( "#target" ).trigger( "dblclick" );
+} );
+    

+

After this code executes, (single) clicks on Trigger the handler will also alert the message.

The dblclick event is only triggered after this exact series of events:

• The mouse button is depressed while the pointer is inside the element.
@@ -57,28 +64,57 @@
- To bind a "Hello World!" alert box the dblclick event on every paragraph on the page: - + To bind a "Hello World!" alert box to the dblclick event on every paragraph on the page: + Double click to toggle background color. - + div.dbl { + background: yellow; + color: black; + } +]]> + - - \ No newline at end of file + + + + + + Trigger the "dblclick" event on an element. + + 1.0 + + The string "dblclick". + + + +

See the description for .on( "dblclick", ... ).

+ + + + + + diff --git a/entries/deferred.always.xml b/entries/deferred.always.xml index a7269094c..30e921936 100644 --- a/entries/deferred.always.xml +++ b/entries/deferred.always.xml @@ -17,15 +17,16 @@ Add handlers to be called when the Deferred object is either resolved or rejected.

The argument can be either a single function or an array of functions. When the Deferred is resolved or rejected, the alwaysCallbacks are called. Since deferred.always() returns the Deferred object, other methods of the Deferred object can be chained to this one, including additional .always() methods. When the Deferred is resolved or rejected, callbacks are executed in the order they were added, using the arguments provided to the resolve, reject, resolveWith or rejectWith method calls. For more information, see the documentation for Deferred object.

+

Note: The deferred.always() method receives the arguments that were used to .resolve() or .reject() the Deferred object, which are often very different. For this reason, it's best to use it only for actions that do not require inspecting the arguments. In all other cases, use explicit .done() or .fail() handlers since the arguments will have well-known orders.

- Since the jQuery.get() method returns a jqXHR object, which is derived from a Deferred object, we can attach a callback for both success and error using the deferred.always() method. + Since the jQuery.get() method returns a jqXHR object, which is derived from a Deferred object, we can attach a callback for both success and error using the deferred.always() method. - \ No newline at end of file + diff --git a/entries/deferred.catch.xml b/entries/deferred.catch.xml new file mode 100644 index 000000000..e6e3d95aa --- /dev/null +++ b/entries/deferred.catch.xml @@ -0,0 +1,31 @@ + + + + + 3.0 + + + A function that is called when the Deferred is rejected. + + + + Add handlers to be called when the Deferred object is rejected. + + +

deferred.catch( fn ) is an alias to deferred.then( null, fn ). Read its page for more information.

+ + + Since the jQuery.get method returns a jqXHR object, which is derived from a Deferred object, we can add rejection handlers using the .catch method. + + + + + diff --git a/entries/deferred.done.xml b/entries/deferred.done.xml index e4db44176..be4787a08 100644 --- a/entries/deferred.done.xml +++ b/entries/deferred.done.xml @@ -19,47 +19,47 @@

The deferred.done() method accepts one or more arguments, all of which can be either a single function or an array of functions. When the Deferred is resolved, the doneCallbacks are called. Callbacks are executed in the order they were added. Since deferred.done() returns the deferred object, other methods of the deferred object can be chained to this one, including additional .done() methods. When the Deferred is resolved, doneCallbacks are executed using the arguments provided to the resolve or resolveWith method call in the order they were added. For more information, see the documentation for Deferred object.

- Since the jQuery.get method returns a jqXHR object, which is derived from a Deferred object, we can attach a success callback using the .done() method. + Since the jQuery.get method returns a jqXHR object, which is derived from a Deferred object, we can attach a success callback using the .done() method. Resolve a Deferred object when the user clicks a button, triggering a number of callback functions: diff --git a/entries/deferred.fail.xml b/entries/deferred.fail.xml index 61d30d597..6af2ec2b9 100644 --- a/entries/deferred.fail.xml +++ b/entries/deferred.fail.xml @@ -16,16 +16,20 @@ Add handlers to be called when the Deferred object is rejected. -

The deferred.fail() method accepts one or more arguments, all of which can be either a single function or an array of functions. When the Deferred is rejected, the failCallbacks are called. Callbacks are executed in the order they were added. Since deferred.fail() returns the deferred object, other methods of the deferred object can be chained to this one, including additional deferred.fail() methods. The failCallbacks are executed using the arguments provided to the deferred.reject() or deferred.rejectWith() method call in the order they were added. For more information, see the documentation for Deferred object.

+

The deferred.fail() method accepts one or more arguments, all of which can be either a single function or an array of functions. When the Deferred is rejected, the failCallbacks are called. Callbacks are executed in the order they were added. Since deferred.fail() returns the deferred object, other methods of the deferred object can be chained to this one, including additional deferred.fail() methods. The failCallbacks are executed using the arguments provided to the deferred.reject() or deferred.rejectWith() method call in the order they were added. For more information, see the documentation for Deferred object.

- Since the jQuery.get method returns a jqXHR object, which is derived from a Deferred, you can attach a success and failure callback using the deferred.done() and deferred.fail() methods. + Since the jQuery.get method returns a jqXHR object, which is derived from a Deferred, you can attach a success and failure callback using the deferred.done() and deferred.fail() methods. - \ No newline at end of file + diff --git a/entries/deferred.isRejected.xml b/entries/deferred.isRejected.xml index eb2c22396..a391f7795 100644 --- a/entries/deferred.isRejected.xml +++ b/entries/deferred.isRejected.xml @@ -1,15 +1,19 @@ - + 1.5 Determine whether a Deferred object has been rejected. -

As of jQuery 1.7 this API has been deprecated; please use deferred.state() instead.

-

Returns true if the Deferred object is in the rejected state, meaning that either deferred.reject() or deferred.rejectWith() has been called for the object and the failCallbacks have been called (or are in the process of being called).

-

Note that a Deferred object can be in one of three states: pending, resolved, or rejected; use deferred.isResolved() to determine whether the Deferred object is in the resolved state. These methods are primarily useful for debugging, for example to determine whether a Deferred has already been resolved even though you are inside code that intended to reject it.

+
+
Note: This API has been removed in jQuery 1.8; please use deferred.state() instead.
+
+

Returns true if the Deferred object is in the rejected state, meaning that either deferred.reject() or deferred.rejectWith() has been called for the object and the failCallbacks have been called (or are in the process of being called).

+

Note that a Deferred object can be in one of three states: pending, resolved, or rejected; use deferred.isResolved() to determine whether the Deferred object is in the resolved state. These methods are primarily useful for debugging, for example to determine whether a Deferred has already been resolved even though you are inside code that intended to reject it.

- \ No newline at end of file + + + diff --git a/entries/deferred.isResolved.xml b/entries/deferred.isResolved.xml index fa58afe2b..9c046e5ae 100644 --- a/entries/deferred.isResolved.xml +++ b/entries/deferred.isResolved.xml @@ -6,10 +6,14 @@ Determine whether a Deferred object has been resolved. -

This API is deprecated as of jQuery 1.7 and removed as of jQuery 1.8; please use deferred.state() instead.

-

Returns true if the Deferred object is in the resolved state, meaning that either deferred.resolve() or deferred.resolveWith() has been called for the object and the doneCallbacks have been called (or are in the process of being called).

-

Note that a Deferred object can be in one of three states: pending, resolved, or rejected; use deferred.isRejected() to determine whether the Deferred object is in the rejected state. These methods are primarily useful for debugging, for example to determine whether a Deferred has already been resolved even though you are inside code that intended to reject it.

+
+
Note: This API has been removed in jQuery 1.8; please use deferred.state() instead.
+
+

Returns true if the Deferred object is in the resolved state, meaning that either deferred.resolve() or deferred.resolveWith() has been called for the object and the doneCallbacks have been called (or are in the process of being called).

+

Note that a Deferred object can be in one of three states: pending, resolved, or rejected; use deferred.isRejected() to determine whether the Deferred object is in the rejected state. These methods are primarily useful for debugging, for example to determine whether a Deferred has already been resolved even though you are inside code that intended to reject it.

+ + diff --git a/entries/deferred.notify.xml b/entries/deferred.notify.xml index cbaf291cb..1af2435d1 100644 --- a/entries/deferred.notify.xml +++ b/entries/deferred.notify.xml @@ -12,7 +12,7 @@ Call the progressCallbacks on a Deferred object with the given args.

Normally, only the creator of a Deferred should call this method; you can prevent other code from changing the Deferred's state or reporting status by returning a restricted Promise object through deferred.promise().

-

When deferred.notify is called, any progressCallbacks added by deferred.then or deferred.progress are called. Callbacks are executed in the order they were added. Each callback is passed the args from the .notify(). Any calls to .notify() after a Deferred is resolved or rejected (or any progressCallbacks added after that) are ignored. For more information, see the documentation for Deferred object.

+

When deferred.notify is called, any progressCallbacks added by deferred.then or deferred.progress are called. Callbacks are executed in the order they were added. Each callback is passed the args from the .notify(). Any calls to .notify() after a Deferred is resolved or rejected (or any progressCallbacks added after that) are ignored. For more information, see the documentation for Deferred object.

diff --git a/entries/deferred.notifyWith.xml b/entries/deferred.notifyWith.xml index 84799f4bf..add312b8a 100644 --- a/entries/deferred.notifyWith.xml +++ b/entries/deferred.notifyWith.xml @@ -8,16 +8,16 @@ Context passed to the progressCallbacks as the this object. - + - Optional arguments that are passed to the progressCallbacks. + An optional array of arguments that are passed to the progressCallbacks. Call the progressCallbacks on a Deferred object with the given context and args.

Normally, only the creator of a Deferred should call this method; you can prevent other code from changing the Deferred's state or reporting status by returning a restricted Promise object through deferred.promise().

-

When deferred.notifyWith is called, any progressCallbacks added by deferred.then or deferred.progress are called. Callbacks are executed in the order they were added. Each callback is passed the args from the .notifyWith(). Any calls to .notifyWith() after a Deferred is resolved or rejected (or any progressCallbacks added after that) are ignored. For more information, see the documentation for Deferred object.

+

When deferred.notifyWith is called, any progressCallbacks added by deferred.then or deferred.progress are called. Callbacks are executed in the order they were added. Each callback is passed the args from the .notifyWith(). Any calls to .notifyWith() after a Deferred is resolved or rejected (or any progressCallbacks added after that) are ignored. For more information, see the documentation for Deferred object.

diff --git a/entries/deferred.pipe.xml b/entries/deferred.pipe.xml index a5151963a..a74f9dac6 100644 --- a/entries/deferred.pipe.xml +++ b/entries/deferred.pipe.xml @@ -1,5 +1,5 @@ - + 1.6 @@ -34,15 +34,18 @@ Utility method to filter and/or chain Deferreds. +
+
Deprecation Notice:As of jQuery 1.8, the deferred.pipe() method is deprecated. The deferred.then() method, which replaces it, should be used instead.
+

The deferred.pipe() method returns a new promise that filters the status and values of a deferred through a function. The doneFilter and failFilter functions filter the original deferred's resolved / rejected status and values. As of jQuery 1.7, the method also accepts a progressFilter function to filter any calls to the original deferred's notify or notifyWith methods. These filter functions can return a new value to be passed along to the piped promise's done() or fail() callbacks, or they can return another observable object (Deferred, Promise, etc) which will pass its resolved / rejected status and values to the piped promise's callbacks. If the filter function used is null, or not specified, the piped promise will be resolved or rejected with the same values as the original.

Filter resolve value: - \ No newline at end of file + + + diff --git a/entries/deferred.progress.xml b/entries/deferred.progress.xml index ce956eefa..87189af93 100644 --- a/entries/deferred.progress.xml +++ b/entries/deferred.progress.xml @@ -3,15 +3,24 @@ 1.7 - + + + - A function, or array of functions, that is called when the Deferred generates progress notifications. + A function, or array of functions, to be called when the Deferred generates progress notifications. + + + + + + + Optional additional functions, or arrays of functions, to be called when the Deferred generates progress notifications. Add handlers to be called when the Deferred object generates progress notifications. -

The argument can be either a single function or an array of functions. When the Deferred generates progress notifications by calling notify or notifyWith, the progressCallbacks are called. Since deferred.progress() returns the Deferred object, other methods of the Deferred object can be chained to this one. When the Deferred is resolved or rejected, progress callbacks will no longer be called, with the exception that any progressCallbacks added after the Deferred enters the resolved or rejected state are executed immediately when they are added, using the arguments that were passed to the .notify() or notifyWith() call. For more information, see the documentation jQuery.Deferred().

+

The deferred.progress() method accepts one or more arguments, all of which can be either a single function or an array of functions. When the Deferred generates progress notifications by calling notify or notifyWith, the progressCallbacks are called. Since deferred.progress() returns the Deferred object, other methods of the Deferred object can be chained to this one. When the Deferred is resolved or rejected, progress callbacks will no longer be called, with the exception that any progressCallbacks added after the Deferred enters the resolved or rejected state are executed immediately when they are added, using the arguments that were passed to the .notify() or notifyWith() call. For more information, see the documentation for jQuery.Deferred().

diff --git a/entries/deferred.promise.xml b/entries/deferred.promise.xml index bb49dd239..db6550bd9 100644 --- a/entries/deferred.promise.xml +++ b/entries/deferred.promise.xml @@ -9,7 +9,7 @@ Return a Deferred's Promise object. -

The deferred.promise() method allows an asynchronous function to prevent other code from interfering with the progress or status of its internal request. The Promise exposes only the Deferred methods needed to attach additional handlers or determine the state (then, done, fail, always, pipe, progress, and state), but not ones that change the state (resolve, reject, notify, resolveWith, rejectWith, and notifyWith).

+

The deferred.promise() method allows an asynchronous function to prevent other code from interfering with the progress or status of its internal request. The Promise exposes only the Deferred methods needed to attach additional handlers or determine the state (then, done, fail, always, pipe, progress, state and promise), but not ones that change the state (resolve, reject, notify, resolveWith, rejectWith, and notifyWith).

If target is provided, deferred.promise() will attach the methods onto it and then return this object rather than create a new one. This can be useful to attach the Promise behavior to an object that already exists.

If you are creating a Deferred, keep a reference to the Deferred so that it can be resolved or rejected at some point. Return only the Promise object via deferred.promise() so other code can register callbacks or inspect the current state.

For more information, see the documentation for Deferred object.

@@ -17,42 +17,42 @@ Create a Deferred and set two timer-based functions to either resolve or reject the Deferred after a random interval. Whichever one fires first "wins" and will call one of the callbacks. The second timeout has no effect since the Deferred is already complete (in a resolved or rejected state) from the first timeout action. Also set a timer-based progress notification function, and call a progress handler that adds "working..." to the document body. @@ -61,12 +61,12 @@ $.when( asyncEvent() ).then( - \ No newline at end of file + diff --git a/entries/deferred.reject.xml b/entries/deferred.reject.xml index 0c458dc50..25e27e625 100644 --- a/entries/deferred.reject.xml +++ b/entries/deferred.reject.xml @@ -3,7 +3,7 @@ 1.5 - + Optional arguments that are passed to the failCallbacks. @@ -11,8 +11,8 @@ Reject a Deferred object and call any failCallbacks with the given args. -

Normally, only the creator of a Deferred should call this method; you can prevent other code from changing the Deferred's state by returning a restricted Promise object through deferred.promise().

-

When the Deferred is rejected, any failCallbacks added by deferred.then or deferred.fail are called. Callbacks are executed in the order they were added. Each callback is passed the args from the deferred.reject() call. Any failCallbacks added after the Deferred enters the rejected state are executed immediately when they are added, using the arguments that were passed to the .reject() call. For more information, see the documentation for Deferred object.

+

Normally, only the creator of a Deferred should call this method; you can prevent other code from changing the Deferred's state by returning a restricted Promise object through deferred.promise().

+

When the Deferred is rejected, any failCallbacks added by deferred.then() or deferred.fail() are called. Callbacks are executed in the order they were added. Each callback is passed the args from the deferred.reject() call. Any failCallbacks added after the Deferred enters the rejected state are executed immediately when they are added, using the arguments that were passed to the deferred.reject() call. For more information, see the documentation for jQuery.Deferred().

diff --git a/entries/deferred.rejectWith.xml b/entries/deferred.rejectWith.xml index 0b94ccacc..31e272d6e 100644 --- a/entries/deferred.rejectWith.xml +++ b/entries/deferred.rejectWith.xml @@ -16,7 +16,7 @@ Reject a Deferred object and call any failCallbacks with the given context and args. -

Normally, only the creator of a Deferred should call this method; you can prevent other code from changing the Deferred's state by returning a restricted Promise object through deferred.promise().

+

Normally, only the creator of a Deferred should call this method; you can prevent other code from changing the Deferred's state by returning a restricted Promise object through deferred.promise().

When the Deferred is rejected, any failCallbacks added by deferred.then or deferred.fail are called. Callbacks are executed in the order they were added. Each callback is passed the args from the deferred.reject() call. Any failCallbacks added after the Deferred enters the rejected state are executed immediately when they are added, using the arguments that were passed to the .reject() call. For more information, see the documentation for Deferred object.

diff --git a/entries/deferred.resolve.xml b/entries/deferred.resolve.xml index edeb418c1..3aea35994 100644 --- a/entries/deferred.resolve.xml +++ b/entries/deferred.resolve.xml @@ -3,7 +3,7 @@ 1.5 - + Optional arguments that are passed to the doneCallbacks. @@ -11,7 +11,8 @@ Resolve a Deferred object and call any doneCallbacks with the given args. -

When the Deferred is resolved, any doneCallbacks added by deferred.then or deferred.done are called. Callbacks are executed in the order they were added. Each callback is passed the args from the .resolve(). Any doneCallbacks added after the Deferred enters the resolved state are executed immediately when they are added, using the arguments that were passed to the .resolve() call. For more information, see the documentation for Deferred object.

+

Normally, only the creator of a Deferred should call this method; you can prevent other code from changing the Deferred's state by returning a restricted Promise object through deferred.promise().

+

When the Deferred is resolved, any doneCallbacks added by deferred.then() or deferred.done() are called. Callbacks are executed in the order they were added. Each callback is passed the args from the deferred.resolve(). Any doneCallbacks added after the Deferred enters the resolved state are executed immediately when they are added, using the arguments that were passed to the deferred.resolve() call. For more information, see the documentation for jQuery.Deferred().

diff --git a/entries/deferred.resolveWith.xml b/entries/deferred.resolveWith.xml index da3e456d4..a6daf6ca2 100644 --- a/entries/deferred.resolveWith.xml +++ b/entries/deferred.resolveWith.xml @@ -16,7 +16,7 @@ Resolve a Deferred object and call any doneCallbacks with the given context and args. -

Normally, only the creator of a Deferred should call this method; you can prevent other code from changing the Deferred's state by returning a restricted Promise object through deferred.promise().

+

Normally, only the creator of a Deferred should call this method; you can prevent other code from changing the Deferred's state by returning a restricted Promise object through deferred.promise().

When the Deferred is resolved, any doneCallbacks added by deferred.then or deferred.done are called. Callbacks are executed in the order they were added. Each callback is passed the args from the .resolve(). Any doneCallbacks added after the Deferred enters the resolved state are executed immediately when they are added, using the arguments that were passed to the .resolve() call. For more information, see the documentation for Deferred object.

diff --git a/entries/deferred.state.xml b/entries/deferred.state.xml index 8a2350f6f..be9cde062 100644 --- a/entries/deferred.state.xml +++ b/entries/deferred.state.xml @@ -9,11 +9,11 @@

The deferred.state() method returns a string representing the current state of the Deferred object. The Deferred object can be in one of three states:

• "pending": The Deferred object is not yet in a completed state (neither "rejected" nor "resolved").
-
• "resolved": The Deferred object is in the resolved state, meaning that either deferred.resolve() or deferred.resolveWith() has been called for the object and the doneCallbacks have been called (or are in the process of being called).
-
• "rejected": The Deferred object is in the rejected state, meaning that either deferred.reject() or deferred.rejectWith() has been called for the object and the failCallbacks have been called (or are in the process of being called).
+
• "resolved": The Deferred object is in the resolved state, meaning that either deferred.resolve() or deferred.resolveWith() has been called for the object and the doneCallbacks have been called (or are in the process of being called).
+
• "rejected": The Deferred object is in the rejected state, meaning that either deferred.reject() or deferred.rejectWith() has been called for the object and the failCallbacks have been called (or are in the process of being called).

This method is primarily useful for debugging to determine, for example, whether a Deferred has already been resolved even though you are inside code that intended to reject it.

- \ No newline at end of file + diff --git a/entries/deferred.then.xml b/entries/deferred.then.xml index 1d3f8c9f7..ec8b2b051 100644 --- a/entries/deferred.then.xml +++ b/entries/deferred.then.xml @@ -1,8 +1,27 @@ + + 1.8 + + + A function that is called when the Deferred is resolved. + + + + + An optional function that is called when the Deferred is rejected. + + + + + An optional function that is called when progress notifications are sent to the Deferred. + + + 1.5 + 1.8 A function, or array of functions, called when the Deferred is resolved. @@ -16,6 +35,7 @@ 1.7 + 1.8 A function, or array of functions, called when the Deferred is resolved. @@ -32,10 +52,14 @@ - Add handlers to be called when the Deferred object is resolved or rejected. + Add handlers to be called when the Deferred object is resolved, rejected, or still in progress. + -

All three arguments (including progressCallbacks, as of jQuery 1.7) can be either a single function or an array of functions. The arguments can also be null if no callback of that type is desired. Alternatively, use .done(), .fail() or .progress() to set only one type of callback.

-

When the Deferred is resolved, the doneCallbacks are called. If the Deferred is instead rejected, the failCallbacks are called. As of jQuery 1.7, the deferred.notify() or deferred.notifyWith() methods can be called to invoke the progressCallbacks as many times as desired before the Deferred is resolved or rejected.

+

Prior to jQuery 1.8, the arguments could be a function or an array of functions.

+

For all signatures, the arguments can be null if no callback of that type is desired. Alternatively, use .done(), .fail() or .progress() to set only one type of callback without filtering status or values.

+ +

As of jQuery 1.8, the deferred.then() method returns a new promise that can filter the status and values of a deferred through a function, replacing the now-deprecated deferred.pipe() method. The doneFilter and failFilter functions filter the original deferred's resolved / rejected status and values. The progressFilter function filters any calls to the original deferred's notify or notifyWith methods. These filter functions can return a new value to be passed along to the promise's .done() or .fail() callbacks, or they can return another observable object (Deferred, Promise, etc) which will pass its resolved / rejected status and values to the promise's callbacks. If the filter function used is null, or not specified, the promise will be resolved or rejected with the same values as the original.

+

Callbacks are executed in the order they were added. Since deferred.then returns a Promise, other methods of the Promise object can be chained to this one, including additional @@ -43,12 +67,64 @@

- Since the jQuery.get method returns a jqXHR object, which is derived from a Deferred object, we can attach handlers using the .then method. + Since the jQuery.get method returns a jqXHR object, which is derived from a Deferred object, we can attach handlers using the .then method. + + + Filter the resolve value: + + + + + Filter reject value: + + + + Chain tasks: + diff --git a/entries/delay.xml b/entries/delay.xml index 7562a0bdf..b2066217d 100644 --- a/entries/delay.xml +++ b/entries/delay.xml @@ -15,31 +15,46 @@

Added to jQuery in version 1.4, the .delay() method allows us to delay the execution of functions that follow it in the queue. It can be used with the standard effects queue or with a custom queue. Only subsequent events in a queue are delayed; for example this will not delay the no-arguments forms of .show() or .hide() which do not use the effects queue.

Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively.

Using the standard effects queue, we can, for example, set an 800-millisecond delay between the .slideUp() and .fadeIn() of <div id="foo">:

-

$('#foo').slideUp(300).delay(800).fadeIn(400);

+

+$( "#foo" ).slideUp( 300 ).delay( 800 ).fadeIn( 400 );
+    

When this statement is executed, the element slides up for 300 milliseconds and then pauses for 800 milliseconds before fading in for 400 milliseconds.

-

+

- The .delay() method is best for delaying between queued jQuery effects. Because it is limited—it doesn't, for example, offer a way to cancel the delay—.delay() is not a replacement for JavaScript's native setTimeout function, which may be more appropriate for certain use cases. + The .delay() method is best for delaying between queued jQuery effects. Because it is limited—it doesn't, for example, offer a way to cancel the delay—.delay() is not a replacement for JavaScript's native setTimeout function, which may be more appropriate for certain use cases.

-

+ Animate the hiding and showing of two divs, delaying the first before showing it. +$( "button" ).on( "click", function() { + $( "div.first" ).slideUp( 300 ).delay( 800 ).fadeIn( 400 ); + $( "div.second" ).slideUp( 300 ).fadeIn( 400 ); +}); +]]> +
+]]> - \ No newline at end of file + diff --git a/entries/delegate.xml b/entries/delegate.xml index 83c0256fa..c0c0dac72 100644 --- a/entries/delegate.xml +++ b/entries/delegate.xml @@ -1,5 +1,5 @@ - + Attach a handler to one or more events for all elements that match the selector, now or in the future, based on a specific set of root elements. @@ -10,8 +10,9 @@ A string containing one or more space-separated JavaScript event types, such as "click" or "keydown," or custom event names. - + A function to execute at the time the event is triggered. + @@ -22,11 +23,12 @@ A string containing one or more space-separated JavaScript event types, such as "click" or "keydown," or custom event names. - - A map of data that will be passed to the event handler. + + An object containing data that will be passed to the event handler. - + A function to execute at the time the event is triggered. + @@ -35,84 +37,116 @@ A selector to filter the elements that trigger the event. - A map of one or more event types and functions to execute for them. + A plain object of one or more event types and functions to execute for them. -

As of jQuery 1.7, .delegate() has been superseded by the .on() method. For earlier versions, however, it remains the most effective means to use event delegation. More information on event binding and delegation is in the .on() method. In general, these are the equivalent templates for the two methods:

+

As of jQuery 3.0, .delegate() has been deprecated. It was superseded by the .on() method since jQuery 1.7, so its use was already discouraged. For earlier versions, however, it remains the most effective means to use event delegation. More information on event binding and delegation is in the .on() method. In general, these are the equivalent templates for the two methods:

-$(elements).delegate(selector, events, data, handler);  // jQuery 1.4.3+
-$(elements).on(events, selector, data, handler);        // jQuery 1.7+
- 

+// jQuery 1.4.3+ +$( elements ).delegate( selector, events, data, handler ); +// jQuery 1.7+ +$( elements ).on( events, selector, data, handler ); +

For example, the following .delegate() code:

-

$("table").delegate("td", "click", function() {
-  $(this).toggleClass("chosen");
-});

+

+$( "table" ).delegate( "td", "click", function() {
+  $( this ).toggleClass( "chosen" );
+});
+    

is equivalent to the following code written using .on():

-

$("table").on("click", "td", function() {
-  $(this).toggleClass("chosen");
-});

-

To remove events attached with delegate(), see the .undelegate() method.

+

+$( "table" ).on( "click", "td", function() {
+  $( this ).toggleClass( "chosen" );
+});
+    

+

To remove events attached with delegate(), see the .undelegate() method.

Passing and handling event data works the same way as it does for .on().

Click a paragraph to add another. Note that .delegate() attaches a click event handler to all paragraphs - even new ones. - + + +]]> To display each paragraph's text in an alert box whenever it is clicked: - + To cancel a default action and prevent it from bubbling up, return false: - + To cancel only the default action by using the preventDefault method. - +}); +]]> Can bind custom events too. - + p { + color: red; + } + span { + color: blue; + } +]]> + - \ No newline at end of file + + diff --git a/entries/dequeue.xml b/entries/dequeue.xml index d0d74e49a..c54401c78 100644 --- a/entries/dequeue.xml +++ b/entries/dequeue.xml @@ -14,27 +14,37 @@ Use dequeue to end a custom queue function which allows the queue to keep going. - + - \ No newline at end of file + diff --git a/entries/descendant-selector.xml b/entries/descendant-selector.xml index 3d3d62926..5792b612a 100644 --- a/entries/descendant-selector.xml +++ b/entries/descendant-selector.xml @@ -16,29 +16,41 @@

A descendant of an element could be a child, grandchild, great-grandchild, and so on, of that element.

- Finds all input descendants of forms. - + Mark all inputs that are descendants of a form with a dotted blue border. Give a yellow background to inputs that are descendants of a fieldset that is a descendant of a form. + + - +
+ Grandchild of form, child of fieldset: + +
+ +Sibling to form: +]]> - \ No newline at end of file + diff --git a/entries/detach.xml b/entries/detach.xml index 301ad74d5..bc6b32c77 100644 --- a/entries/detach.xml +++ b/entries/detach.xml @@ -9,29 +9,40 @@ Remove the set of matched elements from the DOM. -

The .detach() method is the same as .remove(), except that .detach() keeps all jQuery data associated with the removed elements. This method is useful when removed elements are to be reinserted into the DOM at a later time.

+

The .detach() method is the same as .remove(), except that .detach() keeps all jQuery data associated with the removed elements. This method is useful when removed elements are to be reinserted into the DOM at a later time.

Detach all paragraphs from the DOM - - +$( "p" ).on( "click", function() { + $( this ).toggleClass( "off" ); +}); +var p; +$( "button" ).on( "click", function() { + if ( p ) { + p.appendTo( "body" ); + p = null; + } else { + p = $( "p" ).detach(); + } +}); +]]> + + - \ No newline at end of file + diff --git a/entries/die.xml b/entries/die.xml index 42c868d96..efe2e6145 100644 --- a/entries/die.xml +++ b/entries/die.xml @@ -1,5 +1,5 @@ - + Remove event handlers previously attached using .live() from the elements. @@ -17,67 +17,49 @@ 1.4.3 - A map of one or more event types, such as click or keydown and their corresponding functions that are no longer to be executed. + A plain object of one or more event types, such as click or keydown and their corresponding functions that are no longer to be executed. -

Any handler that has been attached with .live() can be removed with .die(). This method is analogous to calling .unbind() with no arguments, which is used to remove all handlers attached with .bind(). - See the discussions of .live() and .unbind() for further details.

+
+
Note: This API has been removed in jQuery 1.9; please use on() instead.
+
+

Any handler that has been attached with .live() can be removed with .die(). This method is analogous to calling .off() with no arguments, which is used to remove all handlers attached with .on(). + See the discussions of .live() and .off() for further details.

If used without an argument, .die() removes all event handlers previously attached using .live() from the elements.

-

As of jQuery 1.7, use of .die() (and its complementary method, .live()) is not recommended. Instead, use .off() to remove event handlers bound with .on()

+

As of jQuery 1.7, use of .die() (and its complementary method, .live()) is not recommended. Instead, use .off() to remove event handlers bound with .on()

Note: In order for .die() to function correctly, the selector used with it must match exactly the selector initially used with .live().

- - - - - Can bind and unbind events to the colored button. + To unbind all live events from all paragraphs, write: - - - - - To unbind all live events from all paragraphs, write: - To unbind all live click events from all paragraphs, write: - + To unbind just one previously bound handler, pass the function in as the second argument: - +// Now foo will no longer be called +$( "p" ).die( "click", foo ); +]]> + + - diff --git a/entries/disabled-selector.xml b/entries/disabled-selector.xml index 8e601b34a..812c8f572 100644 --- a/entries/disabled-selector.xml +++ b/entries/disabled-selector.xml @@ -9,19 +9,22 @@

As with other pseudo-class selectors (those that begin with a ":"), it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare $(':disabled') is equivalent to $('*:disabled'), so $('input:disabled') or similar should be used instead.

-

Although their resulting selections are usually the same, the :disabled selector is subtly different from the [disabled] attribute selector; :disabled checks the boolean (true/false) value of the element's disabled property while [disabled] checks for the existence of the disabled attribute.

+

Although their resulting selections are usually the same, the :disabled selector is subtly different from the [disabled] attribute selector;:disabled matches elements that are actually disabled while [disabled] only checks for the existence of the disabled attribute.

-

The :disabled selector should only be used for selecting HTML elements that support the disabled attribute (<button>, <input>, <optgroup>, <option>, <select>, and <textarea>).

+

The :disabled selector should only be used for selecting HTML elements that support the disabled attribute (<button>, <input>, <optgroup>, <option>, <select>, <textarea>, <menuitem>, and <fieldset>).

Finds all input elements that are disabled. - - + + diff --git a/entries/each.xml b/entries/each.xml index d38e6895b..fd2db6483 100644 --- a/entries/each.xml +++ b/entries/each.xml @@ -3,117 +3,145 @@ 1.0 - + A function to execute for each matched element. + + Iterate over a jQuery object, executing a function for each matched element.

The .each() method is designed to make DOM looping constructs concise and less error-prone. When called it iterates over the DOM elements that are part of the jQuery object. Each time the callback runs, it is passed the current loop iteration, beginning from 0. More importantly, the callback is fired in the context of the current DOM element, so the keyword this refers to the element.

Suppose you have a simple unordered list on the page:

-

<ul>
-    <li>foo</li>
-    <li>bar</li>
+    

+<ul>
+  <li>foo</li>
+  <li>bar</li>
 </ul>
     
     
You can select the list items and iterate across them:
-
$( "li" ).each(function( index ) {
-  console.log( index + ": "" + $(this).text() );
+    

+$( "li" ).each(function( index ) {
+  console.log( index + ": " + $( this ).text() );
 });
-  
+    
     
A message is thus logged for each item in the list:
     

-      0: foo
+      0: foo
       

-      1: bar
+      1: bar
     
     
You can stop the loop from within the callback function by returning false.
     
Note: most jQuery methods that return a jQuery object also loop through the set of elements in the jQuery collection — a process known as implicit iteration. When this occurs, it is often unnecessary to explicitly iterate with the .each() method:
-
// The .each() method is unnecessary here:
+    

+// The .each() method is unnecessary here:
 $( "li" ).each(function() {
-  $(this).addClass( "foo" );
+  $( this ).addClass( "foo" );
 });
 
 // Instead, you should rely on implicit iteration:
 $( "li" ).addClass( "bar" );
-
+    
   
   
     Iterate over three divs and sets their color property.
     
     
-    
+  div {
+    color: red;
+    text-align: center;
+    cursor: pointer;
+    font-weight: bolder;
+    width: 300px;
+  }
+]]>
+    
   
   
-    To access a jQuery object instead of the regular DOM element, use $(this). For example:
+    To access a jQuery object instead of the regular DOM element, use $( this ). For example:
     
     
-    
+  ul {
+    font-size: 18px;
+    margin: 0;
+  }
+  span {
+    color: blue;
+    text-decoration: underline;
+    cursor: pointer;
+  }
+  .example {
+    font-style: italic;
+  }
+]]>
+    
   
   
-    Use "return" to break out of each() loops early.
+    Use return false to break out of each() loops early.
     
     
-    
+  div {
+    width: 40px;
+    height: 40px;
+    margin: 5px;
+    float: left;
+    border: 2px blue solid;
+    text-align: center;
+  }
+  span {
+    color: red;
+  }
+]]>
+    
   
   
   
diff --git a/entries/element-selector.xml b/entries/element-selector.xml
index 8061f3402..a26a9109e 100644
--- a/entries/element-selector.xml
+++ b/entries/element-selector.xml
@@ -14,22 +14,25 @@
   
   
     Finds every DIV element.
-    
-    
+    
+    
     
+]]>
   
   
   
-
\ No newline at end of file
+
diff --git a/entries/empty-selector.xml b/entries/empty-selector.xml
index 05e13b67e..165e21121 100644
--- a/entries/empty-selector.xml
+++ b/entries/empty-selector.xml
@@ -9,22 +9,28 @@
   
     
This is the inverse of :parent. 
     
One important thing to note with :empty (and :parent) is that child elements include text nodes.
-    
The W3C recommends that the <p> element have at least one child node, even if that child is merely text (see http://www.w3.org/TR/html401/struct/text.html#edef-P). Some other elements, on the other hand, are empty (i.e. have no children) by definition: <input>, <img>, <br>, and <hr>, for example.
+    
The W3C recommends that the <p> element have at least one child node, even if that child is merely text (see https://www.w3.org/TR/html401/struct/text.html#edef-P). Some other elements, on the other hand, are empty (i.e. have no children) by definition: <input>, <img>, <br>, and <hr>, for example.
   
   
     Finds all elements that are empty - they don't have child elements or text.
-    
+    
     
-    
+  td {
+    text-align: center;
+  }
+]]>
+    
   
   
   
-
\ No newline at end of file
+
diff --git a/entries/empty.xml b/entries/empty.xml
index 0a1fe9ba3..097ad9c66 100644
--- a/entries/empty.xml
+++ b/entries/empty.xml
@@ -7,37 +7,47 @@
   Remove all child nodes of the set of matched elements from the DOM.
   
     
This method removes not only child (and other descendant) elements, but also any text within the set of matched elements. This is because, according to the DOM specification, any string of text within an element is considered a child node of that element. Consider the following HTML:
-    
<div class="container">
+    

+<div class="container">
   <div class="hello">Hello</div>
   <div class="goodbye">Goodbye</div>
-</div>
+</div>
+    
     
We can target any element for removal:
-    
$('.hello').empty();
+    

+$( ".hello" ).empty();
+    
     
This will result in a DOM structure with the Hello text deleted:
-    
<div class="container">
+    

+<div class="container">
   <div class="hello"></div>
   <div class="goodbye">Goodbye</div>
-</div>
-    
If we had any number of nested elements inside <div class="hello">, they would be removed, too. 
+</div>
+    
+    
If we had any number of nested elements inside <div class="hello">, they would be removed, too.
     
To avoid memory leaks, jQuery removes other constructs such as data and event handlers from the child elements before removing the elements themselves.
     
If you want to remove elements without destroying their data or event handlers (so they can be re-added later), use .detach() instead.
   
   
     Removes all child nodes (including text nodes) from all paragraphs
     
     
-    
+Call empty() on above paragraph
+]]>
   
   
   
-
\ No newline at end of file
+
diff --git a/entries/enabled-selector.xml b/entries/enabled-selector.xml
index 7b40f5d60..177680e3f 100644
--- a/entries/enabled-selector.xml
+++ b/entries/enabled-selector.xml
@@ -7,7 +7,7 @@
   
   Selects all elements that are enabled.
   
-    
As with other pseudo-class selectors (those that begin with a ":") it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare $(':enabled') is equivalent to $('*:enabled'), so $('input:enabled') or similar should be used instead. 
+    
As with other pseudo-class selectors (those that begin with a ":") it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ( "*" ) is implied. In other words, the bare $( ":enabled" ) is equivalent to $( "*:enabled" ), so $( "input:enabled" ) or similar should be used instead. 
 
     
Although their resulting selections are usually the same, :enabled selector is subtly different from :not([disabled]); :enabled selects elements that have their boolean disabled property strictly equal to false, while :not([disabled]) selects elements that do not have a disabled attribute set (regardless of its value).
 
@@ -16,12 +16,15 @@
   
   
     Find all input elements that are enabled.
-    
-    
+    
+    
   
   
   
diff --git a/entries/end.xml b/entries/end.xml
index eb1fbbb1c..7f85ea1aa 100644
--- a/entries/end.xml
+++ b/entries/end.xml
@@ -6,90 +6,120 @@
   
   End the most recent filtering operation in the current chain and return the set of matched elements to its previous state.
   
-    
Most of jQuery's DOM traversal methods operate on a jQuery object instance and produce a new one, matching a different set of DOM elements. When this happens, it is as if the new set of elements is pushed onto a stack that is maintained inside the object. Each successive filtering method pushes a new element set onto the stack. If we need an older element set, we can use end() to pop the sets back off of the stack.
+    
Most of jQuery's DOM traversal methods operate on a jQuery object instance and produce a new one, matching a different set of DOM elements. When this happens, it is as if the new set of elements is pushed onto a stack that is maintained inside the object. Each successive filtering method pushes a new element set onto the stack. If we need an older element set, we can use end() to pop the sets back off of the stack.
     
Suppose we have a couple short lists on a page:
     

 <ul class="first">
-   <li class="foo">list item 1</li>
-   <li>list item 2</li>
-   <li class="bar">list item 3</li>
+  <li class="foo">list item 1</li>
+  <li>list item 2</li>
+  <li class="bar">list item 3</li>
 </ul>
 <ul class="second">
-   <li class="foo">list item 1</li>
-   <li>list item 2</li>
-   <li class="bar">list item 3</li>
+  <li class="foo">list item 1</li>
+  <li>list item 2</li>
+  <li class="bar">list item 3</li>
 </ul>
-
+    

The end() method is useful primarily when exploiting jQuery's chaining properties. When not using chaining, we can usually just call up a previous object by variable name, so we don't need to manipulate the stack. With end(), though, we can string all the method calls together:

-$('ul.first').find('.foo').css('background-color', 'red')
-  .end().find('.bar').css('background-color', 'green');
-

+$( "ul.first" ) + .find( ".foo" ) + .css( "background-color", "red" ) + .end() + .find( ".bar" ) + .css( "background-color", "green" ); +

This chain searches for items with the class foo within the first list only and turns their backgrounds red. Then end() returns the object to its state before the call to find(), so the second find() looks for '.bar' inside <ul class="first">, not just inside that list's <li class="foo">, and turns the matching elements' backgrounds green. The net result is that items 1 and 3 of the first list have a colored background, and none of the items from the second list do.

A long jQuery chain can be visualized as a structured code block, with filtering methods providing the openings of nested blocks and end() methods closing them:

-$('ul.first').find('.foo')
-  .css('background-color', 'red')
-.end().find('.bar')
-  .css('background-color', 'green')
-.end();
-

+$( "ul.first" ) + .find( ".foo" ) + .css( "background-color", "red" ) + .end() + .find( ".bar" ) + .css( "background-color", "green" ) + .end(); +

The last end() is unnecessary, as we are discarding the jQuery object immediately thereafter. However, when the code is written in this form, the end() provides visual symmetry and a sense of completion —making the program, at least to the eyes of some developers, more readable, at the cost of a slight hit to performance as it is an additional function call.

Selects all paragraphs, finds span elements inside these, and reverts the selection back to the paragraphs. - + +
+ Tags in jQuery object after end: +
+]]> Selects all paragraphs, finds span elements inside these, and reverts the selection back to the paragraphs. - - - + + + - \ No newline at end of file + diff --git a/entries/eq-selector.xml b/entries/eq-selector.xml index f312b6b00..a191d31be 100644 --- a/entries/eq-selector.xml +++ b/entries/eq-selector.xml @@ -1,49 +1,88 @@ - + - :eq(index) + :eq(index) 1.0 Zero-based index of the element to match. + + :eq(-index) + 1.8 + + Zero-based index of the element to match, counting backwards from the last element. + + Select the element at index n within the matched set. +
+
As of jQuery 3.4, the :eq pseudo-class is deprecated. Remove it from your selectors and filter the results later using .eq().
+

The index-related selectors (:eq(), :lt(), :gt(), :even, :odd) filter the set of elements that have matched the expressions that precede them. They narrow the set down based on the order of the elements within this matched set. For example, if elements are first selected with a class selector (.myclass) and four elements are returned, these elements are given indices 0 through 3 for the purposes of these selectors.

-

Note that since JavaScript arrays use 0-based indexing, these selectors reflect that fact. This is why $('.myclass:eq(1)') selects the second element in the document with the class myclass, rather than the first. In contrast, :nth-child(n) uses 1-based indexing to conform to the CSS specification.

-

Unlike the .eq(index) method, the :eq(index) selector does not accept a negative value for index. For example, while $('li').eq(-1) selects the last li element, $('li:eq(-1)') selects nothing.

+

Note that since JavaScript arrays use 0-based indexing, these selectors reflect that fact. This is why $( ".myclass:eq(1)" ) selects the second element in the document with the class myclass, rather than the first. In contrast, :nth-child(n) uses 1-based indexing to conform to the CSS specification.

+

Prior to jQuery 1.8, the :eq(index) selector did not accept a negative value for index (though the .eq(index) method did).

- Finds the third td. - - + + +]]> 160 Apply three different styles to list items to demonstrate that :eq() is designed to select a single element while :nth-child() or :eq() within a looping construct such as .each() can select multiple elements. - + + + Add a class to List 2, item 2 by targeting the second to last <li> + + + - + div { + width: 60px; + height: 60px; + margin: 10px; + float: left; + border: 2px solid blue; + } + .blue { + background: blue; + } +]]> + - \ No newline at end of file + diff --git a/entries/error-shorthand.xml b/entries/error-shorthand.xml new file mode 100644 index 000000000..b40d9b755 --- /dev/null +++ b/entries/error-shorthand.xml @@ -0,0 +1,37 @@ + + + + Bind an event handler to the "error" event, or trigger that event on an element. + + 1.0 + + A function to execute each time the event is triggered. + + + + + 1.4.3 + + An object containing data that will be passed to the event handler. + + + A function to execute each time the event is triggered. + + + + + 1.0 + + +
+
This API has been removed in jQuery 3.0.
+
Instead of .error( handler ) or .error( eventData, handler ), use .on( "error", handler ) or .on( "error", eventData, handler ), respectively.
+
Instead of .error(), use .trigger( "error" ).
+
+ + + + + + + diff --git a/entries/error.xml b/entries/error.xml index 3c4df887b..d1f9493ea 100644 --- a/entries/error.xml +++ b/entries/error.xml @@ -1,52 +1,79 @@ - - - Bind an event handler to the "error" JavaScript event. + +Bind an event handler to the "error" event, or trigger that event on an element. + + + + Bind an event handler to the "error" event. - 1.0 - - A function to execute when the event is triggered. + 1.7 + + The string "error". - - - 1.4.3 - - A map of data that will be passed to the event handler. + + An object containing data that will be passed to the event handler. - + A function to execute each time the event is triggered. + -

This method is a shortcut for .bind('error', handler).

+
+
This page describes the error event. For the .error() method removed in jQuery 3.0, see .error().
+

The error event is sent to elements, such as images, that are referenced by a document and loaded by the browser. It is called if the element was not loaded correctly.

For example, consider a page with a simple image element:

-

<img alt="Book" id="book" />

+

+<img alt="Book" id="book">
+    

The event handler can be bound to the image:

-

$('#book')
-  .error(function() {
-    alert('Handler for .error() called.')
-  })
-  .attr("src", "missing.png");
+    

+$( "#book" )
+  .on( "error", function() {
+    alert( "Handler for `error` called." )
+  } )
+  .attr( "src", "missing.png" );
     
-    
If the image cannot be loaded (for example, because it is not present at the supplied URL), the alert  is displayed:
+    
If the image cannot be loaded (for example, because it is not present at the supplied URL), the alert is displayed:
     

-      Handler for .error() called.
+      Handler for `error` called.
     
-    

-      
The event handler must be attached before the browser fires the error event, which is why the example sets the src attribute after attaching the handler. Also, the error event may not be correctly fired when the page is served locally; error relies on HTTP status codes and will generally not be triggered if the URL uses the file: protocol.
-    
-    
Note: A jQuery error event handler should not be attached to the window object. The browser fires the window's error event when a script error occurs. However, the window error event receives different arguments and has different return value requirements than conventional event handlers. Use window.onerror instead.
+    

+      
The event handler must be attached before the browser fires the error event, which is why the example sets the src attribute after attaching the handler. Also, the error event may not be correctly fired when the page is served locally; error relies on HTTP status codes and will generally not be triggered if the URL uses the file: protocol.
+    
+    
Note: A jQuery error event handler should not be attached to the window object. The browser fires the window's error event when a script error occurs. However, the window error event receives different arguments and has different return value requirements than conventional event handlers. Use window.onerror instead.
   
   
-    To hide the "broken image" icons for IE users, you can try:
-    
+    To replace all the missing images with another, you can update the src attribute inside the error handler. Be sure that the replacement image exists; otherwise the error event will be triggered indefinitely.
+    
   
   
   
-  
-
\ No newline at end of file
+  
+
+
+
+  
+  Trigger the "error" event on an element.
+  
+    1.0
+    
+      The string "error".
+    
+  
+  
+    
See the description for .on( "error", ... ).
+  
+  
+  
+
+
+
diff --git a/entries/even-selector.xml b/entries/even-selector.xml
index 42210e419..bfc8038a3 100644
--- a/entries/even-selector.xml
+++ b/entries/even-selector.xml
@@ -1,33 +1,40 @@
 
-
+
   
   :even
   
     1.0
   
-  Selects even elements, zero-indexed.  See also odd.
+  Selects even elements, zero-indexed.  See also :odd.
   
+    

+      
As of jQuery 3.4, the :even pseudo-class is deprecated. Remove it from your selectors and filter the results later using .even() (available in jQuery 3.5.0 or newer).
+    
     
In particular, note that the 0-based indexing means that, counter-intuitively, :even selects the first element, third element, and so on within the matched set.
   
   
   
   
     Finds even table rows, matching the first, third and so on (index 0, 2, 4 etc.).
-    
+    
     
-    
+]]>
+    
   
   
   
   
+  
 
diff --git a/entries/even.xml b/entries/even.xml
new file mode 100644
index 000000000..cecff9e42
--- /dev/null
+++ b/entries/even.xml
@@ -0,0 +1,47 @@
+
+
+  
+  
+    3.5
+  
+  Reduce the set of matched elements to the even ones in the set, numbered from zero.
+  
+    
Given a jQuery object that represents a set of DOM elements, the .even() method constructs a new jQuery object from the even elements in that set. Counting starts from zero!
+    
Consider a page with a simple list on it:
+    

+<ul>
+  <li>list item 1</li>
+  <li>list item 2</li>
+  <li>list item 3</li>
+  <li>list item 4</li>
+  <li>list item 5</li>
+</ul>
+    
+    
We can apply this method to the set of list items:
+    

+$( "li" ).even().css( "background-color", "red" );
+    
+    
The result of this call is a red background for the first, third & 5th items.
+  
+  
+    Highlight the even items in a list.
+    
+    
+    
+  
+  
+  
+
diff --git a/entries/event.currentTarget.xml b/entries/event.currentTarget.xml
index d25c6f7bd..859cb8d41 100644
--- a/entries/event.currentTarget.xml
+++ b/entries/event.currentTarget.xml
@@ -8,15 +8,17 @@
   
     
This property will typically be equal to the this of the function.
     

-      If you are using jQuery.proxy or another form of scope manipulation, this will be equal to whatever context you have provided, not event.currentTarget
+      If you are using jQuery.proxy or another form of scope manipulation, this will be equal to whatever context you have provided, not event.currentTarget
     
   
   
     Alert that currentTarget matches the `this` keyword.
-    
+});
+]]>
   
   
   
-
\ No newline at end of file
+
diff --git a/entries/event.data.xml b/entries/event.data.xml
index ecd7b92d3..c1e249325 100644
--- a/entries/event.data.xml
+++ b/entries/event.data.xml
@@ -4,7 +4,7 @@
   
     1.1
   
-  An optional data map passed to an event method when the current executing handler is bound.  
+  An optional object of data passed to an event method when the current executing handler is bound.  
   
   
     Within a for loop, pass the value of i to the .on() method so that the current iteration's value is preserved. 
@@ -18,17 +18,16 @@
 

 ]]>
     " );
+    logDiv.append( msgs.join( ", " ) + "
" );
   });
 }
 ]]>
diff --git a/entries/event.delegateTarget.xml b/entries/event.delegateTarget.xml
index a0c450896..af9b55bad 100644
--- a/entries/event.delegateTarget.xml
+++ b/entries/event.delegateTarget.xml
@@ -6,16 +6,18 @@
   
   The element where the currently-called jQuery event handler was attached.
   
-    
This property is most often useful in delegated events attached by .delegate() or .on(), where the event handler is attached at an ancestor of the element being processed. It can be used, for example, to identify and remove event handlers at the delegation point.
+    
This property is most often useful in delegated events attached by .delegate() or .on(), where the event handler is attached at an ancestor of the element being processed. It can be used, for example, to identify and remove event handlers at the delegation point.
     
For non-delegated event handlers attached directly to an element, event.delegateTarget will always be equal to event.currentTarget.
   
   
     When a button in any box class is clicked, change the box's background color to red.
-    
+    
   
   
   
   
-
\ No newline at end of file
+
diff --git a/entries/event.isDefaultPrevented.xml b/entries/event.isDefaultPrevented.xml
index 0b660e1e2..d9ada3149 100644
--- a/entries/event.isDefaultPrevented.xml
+++ b/entries/event.isDefaultPrevented.xml
@@ -4,15 +4,17 @@
   
     1.3
   
-  Returns whether event.preventDefault() was ever called on this event object. 
+  Returns whether event.preventDefault() was ever called on this event object. 
      
   
     Checks whether event.preventDefault() was called.
-    
+});
+]]>
   
   
   
diff --git a/entries/event.isImmediatePropagationStopped.xml b/entries/event.isImmediatePropagationStopped.xml
index 8f6e63d51..433cd4912 100644
--- a/entries/event.isImmediatePropagationStopped.xml
+++ b/entries/event.isImmediatePropagationStopped.xml
@@ -6,33 +6,32 @@
   
     Returns whether event.stopImmediatePropagation() was ever called on this event object. 
   
-    
This property was introduced in DOM level 3.
+    
This property was introduced in DOM level 3.
   
   
     Checks whether event.stopImmediatePropagation() was called.
     
     
   
   
   
-
\ No newline at end of file
+
diff --git a/entries/event.isPropagationStopped.xml b/entries/event.isPropagationStopped.xml
index dbf08286d..c6c270b4d 100644
--- a/entries/event.isPropagationStopped.xml
+++ b/entries/event.isPropagationStopped.xml
@@ -4,33 +4,32 @@
   
     1.3
   
-    Returns whether event.stopPropagation() was ever called on this event object. 
+    Returns whether event.stopPropagation() was ever called on this event object. 
   
-    
This event method is described in the W3C DOM Level 3 specification.
+    
This event method is described in the W3C DOM Level 3 specification.
   
   
     Checks whether event.stopPropagation() was called
     
     
   
   
diff --git a/entries/event.metaKey.xml b/entries/event.metaKey.xml
index a35597ac3..0c00d6b9b 100644
--- a/entries/event.metaKey.xml
+++ b/entries/event.metaKey.xml
@@ -4,21 +4,30 @@
   
     1.0.4
   
-	Indicates whether the META key was pressed when the event fired.
-	
+  Indicates whether the META key was pressed when the event fired.
+  
     
Returns a boolean value (true or false) that indicates whether or not the META key was pressed at the time the event fired.
     This key might map to an alternative key name on some platforms.
-	
+    
On Macintosh keyboards, the META key maps to the Command key (⌘).
+    
On Windows keyboards, the META key maps to the Windows key.
+  
   
     Determine whether the META key was pressed when the event fired.
-    body {background-color: #eef; }
-    div { padding: 20px; }
-	
+    
-		
+    
   
diff --git a/entries/event.namespace.xml b/entries/event.namespace.xml
index bfb7cafd5..bbebcda4d 100644
--- a/entries/event.namespace.xml
+++ b/entries/event.namespace.xml
@@ -11,11 +11,11 @@
   
     Determine the event namespace used.
     
     
-    
+    Show the mouse position relative to the left and top edges of the document (within this iframe).
+    
+    
+    
   
   
   
-
\ No newline at end of file
+
diff --git a/entries/event.pageY.xml b/entries/event.pageY.xml
index 134cd5528..8815db947 100644
--- a/entries/event.pageY.xml
+++ b/entries/event.pageY.xml
@@ -4,20 +4,27 @@
   
     1.0.4
   
-  The mouse position relative to the top edge of the document. 
+  The mouse position relative to the top edge of the document.
      
   
     Show the mouse position relative to the left and top edges of the document (within this iframe).
-    body {background-color: #eef; }
-      div { padding: 20px; }
-    
-    
+    
+    
     
+]]>
   
   
   
-
\ No newline at end of file
+
diff --git a/entries/event.preventDefault.xml b/entries/event.preventDefault.xml
index 397b066c2..82b4e1047 100644
--- a/entries/event.preventDefault.xml
+++ b/entries/event.preventDefault.xml
@@ -4,25 +4,25 @@
   
     1.0
   
-   If this method is called, the default action of the event will not be triggered. 
+  If this method is called, the default action of the event will not be triggered.
   
-    
For example, clicked anchors will not take the browser to a new URL. We can use event.isDefaultPrevented() to determine if this method has been called by an event handler that was triggered by this event.
+    
For example, clicked anchors will not take the browser to a new URL. We can use event.isDefaultPrevented() to determine if this method has been called by an event handler that was triggered by this event.
   
   
     Cancel the default action (navigation) of the click.
     
     
   
   
   
-
\ No newline at end of file
+
diff --git a/entries/event.relatedTarget.xml b/entries/event.relatedTarget.xml
index 0a03e3277..e4ee9eafa 100644
--- a/entries/event.relatedTarget.xml
+++ b/entries/event.relatedTarget.xml
@@ -4,16 +4,18 @@
   
     1.1.4
   
-  The other DOM element involved in the event, if any. 
+  The other DOM element involved in the event, if any.
   
     
For mouseout, indicates the element being entered; for mouseover, indicates the element being exited. 
   
   
     On mouseout of anchors, alert the element type being entered.
-    
+    
   
   
   
-
\ No newline at end of file
+
diff --git a/entries/event.result.xml b/entries/event.result.xml
index e6823b2c6..40bd18724 100644
--- a/entries/event.result.xml
+++ b/entries/event.result.xml
@@ -11,11 +11,11 @@
   
     Display previous handler's return value
     
     
     
-    
+  $( this ).css( "background-color", "#f00" );
+});
+]]>
+    
   
   
   
-
\ No newline at end of file
+
diff --git a/entries/event.stopPropagation.xml b/entries/event.stopPropagation.xml
index 69c5ee728..de93b6e68 100644
--- a/entries/event.stopPropagation.xml
+++ b/entries/event.stopPropagation.xml
@@ -1,23 +1,25 @@
 
-
+
   
   
     1.0
   
-  Prevents the event from bubbling up the DOM tree, preventing any parent handlers from being notified of the event.   
+  Prevents the event from bubbling up the DOM tree, preventing any parent handlers from being notified of the event.
   
-    
We can use event.isPropagationStopped() to determine if this method was ever called (on that event object). 
-    
This method works for custom events triggered with trigger(), as well.
+    
We can use event.isPropagationStopped() to determine if this method was ever called (on that event object). 
+    
This method works for custom events triggered with trigger() as well.
     
Note that this will not prevent other handlers on the same element from running. 
   
   
   
     Kill the bubbling on the click event.
-    
+  // Do something
+});
+]]>
   
   
   
-
\ No newline at end of file
+
diff --git a/entries/event.target.xml b/entries/event.target.xml
index cd1346244..82c701778 100644
--- a/entries/event.target.xml
+++ b/entries/event.target.xml
@@ -10,30 +10,38 @@
   
   
     Display the tag's name on click
-    
-    
-span, strong, p {
-  padding: 8px; display: block; border: 1px solid #999;  }
-    
+    
+    
     
+
+]]>
   
   
     Implements a simple event delegation: The click handler is added to an unordered list, and the children of its li children are hidden. Clicking one of the li children toggles (see toggle()) their children.
-    
+$( "ul" ).on( "click", handler ).find( "ul" ).hide();
+]]>
     
       
sub item 2-b
     

-