8000 Note: Only attach global ajax events to document · connorcartwright/api.jquery.com@93388c9 · GitHub
Skip to content

Commit 93388c9

Browse files
kswedbergkswedberg
committed
Note: Only attach global ajax events to document
* Clean up code style * Fixes jquery#118

1 parent 2f66d1d commit 93388c9

6 files changed

Lines changed: 80 additions & 80 deletions

File tree

‎entries/ajaxComplete.xml‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -10,36 +10,36 @@
1010
<desc>Register a handler to be called when Ajax requests complete. This is an <a href="http://docs.jquery.com/Ajax_Events">AjaxEvent</a>.</desc>
1111
<longdesc>
1212
<p>Whenever an Ajax request completes, jQuery triggers the <code>ajaxComplete</code> event. Any and all handlers that have been registered with the <code>.ajaxComplete()</code> method are executed at this time.</p>
13-
<p>To observe this method in action, we can set up a basic Ajax load request:</p>
13+
<p>To observe this method in action, set up a basic Ajax load request:</p>
1414
<pre><code>&lt;div class="trigger"&gt;Trigger&lt;/div&gt;
1515
&lt;div class="result"&gt;&lt;/div&gt;
1616
&lt;div class="log"&gt;&lt;/div&gt;
1717
</code></pre>
18-
<p>We can attach our event handler to any element:</p>
19-
<pre><code>$('.log').ajaxComplete(function() {
20-
$(this).text('Triggered ajaxComplete handler.');
18+
<p>Attach the event handler to the document:</p>
19+
<pre><code>$(document).ajaxComplete(function() {
20+
$( ".log" ).text( "Triggered ajaxComplete handler." );
2121
});
2222
</code></pre>
23-
<p>Now, we can make an Ajax request using any jQuery method:</p>
24-
<pre><code>$('.trigger').click(function() {
25-
$('.result').load('ajax/test.html');
23+
<p>Now, make an Ajax request using any jQuery method:</p>
24+
<pre><code>$( ".trigger" ).click(function() {
25+
$( ".result" ).load( "ajax/test.html" );
2626
});</code></pre>
2727
<p>When the user clicks the element with class <code>trigger</code> and the Ajax request completes, the log message is displayed.</p>
28-
<p><strong>Note:</strong> Because <code>.ajaxComplete()</code> is implemented as a method of jQuery object instances, we can use the <code>this</code> keyword as we do here to refer to the selected elements within the callback function.</p>
29-
<p>All <code>ajaxComplete</code> handlers are invoked, regardless of what Ajax request was completed. If we must differentiate between the requests, we can use the parameters passed to the handler. Each time an <code>ajaxComplete</code> handler is executed, it is passed the event object, the <code>XMLHttpRequest</code> object, and the settings object that was used in the creation of the request. For example, we can restrict our callback to only handling events dealing with a particular URL:</p>
30-
<p><strong>Note:</strong> You can get the returned ajax contents by looking at <code>xhr.responseXML</code> or <code>xhr.responseHTML</code> for xml and html respectively.</p>
31-
<pre><code>$('.log').ajaxComplete(function(e, xhr, settings) {
32-
if (settings.url == 'ajax/test.html') {
33-
$(this).text('Triggered ajaxComplete handler. The result is ' +
34-
xhr.responseHTML);
28+
<p><strong>Note:</strong> Because <code>.ajaxComplete()</code> is implemented as a method of jQuery object instances, you can use the <code>this</code> keyword to refer to the selected elements within the callback function. <strong>As of jQuery 1.8, however, the <code>.ajaxComplete()</code> method should only be attached to <code>document</code>.</strong></p>
29+
<p>All <code>ajaxComplete</code> handlers are invoked, regardless of what Ajax request was completed. If you must differentiate between the requests, use the parameters passed to the handler. Each time an <code>ajaxComplete</code> handler is executed, it is passed the event object, the <code>XMLHttpRequest</code> 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:</p>
30+
<pre><code>$(document).ajaxComplete(function(event, xhr, settings) {
31+
if ( settings.url === "ajax/test.html" ) {
32+
$( ".log" ).text( "Triggered ajaxComplete handler. The result is " +
33+
xhr.responseHTML );
3534
}
3635
});</code></pre>
36+
<p><strong>Note:</strong> You can get the returned ajax contents by looking at <code>xhr.responseXML</code> or <code>xhr.responseHTML</code> for xml and html respectively.</p>
3737
</longdesc>
3838
<note id="ajax-global-false" type="additional" data-title=".ajaxComplete()"/>
3939
<example>
4040
<desc>Show a message when an Ajax request completes.</desc>
41-
<code><![CDATA[$("#msg").ajaxComplete(function(event,request, settings){
42-
$(this).append("<li>Request Complete.</li>");
41+
<code><![CDATA[$(document).ajaxComplete(function(event,request, settings) {
42+
$( "#msg" ).append( "<li>Request Complete.</li>" );
4343
});]]></code>
4444
</example>
4545
<category slug="ajax/global-ajax-event-handlers"/>

‎entries/ajaxError.xml‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -14,28 +14,28 @@
1414
<pre><code>&lt;button class="trigger"&gt;Trigger&lt;/button&gt;
1515
&lt;div class="result"&gt;&lt;/div&gt;
1616
&lt;div class="log"&gt;&lt;/div&gt;</code></pre>
17-
<p>Attach the event handler to any element:</p>
18-
<pre><code>$("div.log").ajaxError(function() {
19-
$(this).text( "Triggered ajaxError handler." );
17+
<p>Attach the event handler to the document:</p>
18+
<pre><code>$(document).ajaxError(function() {
19+
$( "div.log" ).text( "Triggered ajaxError handler." );
2020
});</code></pre>
2121
<p>Now, make an Ajax request using any jQuery method:</p>
22-
<pre><code>$("button.trigger").click(function() {
23-
$("div.result").load( "ajax/missing.html" );
22+
<pre><code>$( "button.trigger" ).click(function() {
23+
$( "div.result" ).load( "ajax/missing.html" );
2424
});</code></pre>
2525
<p>When the user clicks the button and the Ajax request fails, because the requested file is missing, the log message is displayed.</p>
26-
<p><strong>Note:</strong> Because <code>.ajaxError()</code> is implemented as a method of jQuery object instances, you can use the <code>this</code> keyword within the callback function to refer to the selected elements.</p>
27-
<p>All <code>ajaxError</code> handlers are invoked, regardless of what Ajax request was completed. To differentiate between the requests, you can 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. If the request failed because JavaScript raised an exception, the exception object is passed to the handler as a fourth parameter. For example, to restrict the error callback to only handling events dealing with a particular URL:</p>
28-
<pre><code>$( "div.log" ).ajaxError(function(e, jqxhr, settings, exception) {
26+
<p><strong>Note:</strong> Because <code>.ajaxError()</code> is implemented as a method of jQuery object instances, you can use the <code>this</code> keyword within the callback function to refer to the selected elements. <strong>As of jQuery 1.8, however, the <code>.ajaxError()</code> method should only be attached to <code>document</code>.</strong></p>
27+
<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. If the request failed because JavaScript raised an exception, the exception object is passed to the handler as a fourth parameter. For example, to restrict the error callback to only handling events dealing with a particular URL:</p>
28+
<pre><code>$( document ).ajaxError(function(event, jqxhr, settings, exception) {
2929
if ( settings.url == "ajax/missing.html" ) {
30-
$(this).text( "Triggered ajaxError handler." );
30+
$( "div.log" ).text( "Triggered ajaxError handler." );
3131
}
3232
});</code></pre>
3333
</longdesc>
3434
<note id="ajax-global-false" type="additional" data-title=".ajaxError()"/>
3535
<example>
3636
<desc>Show a message when an Ajax request fails.</desc>
37-
<code><![CDATA[$("#msg").ajaxError(function(event, request, settings){
38-
$(this).append("<li>Error requesting page " + settings.url + "</li>");
37+
<code><![CDATA[$(document).ajaxError(function(event, request, settings) {
38+
$( "#msg" ).append( "<li>Error requesting page " + settings.url + "</li>" );
3939
});]]></code>
4040
</example>
4141
<category slug="ajax/global-ajax-event-handlers"/>

‎entries/ajaxSend.xml‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -10,32 +10,32 @@
1010
<desc>Attach a function to be executed before an Ajax request is sent. This is an <a href='http://docs.jquery.com/Ajax_Events'>Ajax Event</a>.</desc>
1111
<longdesc>
1212
<p>Whenever an Ajax request is about to be sent, jQuery triggers the <code>ajaxSend</code> event. Any and all handlers that have been registered with the <code>.ajaxSend()</code> method are executed at this time.</p>
13-
<p>To observe this method in action, we can set up a basic Ajax load request:</p>
13+
<p>To observe this method in action, set up a basic Ajax load request:</p>
1414
<pre><code>&lt;div class="trigger"&gt;Trigger&lt;/div&gt;
1515
&lt;div class="result"&gt;&lt;/div&gt;
1616
&lt;div class="log"&gt;&lt;/div&gt;</code></pre>
17-
<p>We can attach our event handler to any element:</p>
18-
<pre><code>$('.log').ajaxSend(function() {
19-
$(this).text('Triggered ajaxSend handler.');
17+
<p>Attach the event handler to the document:</p>
18+
<pre><code>$(document).ajaxSend(function() {
19+
$( ".log" ).text( "Triggered ajaxSend handler." );
2020
});</code></pre>
21-
<p>Now, we can make an Ajax request using any jQuery method:</p>
22-
<pre><code>$('.trigger').click(function() {
23-
$('.result').load('ajax/test.html');
21+
<p>Now, make an Ajax request using any jQuery method:</p>
22+
<pre><code>$( ".trigger" ).click(function() {
23+
$( ".result" ).load( "ajax/test.html" );
2424
});</code></pre>
2525
<p>When the user clicks the element with class <code>trigger</code> and the Ajax request is about to begin, the log message is displayed.</p>
26-
<p><strong>Note:</strong> Because <code>.ajaxSend()</code> is implemented as a method of jQuery instances, we can use the <code>this</code> keyword as we do here to refer to the selected elements within the callback function.</p>
27-
<p>All <code>ajaxSend</code> handlers are invoked, regardless of what Ajax request is to be sent. If we must differentiate between the requests, we can use the parameters passed to the handler. Each time an <code>ajaxSend</code> handler is executed, it is passed the event object, the <code>jqXHR</code> object (in version 1.4, <code>XMLHttpRequest</code>object), and the <a href="http://api.jquery.com/jQuery.ajax/">settings object</a> that was used in the creation of the Ajax request. For example, we can restrict our callback to only handling events dealing with a particular URL:</p>
28-
<pre><code>$('.log').ajaxSend(function(e, jqxhr, settings) {
29-
if (settings.url == 'ajax/test.html') {
30-
$(this).text('Triggered ajaxSend handler.');
26+
<p><strong>Note:</strong> Because <code>.ajaxSend()</code> is implemented as a method of jQuery instances, you can use the <code>this</code> keyword to refer to the selected elements within the callback function. <strong>As of jQuery 1.8, however, the <code>.ajaxSend()</code> method should only be attached to <code>document</code>.</strong></p>
27+
<p>All <code>ajaxSend</code> 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 <code>ajaxSend</code> handler is executed, it is passed the event object, the <code>jqXHR</code> object (in version 1.4, <code>XMLHttpRequest</code>object), and the <a href="http://api.jquery.com/jQuery.ajax/">settings object</a> 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:</p>
28+
<pre><code>$(document).ajaxSend(function(event, jqxhr, settings) {
29+
if ( settings.url == "ajax/test.html" ) {
30+
$( ".log" ).text( "Triggered ajaxSend handler." );
3131
}
3232
});</code></pre>
3333
</longdesc>
3434
<note id="ajax-global-false" type="additional" data-title=".ajaxSend()"/>
3535
<example>
3636
<desc>Show a message before an Ajax request is sent.</desc>
37-
<code><![CDATA[$("#msg").ajaxSend(function(evt, request, settings){
38-
$(this).append("<li>Starting request at " + settings.url + "</li>");
37+
<code><![CDATA[$(document).ajaxSend(function(event, request, settings) {
38+
$( "#msg" ).append( "<li>Starting request at " + settings.url + "</li>" );
3939
});]]></code>
4040
</example>
4141
<category slug="ajax/global-ajax-event-handlers"/>

‎entries/ajaxStart.xml‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -7,29 +7,29 @@
77
<desc>The function to be invoked.</desc>
88
</argument>
99
</signature>
10-
<desc>Register a handler to be called when the first Ajax request begins. This is an <a href='http://docs.jquery.com/Ajax_Events'>Ajax Event</a>.</desc>
10+
<desc>Register a handler to be called when the first Ajax request begins. This is an <a href="http://docs.jquery.com/Ajax_Events">Ajax Event</a>.</desc>
1111
<longdesc>
1212
<p>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 <code>ajaxStart</code> event. Any and all handlers that have been registered with the <code>.ajaxStart()</code> method are executed at this time.</p>
13-
<p>To observe this method in action, we can set up a basic Ajax load request:</p>
13+
<p>To observe this method in action, set up a basic Ajax load request:</p>
1414
<pre><code>&lt;div class="trigger"&gt;Trigger&lt;/div&gt;
1515
&lt;div class="result"&gt;&lt;/div&gt;
1616
&lt;div class="log"&gt;&lt;/div&gt;</code></pre>
17-
<p>We can attach our event handler to any element:</p>
18-
<pre><code>$('.log').ajaxStart(function() {
19-
$(this).text('Triggered ajaxStart handler.');
17+
<p>Attach the event handler to any element:</p>
18+
<pre><code>$(document).ajaxStart(function() {
19+
$( ".log" ).text( "Triggered ajaxStart handler." );
2020
});</code></pre>
21-
<p>Now, we can make an Ajax request using any jQuery method:</p>
22-
<pre><code>$('.trigger').click(function() {
23-
$('.result').load('ajax/test.html');
21+
<p>Now, make an Ajax request using any jQuery method:</p>
22+
<pre><code>$( ".trigger" ).click(function() {
23+
$( ".result" ).load("ajax/test.html");
2424
});</code></pre>
2525
<p>When the user clicks the element with class <code>trigger</code> and the Ajax request is sent, the log message is displayed.</p>
26-
<p><strong>Note:</strong> Because <code>.ajaxStart()</code> is implemented as a method of jQuery object instances, we can use the <code>this</code> keyword as we do here to refer to the selected elements within the callback function.</p>
26+
<p><strong>Note:</strong> Because <code>.ajaxStart()</code> is implemented as a method of jQuery object instances, you can use the <code>this</code> keyword to refer to the selected elements within the callback function. <strong>As of jQuery 1.8, however, the <code>.ajaxStart()</code> method should only be attached to <code>document</code>.</strong></p>
2727
</longdesc>
2828
<note id="ajax-global-false" type="additional" data-title=".ajaxStart()"/>
2929
<example>
3030
<desc>Show a loading message whenever an Ajax request starts (and none is already active).</desc>
31-
<code><![CDATA[$("#loading").ajaxStart(function(){
32-
$(this).show();
31+
<code><![CDATA[$(document).ajaxStart(function() {
32+
$( "#loading" ).show();
3333
});]]></code>
3434
</example>
3535
<category slug="ajax/global-ajax-event-handlers"/>

‎entries/ajaxStop.xml‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<?xml version="1.0"?>
22
<entry type="method" name="ajaxStop" return="jQuery">
33
<title>.ajaxStop()</title>
4-
<desc>Register a handler to be called when all Ajax requests have completed. This is an <a href='http://docs.jquery.com/Ajax_Events'>Ajax Event</a>.</desc>
4+
<desc>Register a handler to be called when all Ajax requests have completed. This is an <a href="http://docs.jquery.com/Ajax_Events">Ajax Event</a>.</desc>
55
<signature>
66
<added>1.0</added>
77
<argument name="handler()" type="Function">
@@ -10,26 +10,26 @@
1010
</signature>
1111
<longdesc>
1212
<p>Whenever an Ajax request completes, jQuery checks whether there are any other outstanding Ajax requests. If none remain, jQuery triggers the <code>ajaxStop</code> event. Any and all handlers that have been registered with the <code>.ajaxStop()</code> method are executed at this time. The <code>ajaxStop</code> event is also triggered if the last outstanding Ajax request is cancelled by returning false within the <code>beforeSend</code> callback function. </p>
13-
<p>To observe this method in action, we can set up a basic Ajax load request:</p>
13+
<p>To observe this method in action, set up a basic Ajax load request:</p>
1414
<pre><code>&lt;div class="trigger"&gt;Trigger&lt;/div&gt;
1515
&lt;div class="result"&gt;&lt;/div&gt;
1616
&lt;div class="log"&gt;&lt;/div&gt;</code></pre>
17-
<p>We can attach our event handler to any element:</p>
18-
<pre><code>$('.log').ajaxStop(function() {
19-
$(this).text('Triggered ajaxStop handler.');
17+
<p>Attach the event handler to the document:</p>
18+
<pre><code>$( ".log" ).ajaxStop(function() {
19+
$(this).text( "Triggered ajaxStop handler." );
2020
});</code></pre>
21-
<p>Now, we can make an Ajax request using any jQuery method:</p>
22-
<pre><code>$('.trigger').click(function() {
23-
$('.result').load('ajax/test.html');
21+
<p>Now, make an Ajax request using any jQuery method:</p>
22+
<pre><code>$( ".trigger" ).click(function() {
23+
$( ".result" ).load( "ajax/test.html" );
2424
});</code></pre>
2525
<p>When the user clicks the element with class <code>trigger</code> and the Ajax request completes, the log message is displayed.</p>
26-
<p>Because <code>.ajaxStop()</code> is implemented as a method of jQuery object instances, we can use the <code>this</code> keyword as we do here to refer to the selected elements within the callback function.</p>
26+
<p>Because <code>.ajaxStop()</code> is implemented as a method of jQuery object instances, you can use the <code>this</code> keyword to refer to the selected elements within the callback function. <strong>As of jQuery 1.8, however, the <code>.ajaxStop()</code> method should only be attached to <code>document</code>.</strong></p>
2727
</longdesc>
2828
<note id="ajax-global-false" type="additional" data-title< 6CAF /span>=".ajaxStop()"/>
2929
<example>
3030
<desc>Hide a loading message after all the Ajax requests have stopped.</desc>
31-
<code><![CDATA[$("#loading").ajaxStop(function(){
32-
$(this).hide();
31+
<code><![CDATA[$(document).ajaxStop(function() {
32+
$( "#loading" ).hide();
3333
});]]></code>
3434
</example>
3535
<category slug="ajax/global-ajax-event-handlers"/>

0 commit comments

Comments
 (0)