.attr(), .html(), and .val()—also act as "getters," retrieving information from DOM elements for later use.
+ ]]>
this refers to the current element in the set.It's important to note that this method does not replace a class. It simply adds the class, appending it to any which may already be assigned to the elements.
@@ -64,7 +80,30 @@ $( "p" ).last().addClass( "selected" );This API is deprecated. Use .on( "ajaxError", handler ) instead.
"ajaxError".Whenever an Ajax request completes with an error, jQuery triggers the ajaxError event. Any and all handlers that have been registered with the .ajaxError() method are executed at this time. Note: This handler is not called for cross-domain script and cross-domain JSONP requests.
This page describes the ajaxError event. For the deprecated .ajaxError() method, see .ajaxError().
Whenever an Ajax request completes with an error, jQuery triggers the ajaxError event. Any and all registered ajaxError handlers are executed at this time. Note: This handler is not called for cross-domain script and cross-domain JSONP requests.
To observe this method in action, set up a basic Ajax load request.
<button class="trigger">Trigger</button>
@@ -22,35 +28,37 @@
Attach the event handler to the document:
-$( document ).ajaxError(function() {
+$( document ).on( "ajaxError", function() {
$( ".log" ).text( "Triggered ajaxError handler." );
-});
+} );
Now, make an Ajax request using any jQuery method:
$( "button.trigger" ).on( "click", function() {
$( "div.result" ).load( "ajax/missing.html" );
-});
+} );
When the user clicks the button and the Ajax request fails, because the requested file is missing, the log message is displayed.
All ajaxError handlers are invoked, regardless of what Ajax request was completed. To differentiate between the requests, use the parameters passed to the handler. Each time an ajaxError handler is executed, it is passed the event object, the jqXHR object (prior to jQuery 1.5, the XHR object), and the settings object that was used in the creation of the request. When an HTTP error occurs, the fourth argument (thrownError) receives the textual portion of the HTTP status, such as "Not Found" or "Internal Server Error." For example, to restrict the error callback to only handling events dealing with a particular URL:
-$( document ).ajaxError(function( event, jqxhr, settings, thrownError ) {
+$( document ).on( "ajaxError", function( event, jqxhr, settings, thrownError ) {
if ( settings.url == "ajax/missing.html" ) {
$( "div.log" ).text( "Triggered ajaxError handler." );
}
-});This API is deprecated. Use .on( "ajaxSend", handler ) instead.
"ajaxSend".Whenever an Ajax request is about to be sent, jQuery triggers the ajaxSend event. Any and all handlers that have been registered with the .ajaxSend() method are executed at this time.
This page describes the ajaxSend event. For the deprecated .ajaxSend() method, see .ajaxSend().
Whenever an Ajax request is about to be sent, jQuery triggers the ajaxSend event. Any and all registerd ajaxSend handlers are executed at this time.
To observe this method in action, set up a basic Ajax load request:
<div class="trigger">Trigger</div>
@@ -21,36 +27,37 @@
Attach the event handler to the document:
-$( document ).ajaxSend(function() {
+$( document ).on( "ajaxSend", function() {
$( ".log" ).text( "Triggered ajaxSend handler." );
-});
+} );
Now, make an Ajax request using any jQuery method:
-$( ".trigger" ).click(function() {
+$( ".trigger" ).on( "click", function() {
$( ".result" ).load( "ajax/test.html" );
-});
+} );
When the user clicks the element with class trigger and the Ajax request is about to begin, the log message is displayed.
All ajaxSend handlers are invoked, regardless of what Ajax request is to be sent. If you must differentiate between the requests, use the parameters passed to the handler. Each time an ajaxSend handler is executed, it is passed the event object, the jqXHR object (in version 1.4, XMLHttpRequestobject), and the settings object that was used in the creation of the Ajax request. For example, you can restrict the callback to only handling events dealing with a particular URL:
-$( document ).ajaxSend(function( event, jqxhr, settings ) {
+$( document ).on( "ajaxSend", function( event, jqxhr, settings ) {
if ( settings.url == "ajax/test.html" ) {
$( ".log" ).text( "Triggered ajaxSend handler." );
}
-});
+} );
This API is deprecated. Use .on( "ajaxStart", handler ) instead.
"ajaxStart".Whenever an Ajax request is about to be sent, jQuery checks whether there are any other outstanding Ajax requests. If none are in progress, jQuery triggers the ajaxStart event. Any and all handlers that have been registered with the .ajaxStart() method are executed at this time.
This page describes the ajaxStart event. For the deprecated .ajaxStart() method, see .ajaxStart().
Whenever an Ajax request is about to be sent, jQuery checks whether there are any other outstanding Ajax requests. If none are in progress, jQuery triggers the ajaxStart event. Any and all handlers that have been registered with .on( "ajaxStart", ... ) are executed at this time.
To observe this method in action, set up a basic Ajax load request:
<div class="trigger">Trigger</div>
@@ -18,28 +24,29 @@
Attach the event handler to any element:
-$( document ).ajaxStart(function() {
+$( document ).on( "ajaxStart", function() {
$( ".log" ).text( "Triggered ajaxStart handler." );
-});
+} );
Now, make an Ajax request using any jQuery method:
-$( ".trigger" ).click(function() {
+$( ".trigger" ).on( "click", function() {
$( ".result" ).load( "ajax/test.html" );
-});
+} );
When the user clicks the element with class trigger and the Ajax request is sent, the log message is displayed.
This API is deprecated. Use .on( "ajaxStop", handler ) instead.
"ajaxStop".Whenever an Ajax request completes, jQuery checks whether there are any other outstanding Ajax requests. If none remain, jQuery triggers the ajaxStop event. Any and all handlers that have been registered with the .ajaxStop() method are executed at this time. The ajaxStop event is also triggered if the last outstanding Ajax request is cancelled by returning false within the beforeSend callback function.
This page describes the ajaxStop event. For the deprecated .ajaxStop() method, see .ajaxStop().
Whenever an Ajax request completes, jQuery checks whether there are any other outstanding Ajax requests. If none remain, jQuery triggers the ajaxStop event. Any and all registered ajaxStop handlers are executed at this time. The ajaxStop event is also triggered if the last outstanding Ajax request is cancelled by returning false within the beforeSend callback function.
To observe this method in action, set up a basic Ajax load request:
<div class="trigger">Trigger</div>
@@ -18,28 +24,29 @@
Attach the event handler to the document:
-$( document ).ajaxStop(function() {
+$( document ).on( "ajaxStop", function() {
$( ".log" ).text( "Triggered ajaxStop handler." );
-});
+} );
Now, make an Ajax request using any jQuery method:
-$( ".trigger" ).click(function() {
+$( ".trigger" ).on( "click", function() {
$( ".result" ).load( "ajax/test.html" );
-});
+} );
When the user clicks the element with class trigger and the Ajax request completes, the log message is displayed.
This API is deprecated. Use .on( "ajaxSuccess", handler ) instead.
"ajaxSuccess".Whenever an Ajax request completes successfully, jQuery triggers the ajaxSuccess event. Any and all handlers that have been registered with the .ajaxSuccess() method are executed at this time.
This page describes the ajaxSuccess event. For the deprecated .ajaxSuccess() method, see .ajaxSuccess().
Whenever an Ajax request completes successfully, jQuery triggers the ajaxSuccess event. Any and all registered ajaxSuccess handlers are executed at this time.
To observe this method in action, set up a basic Ajax load request:
<div class="trigger">Trigger</div>
@@ -22,38 +28,39 @@
Attach the event handler to any element:
-$(document).ajaxSuccess(function() {
+$( document ).on( "ajaxSuccess", function() {
$( ".log" ).text( "Triggered ajaxSuccess handler." );
-});
+} );
Now, make an Ajax request using any jQuery method:
$( ".trigger" ).on( "click", function() {
$( ".result" ).load( "ajax/test.html" );
-});
+} );
When the user clicks the element with class trigger and the Ajax request completes successfully, the log message is displayed.
All ajaxSuccess handlers are invoked, regardless of what Ajax request was completed. If you must differentiate between the requests, you can use the parameters passed to the handler. Each time an ajaxSuccess handler is executed, it is passed the event object, the XMLHttpRequest object, and the settings object that was used in the creation of the request. For example, you can restrict the callback to only handling events dealing with a particular URL:
-$( document ).ajaxSuccess(function( event, xhr, settings ) {
+$( document ).on( "ajaxSuccess", function( event, xhr, settings ) {
if ( settings.url == "ajax/test.html" ) {
$( ".log" ).text( "Triggered ajaxSuccess handler. The Ajax response was: " +
xhr.responseText );
}
-});
+} );
Note: You can get the returned Ajax contents by looking at xhr.responseXML or xhr.responseText for xml and html respectively.
Note: This function has been deprecated and is now an alias for .addBack(), which should be used with jQuery 1.8 and later.
As described in the discussion for .end(), jQuery objects maintain an internal stack that keeps track of changes to the matched set of elements. When one of the DOM traversal methods is called, the new set of elements is pushed onto the stack. If the previous set of elements is desired as well, .andSelf() can help.
Consider a page with a simple list on it:
-
-<ul>
- <li>list item 1</li>
- <li>list item 2</li>
- <li class="third-item">list item 3</li>
- <li>list item 4</li>
- <li>list item 5</li>
-</ul>
- The result of the following code is a red background behind items 3, 4 and 5:
-
-$( "li.third-item" ).nextAll().andSelf()
- .css( "background-color", "red" );
- First, the initial selector locates item 3, initializing the stack with the set containing just this item. The call to .nextAll() then pushes the set of items 4 and 5 onto the stack. Finally, the .andSelf() invocation merges these two sets together, creating a jQuery object that points to all three items in document order: [ <li.third-item>, <li>, <li> ].
Note: This API has been removed in jQuery 3.0; use .addBack() instead, which should work identically.
.andSelf() method causes the previous set of DOM elements in the traversal stack to be added to the current set. In the first example, the top stack contains the set resulting from .find("p"). In the second example, .andSelf() adds the previous set of elements on the stack — in this case $( "div.after-andself" ) — to the current set, selecting both the div and its enclosed paragraphs.To animate the opacity, left offset, and height of the image simultaneously:
-$( "#clickme" ).click(function() {
+$( "#clickme" ).on( "click", function() {
$( "#book" ).animate({
opacity: 0.25,
left: "+=50",
@@ -72,10 +72,10 @@ $( "#clickme" ).click(function() {
The opacity of the image is already at its target value, so this property is not animated by the second click. Since the target value for left is a relative value, the image moves even farther to the right during this second animation.
Directional properties (top, right, bottom, left) have no discernible effect on elements if their position style property is static, which it is by default.
- Note: The jQuery UI project extends the .animate() method by allowing some non-numeric styles such as colors to be animated. The project also includes mechanisms for specifying animations through CSS classes rather than individual attributes.
+ Note: The jQuery UI project extends the .animate() method by allowing some non-numeric styles such as colors to be animated. The project also includes mechanisms for specifying animations through CSS classes rather than individual attributes.
- Note: if attempting to animate an element with a height or width of 0px, where contents of the element are visible due to overflow, jQuery may clip this overflow during animation. By fixing the dimensions of the original element being hidden however, it is possible to ensure that the animation runs smoothly. A clearfix can be used to automatically fix the dimensions of your main element without the need to set this manually.
+ Note: if attempting to animate an element with a height or width of 0px, where contents of the element are visible due to overflow, jQuery may clip this overflow during animation. By fixing the dimensions of the original element being hidden however, it is possible to ensure that the animation runs smoothly. A clearfix can be used to automatically fix the dimensions of your main element without the need to set this manually.
Step Function
The second version of .animate() provides a step option — a callback function that is fired at each step of the animation. This function is useful for enabling custom animation types or altering the animation as it is occurring. It accepts two arguments (now and fx), and this is set to the DOM element being animated.
@@ -96,12 +96,12 @@ $( "li" ).animate({
});
The remaining parameter of .animate() is a string naming an easing function to use. An easing function specifies the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called swing, and one that progresses at a constant pace, called linear. More easing functions are available with the use of plug-ins, most notably the jQuery UI suite.
The remaining parameter of .animate() is a string naming an easing function to use. An easing function specifies the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called swing, and one that progresses at a constant pace, called linear. More easing functions are available with the use of plug-ins, most notably the jQuery UI suite.
As of jQuery version 1.4, you can set per-property easing functions within a single .animate() call. In the first version of .animate(), each property can take an array as its value: The first member of the array is the CSS property and the second member is an easing function. If a per-property easing function is not defined for a particular property, it uses the value of the .animate() method's optional easing argument. If the easing argument is not defined, the default swing function is used.
For example, to simultaneously animate the width and height with the swing easing function and the opacity with the linear easing function:
-$( "#clickme" ).click(function() {
+$( "#clickme" ).on( "click", function() {
$( "#book" ).animate({
width: [ "toggle", "swing" ],
height: [ "toggle", "swing" ],
@@ -113,7 +113,7 @@ $( "#clickme" ).click(function() {
In the second version of .animate(), the options object can include the specialEasing property, which is itself an object of CSS properties and their corresponding easing functions. For example, to simultaneously animate the width using the linear easing function and the height using the easeOutBounce easing function:
-$( "#clickme" ).click(function() { +$( "#clickme" ).on( "click", function() { $( "#book" ).animate({ width: "toggle", height: "toggle" @@ -137,7 +137,7 @@ $( "#clickme" ).click(function() {diff --git a/entries/blur-shorthand.xml b/entries/blur-shorthand.xml new file mode 100644 index 000000000..589a1cebb --- /dev/null +++ b/entries/blur-shorthand.xml @@ -0,0 +1,37 @@ + +@@ -191,7 +191,7 @@ $( "#left" ).click(function(){ The second button starts a traditional chained animation, where each animation will start once the previous animation on the element has completed.+ diff --git a/entries/blur.xml b/entries/blur.xml index 11afbd6ab..68636a0ce 100644 --- a/entries/blur.xml +++ b/entries/blur.xml @@ -1,16 +1,15 @@ -.blur() +Bind an event handler to the "blur" 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
+.blur( handler )or.blur( eventData, handler ), use.on( "blur", handler )or.on( "blur", eventData, handler ), respectively.Instead of
+.blur(), use.trigger( "blur" ).+ + + + + - + +.blur() -Bind an event handler to the "blur" JavaScript event, or trigger that event on an element. ++ + diff --git a/entries/button-selector.xml b/entries/button-selector.xml index 858522e5c..12c8471cd 100644 --- a/entries/button-selector.xml +++ b/entries/button-selector.xml @@ -16,9 +16,9 @@ var input = $( ":button" ).addClass( "marked" ); $( "div" ).text( "For this type jQuery found " + input.length + "." ); // Prevent the form from submitting -$( "form" ).submit(function( event ) { +$( "form" ).on( "submit", function( event ) { event.preventDefault(); -}); +} ); ]]>Bind an event handler to the "blur" event, or trigger that event on an element. ++ + +blur event +Bind an event handler to the "blur" event. - -1.0 -- A function to execute each time the event is triggered. -+ 1.7 ++ -The string "blur".- -1.4.3 @@ -19,11 +18,10 @@ An object containing data that will be passed to the event handler. - 1.0 -- -This method is a shortcut for
+.on( "blur", handler )in the first two variations, and.trigger( "blur" )in the third.+This page describes the
+blurevent. For the deprecated.blur()method, see.blur().The
blurevent is sent to an element when it loses focus. Originally, this event was only applicable to form elements, such as<input>. In recent browsers, the domain of the event has been extended to include all element types. An element can lose focus via keyboard commands, such as the Tab key, or by mouse clicks elsewhere on the page.For example, consider the HTML:
+@@ -34,33 +32,55 @@ <div id="other"> Trigger the handler </div> -The event handler can be bound to the first input field: -$( "#target" ).blur(function() { - alert( "Handler for .blur() called." ); -}); +The event handler can be bound to the first input field:
++$( "#target" ).on( "blur", function() { + alert( "Handler for `blur` called." ); +} );Now if the first field has the focus, clicking elsewhere or tabbing away from it displays the alert:
- Handler for .blur() called. + Handler for `blur` called.
-To trigger the event programmatically, apply
+.blur()without an argument:To trigger the event programmatically, call
.trigger( "blur" ):-$( "#other" ).click(function() { - $( "#target" ).blur(); -}); +$( "#other" ).on( "click", function() { + $( "#target" ).trigger( "blur" ); +} );After this code executes, clicks on Trigger the handler will also alert the message.
-The
+blurevent does not bubble in Internet Explorer. Therefore, scripts that rely on event delegation with theblurevent will not work consistently across browsers. As of version 1.4.2, however, jQuery works around this limitation by mappingblurto thefocusoutevent in its event delegation methods,.live()and.delegate().The
+blurevent does not bubble. As of version 1.4.2, jQuery works around this limitation by mappingblurto thefocusoutevent in its event delegation methods.The native
blurevent is asynchronous in all versions of IE, contrary to other browsers. To avoid issues related to this discrepancy, as of jQuery 3.7.0, jQuery usesfocusoutas the native backing event forblurin IE.To trigger the blur event on all paragraphs: - + + + + + +blur event +Trigger the "blur" event on an element. ++ +1.0 ++ +The string +"blur".+ +See the description for
+.on( "blur", ... ).+ + - + + + + + diff --git a/entries/checkbox-selector.xml b/entries/checkbox-selector.xml index 843cdaf77..ba0fd815d 100644 --- a/entries/checkbox-selector.xml +++ b/entries/checkbox-selector.xml @@ -26,9 +26,9 @@ $( "div" ) .css( "color", "red" ); // Prevent the form from submitting -$( "form" ).submit(function( event ) { +$( "form" ).on( "submit", function( event ) { event.preventDefault(); -}); +} ); ]]>change event +Trigger the "change" event on an element. ++ +1.0 ++ +The string +"change".+ +See the description for
+.on( "change", ... ).+