Skip to content

Commit c149300

Browse files
mgolmgol
authored
All: Mark event aliases as deprecated
Mark all event shorthands as deprecated, including the AJAX ones. Create separate pages for deprecated shorthands, for example: * `/click/` describes the `click` event and how to use it with `.on()` or `.trigger()` * `/click-shorthand/` describes the deprecated `.click()` method * `/ajaxStart/` describes the `ajaxStart` event and how to use it with `.on()` * `/ajaxStart-shorthand/` describes the deprecated `.ajaxStart()` method The reason for such an approach is that event pages often contained useful information about those specific events and we didn't want to lose that. Also, the new shorthand pages all look the same and mostly redirect to the event pages so we didn't want to treat them as the primary page to go to when searching for an event. To make it less confusing, both the event page & its associated shorthand method page link to each other. Separate shorthand pages have also been created for `.load()`, `.unload()` and `.error()` methods. Those methods have already been removed in jQuery 3.0 but they also contained useful info about the associated events so it made sense to treat them like other event shorthands. Because there's no way to include both `.on()` & `.trigger()` usage in a single entry, event pages (except for AJAX ones) now have two entries each. This required wrapping the previous single `<entry>` with the new `<entries>`. To maintain Git history, the inner `<entry>` tags are left de-indented. Usage of deprecated event shorthand methods have been removed across all API entries. Fixes gh-1205 Closes gh-1223
1 parent 56301c1 commit c149300

File tree

159 files changed

+2497
-1042
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

159 files changed

+2497
-1042
lines changed

Diff for: ‎entries/ajaxComplete-shorthand.xml

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<?xml version="1.0"?>
2+
<entry type="method" name="ajaxComplete" return="jQuery" deprecated="3.3">
3+
<title>.ajaxComplete()</title>
4+
<desc>Register a handler to be called when Ajax requests complete. This is an <a href="/Ajax_Events/">AjaxEvent</a>.</desc>
5+
<signature>
6+
<added>1.0</added>
7+
<argument name="handler" type="Function">
8+
<desc>The function to be invoked.</desc>
9+
</argument>
10+
</signature>
11+
<longdesc>
12+
<div class="warning">
13+
<p>This API is deprecated. Use <a href="/ajaxComplete/"><code>.on( "ajaxComplete", handler )</code></a> instead.</p>
14+
</div>
15+
</longdesc>
16+
<category slug="ajax/global-ajax-event-handlers"/>
17+
<category slug="version/1.0"/>
18+
<category slug="deprecated/deprecated-3.3"/>
19+
</entry>

Diff for: ‎entries/ajaxComplete.xml

+22-15
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,24 @@
11
<?xml version="1.0"?>
2-
<entry type="method" name="ajaxComplete" return="jQuery">
3-
<title>.ajaxComplete()</title>
2+
<entry type="method" name="on" return="jQuery">
3+
<title>ajaxComplete event</title>
4+
<desc>Register a handler to be called when Ajax requests complete. This is an <a href="/Ajax_Events/">AjaxEvent</a>.</desc>
45
<signature>
5-
<added>1.0</added>
6+
<added>1.7</added>
7+
<argument name="&quot;ajaxComplete&quot;" type="string">
8+
<desc>The string <code>"ajaxComplete"</code>.</desc>
9+
</argument>
610
<argument name="handler" type="Function">
711
<argument name="event" type="Event" />
812
<argument name="jqXHR" type="jqXHR" />
913
<argument name="ajaxOptions" type="PlainObject" />
1014
<desc>The function to be invoked.</desc>
1115
</argument>
1216
</signature>
13-
<desc>Register a handler to be called when Ajax requests complete. This is an <a href="/Ajax_Events/">AjaxEvent</a>.</desc>
1417
<longdesc>
15-
<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>
18+
<div class="warning">
19+
<p>This page describes the <code>ajaxComplete</code> event. For the deprecated <code>.ajaxComplete()</code> method, see <a href="/ajaxComplete-shorthand/"><code>.ajaxComplete()</code></a>.</p>
20+
</div>
21+
<p>Whenever an Ajax request completes, jQuery triggers the <code>ajaxComplete</code> event. Any and all registered <code>ajaxComplete</code> handlers are executed at this time.</p>
1622
<p>To observe this method in action, set up a basic Ajax load request:</p>
1723
<pre><code>
1824
&lt;div class="trigger"&gt;Trigger&lt;/div&gt;
@@ -21,38 +27,39 @@
2127
</code></pre>
2228
<p>Attach the event handler to the document:</p>
2329
<pre><code>
24-
$( document ).ajaxComplete(function() {
30+
$( document ).on( "ajaxComplete", function() {
2531
$( ".log" ).text( "Triggered ajaxComplete handler." );
26-
});
32+
} );
2733
</code></pre>
2834
<p>Now, make an Ajax request using any jQuery method:</p>
2935
<pre><code>
30-
$( ".trigger" ).click(function() {
36+
$( ".trigger)" ).on( "click", function() {
3137
$( ".result" ).load( "ajax/test.html" );
32-
});
38+
} );
3339
</code></pre>
3440
<p>When the user clicks the element with class <code>trigger</code> and the Ajax request completes, the log message is displayed.</p>
3541
<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>
3642
<pre><code>
37-
$( document ).ajaxComplete(function( event, xhr, settings ) {
43+
$( document ).on( "ajaxComplete", function( event, xhr, settings ) {
3844
if ( settings.url === "ajax/test.html" ) {
3945
$( ".log" ).text( "Triggered ajaxComplete handler. The result is " +
4046
xhr.responseText );
4147
}
42-
});
48+
} );
4349
</code></pre>
4450
<p><strong>Note:</strong> You can get the returned Ajax contents by looking at <code>xhr.responseText</code>.</p>
4551
</longdesc>
46-
<note id="global-ajax-event" type="additional" data-title=".ajaxComplete()"/>
47-
<note id="ajax-global-false" type="additional" data-title=".ajaxComplete()"/>
52+
<note id="global-ajax-event" type="additional" data-title="ajaxComplete"/>
53+
<note id="ajax-global-false" type="additional" data-title="ajaxComplete"/>
4854
<example>
4955
<desc>Show a message when an Ajax request completes.</desc>
5056
<code><![CDATA[
51-
$( document ).ajaxComplete(function( event, request, settings ) {
57+
$( document ).on( "ajaxComplete", function( event, request, settings ) {
5258
$( "#msg" ).append( "<li>Request Complete.</li>" );
53-
});
59+
} );
5460
]]></code>
5561
</example>
5662
<category slug="ajax/global-ajax-event-handlers"/>
5763
<category slug="version/1.0"/>
64+
<category slug="version/1.7"/>
5865
</entry>

Diff for: ‎entries/ajaxError-shorthand.xml

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<?xml version="1.0"?>
2+
<entry type="method" name="ajaxError" return="jQuery" deprecated="3.3">
3+
<title>.ajaxError()</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>
5+
<signature>
6+
<added>1.0</added>
7+
<argument name="handler" type="Function">
8+
<desc>The function to be invoked.</desc>
9+
</argument>
10+
</signature>
11+
<longdesc>
12+
<div class="warning">
13+
<p>This API is deprecated. Use <a href="/ajaxError/"><code>.on( "ajaxError", handler )</code></a> instead.</p>
14+
</div>
15+
</longdesc>
16+
<category slug="ajax/global-ajax-event-handlers"/>
17+
<category slug="version/1.0"/>
18+
<category slug="deprecated/deprecated-3.3"/>
19+
</entry>

Diff for: ‎entries/ajaxError.xml

+22-14
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
11
<?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>
45
<signature>
5-
<added>1.0</added>
6+
<added>1.7</added>
7+
<argument name="&quot;ajaxError&quot;" type="string">
8+
<desc>The string <code>"ajaxError"</code>.</desc>
9+
</argument>
610
<argument name="handler" type="Function">
711
<desc>The function to be invoked.</desc>
812
<argument name="event" type="Event" />
@@ -11,9 +15,11 @@
1115
<argument name="thrownError" type="String" />
1216
</argument>
1317
</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>
1518
<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>
1723
<p>To observe this method in action, set up a basic Ajax load request.</p>
1824
<pre><code>
1925
&lt;button class="trigger"&gt;Trigger&lt;/button&gt;
@@ -22,35 +28,37 @@
2228
</code></pre>
2329
<p>Attach the event handler to the document:</p>
2430
<pre><code>
25-
$( document ).ajaxError(function() {
31+
$( document ).on( "ajaxError", function() {
2632
$( ".log" ).text( "Triggered ajaxError handler." );
27-
});
33+
} );
2834
</code></pre>
2935
<p>Now, make an Ajax request using any jQuery method:</p>
3036
<pre><code>
3137
$( "button.trigger" ).on( "click", function() {
3238
$( "div.result" ).load( "ajax/missing.html" );
33-
});
39+
} );
3440
</code></pre>
3541
<p>When the user clicks the button and the Ajax request fails, because the requested file is missing, the log message is displayed.</p>
3642
<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>
3743
<pre><code>
38-
$( document ).ajaxError(function( event, jqxhr, settings, thrownError ) {
44+
$( document ).on( "ajaxError", function( event, jqxhr, settings, thrownError ) {
3945
if ( settings.url == "ajax/missing.html" ) {
4046
$( "div.log" ).text( "Triggered ajaxError handler." );
4147
}
42-
});</code></pre>
48+
} );
49+
</code></pre>
4350
</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"/>
4653
<example>
4754
<desc>Show a message when an Ajax request fails.</desc>
4855
<code><![CDATA[
49-
$( document ).ajaxError(function( event, request, settings ) {
56+
$( document ).on( "ajaxError", function( event, request, settings ) {
5057
$( "#msg" ).append( "<li>Error requesting page " + settings.url + "</li>" );
51-
});
58+
} );
5259
]]></code>
5360
</example>
5461
<category slug="ajax/global-ajax-event-handlers"/>
5562
<category slug="version/1.0"/>
63+
<category slug="version/1.7"/>
5664
</entry>

Diff for: ‎entries/ajaxSend-shorthand.xml

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<?xml version="1.0"?>
2+
<entry type="method" name="ajaxSend" return="jQuery" deprecated="3.3">
3+
<title>.ajaxSend()</title>
4+
<desc>Attach a function to be executed before an Ajax request is sent. This is an <a href="/Ajax_Events/">Ajax Event</a>.</desc>
5+
<signature>
6+
<added>1.0</added>
7+
<argument name="handler" type="Function">
8+
<desc>The function to be invoked.</desc>
9+
</argument>
10+
</signature>
11+
<longdesc>
12+
<div class="warning">
13+
<p>This API is deprecated. Use <a href="/ajaxSend/"><code>.on( "ajaxSend", handler )</code></a> instead.</p>
14+
</div>
15+
</longdesc>
16+
<category slug="ajax/global-ajax-event-handlers"/>
17+
<category slug="version/1.0"/>
18+
<category slug="deprecated/deprecated-3.3"/>
19+
</entry>

Diff for: ‎entries/ajaxSend.xml

+22-15
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,24 @@
11
<?xml version="1.0"?>
2-
<entry type="method" name="ajaxSend" return="jQuery">
3-
<title>.ajaxSend()</title>
2+
<entry type="method" name="on" return="jQuery">
3+
<title>ajaxSend event</title>
4+
<desc>Attach a function to be executed before an Ajax request is sent. This is an <a href="/Ajax_Events/">Ajax Event</a>.</desc>
45
<signature>
5-
<added>1.0</added>
6+
<added>1.7</added>
7+
<argument name="&quot;ajaxSend&quot;" type="string">
8+
<desc>The string <code>"ajaxSend"</code>.</desc>
9+
</argument>
610
<argument name="handler" type="Function">
711
<desc>The function to be invoked.</desc>
812
<argument name="event" type="Event" />
913
<argument name="jqXHR" type="jqXHR" />
1014
<argument name="ajaxOptions" type="PlainObject" />
1115
</argument>
1216
</signature>
13-
<desc>Attach a function to be executed before an Ajax request is sent. This is an <a href="/Ajax_Events/">Ajax Event</a>.</desc>
1417
<longdesc>
15-
<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>
18+
<div class="warning">
19+
<p>This page describes the <code>ajaxSend</code> event. For the deprecated <code>.ajaxSend()</code> method, see <a href="/ajaxSend-shorthand/"><code>.ajaxSend()</code></a>.</p>
20+
</div>
21+
<p>Whenever an Ajax request is about to be sent, jQuery triggers the <code>ajaxSend</code> event. Any and all registerd <code>ajaxSend</code> handlers are executed at this time.</p>
1622
<p>To observe this method in action, set up a basic Ajax load request:</p>
1723
<pre><code>
1824
&lt;div class="trigger"&gt;Trigger&lt;/div&gt;
@@ -21,36 +27,37 @@
2127
</code></pre>
2228
<p>Attach the event handler to the document:</p>
2329
<pre><code>
24-
$( document ).ajaxSend(function() {
30+
$( document ).on( "ajaxSend", function() {
2531
$( ".log" ).text( "Triggered ajaxSend handler." );
26-
});
32+
} );
2733
</code></pre>
2834
<p>Now, make an Ajax request using any jQuery method:</p>
2935
<pre><code>
30-
$( ".trigger" ).click(function() {
36+
$( ".trigger)" ).on( "click", function() {
3137
$( ".result" ).load( "ajax/test.html" );
32-
});
38+
} );
3339
</code></pre>
3440
<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>
3541
<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="/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>
3642
<pre><code>
37-
$( document ).ajaxSend(function( event, jqxhr, settings ) {
43+
$( document ).on( "ajaxSend", function( event, jqxhr, settings ) {
3844
if ( settings.url == "ajax/test.html" ) {
3945
$( ".log" ).text( "Triggered ajaxSend handler." );
4046
}
41-
});
47+
} );
4248
</code></pre>
4349
</longdesc>
44-
<note id="global-ajax-event" type="additional" data-title=".ajaxSend()"/>
45-
<note id="ajax-global-false" type="additional" data-title=".ajaxSend()"/>
50+
<note id="global-ajax-event" type="additional" data-title="ajaxSend"/>
51+
<note id="ajax-global-false" type="additional" data-title="ajaxSend"/>
4652
<example>
4753
<desc>Show a message before an Ajax request is sent.</desc>
4854
<code><![CDATA[
49-
$( document ).ajaxSend(function( event, request, settings ) {
55+
$( document ).on( "ajaxSend", function( event, request, settings ) {
5056
$( "#msg" ).append( "<li>Starting request at " + settings.url + "</li>" );
51-
});
57+
} );
5258
]]></code>
5359
</example>
5460
<category slug="ajax/global-ajax-event-handlers"/>
5561
<category slug="version/1.0"/>
62+
<category slug="version/1.7"/>
5663
</entry>

Diff for: ‎entries/ajaxStart-shorthand.xml

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<?xml version="1.0"?>
2+
<entry type="method" name="ajaxStart" return="jQuery" deprecated="3.3">
3+
<title>.ajaxStart()</title>
4+
<desc>Register a handler to be called when the first Ajax request begins. This is an <a href="/Ajax_Events/">Ajax Event</a>.</desc>
5+
<signature>
6+
<added>1.0</added>
7+
<argument name="handler" type="Function">
8+
<desc>The function to be invoked.</desc>
9+
</argument>
10+
</signature>
11+
<longdesc>
12+
<div class="warning">
13+
<p>This API is deprecated. Use <a href="/ajaxStart/"><code>.on( "ajaxStart", handler )</code></a> instead.</p>
14+
</div>
15+
</longdesc>
16+
<category slug="ajax/global-ajax-event-handlers"/>
17+
<category slug="version/1.0"/>
18+
<category slug="deprecated/deprecated-3.3"/>
19+
</entry>

Diff for: ‎entries/ajaxStart.xml

+20-13
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,21 @@
11
<?xml version="1.0"?>
2-
<entry type="method" name="ajaxStart" return="jQuery">
3-
<title>.ajaxStart()</title>
2+
<entry type="method" name="on" return="jQuery">
3+
<title>ajaxStart event</title>
4+
<desc>Register a handler to be called when the first Ajax request begins. This is an <a href="/Ajax_Events/">Ajax Event</a>.</desc>
45
<signature>
5-
<added>1.0</added>
6+
<added>1.7</added>
7+
<argument name="&quot;ajaxStart&quot;" type="string">
8+
<desc>The string <code>"ajaxStart"</code>.</desc>
9+
</argument>
610
<argument name="handler" type="Function">
711
<desc>The function to be invoked.</desc>
812
</argument>
913
</signature>
10-
<desc>Register a handler to be called when the first Ajax request begins. This is an <a href="/Ajax_Events/">Ajax Event</a>.</desc>
1114
<longdesc>
12-
<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>
15+
<div class="warning">
16+
<p>This page describes the <code>ajaxStart</code> event. For the deprecated <code>.ajaxStart()</code> method, see <a href="/ajaxStart-shorthand/"><code>.ajaxStart()</code></a>.</p>
17+
</div>
18+
<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 <code>.on( "ajaxStart", ... )</code> are executed at this time.</p>
1319
<p>To observe this method in action, set up a basic Ajax load request:</p>
1420
<pre><code>
1521
&lt;div class="trigger"&gt;Trigger&lt;/div&gt;
@@ -18,28 +24,29 @@
1824
</code></pre>
1925
<p>Attach the event handler to any element:</p>
2026
<pre><code>
21-
$( document ).ajaxStart(function() {
27+
$( document ).on( "ajaxStart", function() {
2228
$( ".log" ).text( "Triggered ajaxStart handler." );
23-
});
29+
} );
2430
</code></pre>
2531
<p>Now, make an Ajax request using any jQuery method:</p>
2632
<pre><code>
27-
$( ".trigger" ).click(function() {
33+
$( ".trigger" ).on( "click", function() {
2834
$( ".result" ).load( "ajax/test.html" );
29-
});
35+
} );
3036
</code></pre>
3137
<p>When the user clicks the element with class <code>trigger</code> and the Ajax request is sent, the log message is displayed.</p>
3238
</longdesc>
33-
<note id="global-ajax-event" type="additional" data-title=".ajaxStart()"/>
34-
<note id="ajax-global-false" type="additional" data-title=".ajaxStart()"/>
39+
<note id="global-ajax-event" type="additional" data-title="ajaxStart"/>
40+
<note id="ajax-global-false" type="additional" data-title="ajaxStart"/>
3541
<example>
3642
<desc>Show a loading message whenever an Ajax request starts (and none is already active).</desc>
3743
<code><![CDATA[
38-
$( document ).ajaxStart(function() {
44+
$( document ).on( "ajaxStart", function() {
3945
$( "#loading" ).show();
40-
});
46+
} );
4147
]]></code>
4248
</example>
4349
<category slug="ajax/global-ajax-event-handlers"/>
4450
<category slug="version/1.0"/>
51+
<category slug="version/1.7"/>
4552
</entry>

Diff for: ‎entries/ajaxStop-shorthand.xml

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<?xml version="1.0"?>
2+
<entry type="method" name="ajaxStop" return="jQuery" deprecated="3.3">
3+
<title>.ajaxStop()</title>
4+
<desc>Register a handler to be called when all Ajax requests have completed. This is an <a href="/Ajax_Events/">Ajax Event</a>.</desc>
5+
<signature>
6+
<added>1.0</added>
7+
<argument name="handler" type="Function">
8+
<desc>The function to be invoked.</desc>
9+
</argument>
10+
</signature>
11+
<longdesc>
12+
<div class="warning">
13+
<p>This API is deprecated. Use <a href="/ajaxStop/"><code>.on( "ajaxStop", handler )</code></a> instead.</p>
14+
</div>
15+
</longdesc>
16+
<category slug="ajax/global-ajax-event-handlers"/>
17+
<category slug="version/1.0"/>
18+
<category slug="deprecated/deprecated-3.3"/>
19+
</entry>

0 commit comments

Comments
 (0)