|
1 | 1 | <?xml version="1.0"?> |
2 | | -<entry type="method" name="ajaxError" return="jQuery"> |
3 | | - <title>.ajaxError()</title> |
| 2 | +<entry type="method" name="on" return="jQuery"> |
| 3 | + <title>ajaxError event</title> |
| 4 | + <desc>Register a handler to be called when Ajax requests complete with an error. This is an <a href="/Ajax_Events/">Ajax Event</a>.</desc> |
4 | 5 | <signature> |
5 | | - <added>1.0</added> |
| 6 | + <added>1.7</added> |
| 7 | + <argument name=""ajaxError"" type="string"> |
| 8 | + <desc>The string <code>"ajaxError"</code>.</desc> |
| 9 | + </argument> |
6 | 10 | <argument name="handler" type="Function"> |
7 | 11 | <desc>The function to be invoked.</desc> |
8 | 12 | <argument name="event" type="Event" /> |
|
11 | 15 | <argument name="thrownError" type="String" /> |
12 | 16 | </argument> |
13 | 17 | </signature> |
14 | | - <desc>Register a handler to be called when Ajax requests complete with an error. This is an <a href="/Ajax_Events/">Ajax Event</a>.</desc> |
15 | 18 | <longdesc> |
16 | | - <p>Whenever an Ajax request completes with an error, jQuery triggers the <code>ajaxError</code> event. Any and all handlers that have been registered with the <code>.ajaxError()</code> method are executed at this time. <strong>Note:</strong> <em>This handler is not called for cross-domain script and cross-domain JSONP requests.</em></p> |
| 19 | + <div class="warning"> |
| 20 | + <p>This page describes the <code>ajaxError</code> event. For the deprecated <code>.ajaxError()</code> method, see <a href="/ajaxError-shorthand/"><code>.ajaxError()</code></a>.</p> |
| 21 | + </div> |
| 22 | + <p>Whenever an Ajax request completes with an error, jQuery triggers the <code>ajaxError</code> event. Any and all registered <code>ajaxError</code> handlers are executed at this time. <strong>Note:</strong> <em>This handler is not called for cross-domain script and cross-domain JSONP requests.</em></p> |
17 | 23 | <p>To observe this method in action, set up a basic Ajax load request.</p> |
18 | 24 | <pre><code> |
19 | 25 | <button class="trigger">Trigger</button> |
|
22 | 28 | </code></pre> |
23 | 29 | <p>Attach the event handler to the document:</p> |
24 | 30 | <pre><code> |
25 | | -$( document ).ajaxError(function() { |
| 31 | +$( document ).on( "ajaxError", function() { |
26 | 32 | $( ".log" ).text( "Triggered ajaxError handler." ); |
27 | | -}); |
| 33 | +} ); |
28 | 34 | </code></pre> |
29 | 35 | <p>Now, make an Ajax request using any jQuery method:</p> |
30 | 36 | <pre><code> |
31 | 37 | $( "button.trigger" ).on( "click", function() { |
32 | 38 | $( "div.result" ).load( "ajax/missing.html" ); |
33 | | -}); |
| 39 | +} ); |
34 | 40 | </code></pre> |
35 | 41 | <p>When the user clicks the button and the Ajax request fails, because the requested file is missing, the log message is displayed.</p> |
36 | 42 | <p>All <code>ajaxError</code> 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 <code>ajaxError</code> handler is executed, it is passed the event object, the <code>jqXHR</code> object (prior to jQuery 1.5, the <code><abbr title="XMLHttpRequest">XHR</abbr></code> object), and the settings object that was used in the creation of the request. When an HTTP error occurs, the fourth argument (<code>thrownError</code>) 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:</p> |
37 | 43 | <pre><code> |
38 | | -$( document ).ajaxError(function( event, jqxhr, settings, thrownError ) { |
| 44 | +$( document ).on( "ajaxError", function( event, jqxhr, settings, thrownError ) { |
39 | 45 | if ( settings.url == "ajax/missing.html" ) { |
40 | 46 | $( "div.log" ).text( "Triggered ajaxError handler." ); |
41 | 47 | } |
42 | | -});</code></pre> |
| 48 | +} ); |
| 49 | + </code></pre> |
43 | 50 | </longdesc> |
44 | | - <note id="global-ajax-event" type="additional" data-title=".ajaxError()"/> |
45 | | - <note id="ajax-global-false" type="additional" data-title=".ajaxError()"/> |
| 51 | + <note id="global-ajax-event" type="additional" data-title="ajaxError"/> |
| 52 | + <note id="ajax-global-false" type="additional" data-title="ajaxError"/> |
46 | 53 | <example> |
47 | 54 | <desc>Show a message when an Ajax request fails.</desc> |
48 | 55 | <code><![CDATA[ |
49 | | -$( document ).ajaxError(function( event, request, settings ) { |
| 56 | +$( document ).on( "ajaxError", function( event, request, settings ) { |
50 | 57 | $( "#msg" ).append( "<li>Error requesting page " + settings.url + "</li>" ); |
51 | | -}); |
| 58 | +} ); |
52 | 59 | ]]></code> |
53 | 60 | </example> |
54 | 61 | <category slug="ajax/global-ajax-event-handlers"/> |
55 | 62 | <category slug="version/1.0"/> |
| 63 | + <category slug="version/1.7"/> |
56 | 64 | </entry> |
0 commit comments