Skip to content

Commit b1acff3

Browse files
mgolmgol
committed
ajaxStart: Mark the shorthand method as deprecated
1 parent 8afd090 commit b1acff3

2 files changed

Lines changed: 68 additions & 45 deletions

File tree

‎entries/ajaxStart.xml‎

Lines changed: 66 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,68 @@
11
<?xml version="1.0"?>
2-
<entry type="method" name="ajaxStart" return="jQuery">
3-
<title>.ajaxStart()</title>
4-
<signature>
5-
<added>1.0</added>
6-
<argument name="handler" type="Function">
7-
<desc>The function to be invoked.</desc>
8-
</argument>
9-
</signature>
2+
<entries>
103
<desc>Register a handler to be called when the first Ajax request begins. This is an <a href="/Ajax_Events/">Ajax Event</a>.</desc>
11-
<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>
13-
<p>To observe this method in action, set up a basic Ajax load request:</p>
14-
<pre><code>
15-
&lt;div class="trigger"&gt;Trigger&lt;/div&gt;
16-
&lt;div class="result"&gt;&lt;/div&gt;
17-
&lt;div class="log"&gt;&lt;/div&gt;
18-
</code></pre>
19-
<p>Attach the event handler to any element:</p>
20-
<pre><code>
21-
$( document ).ajaxStart(function() {
22-
$( ".log" ).text( "Triggered ajaxStart handler." );
23-
});
24-
</code></pre>
25-
<p>Now, make an Ajax request using any jQuery method:</p>
26-
<pre><code>
27-
$( ".trigger" ).click(function() {
28-
$( ".result" ).load( "ajax/test.html" );
29-
});
30-
</code></pre>
31-
<p>When the user clicks the element with class <code>trigger</code> and the Ajax request is sent, the log message is displayed.</p>
32-
</longdesc>
33-
<note id="global-ajax-event" type="additional" data-title=".ajaxStart()"/>
34-
<note id="ajax-global-false" type="additional" data-title=".ajaxStart()"/>
35-
<example>
36-
<desc>Show a loading message whenever an Ajax request starts (and none is already active).</desc>
37-
<code><![CDATA[
38-
$( document ).ajaxStart(function() {
39-
$( "#loading" ).show();
40-
});
41-
]]></code>
42-
</example>
43-
<category slug="ajax/global-ajax-event-handlers"/>
44-
<category slug="version/1.0"/>
45-
</entry>
4+
<entry type="method" name="on" return="jQuery">
5+
<title>ajaxStart event</title>
6+
<signature>
7+
<added>1.7</added>
8+
<argument name="&quot;ajaxStart&quot;" type="string">
9+
<desc>The string <code>"ajaxStart"</code>.</desc>
10+
</argument>
11+
<argument name="handler" type="Function">
12+
<desc>The function to be invoked.</desc>
13+
</argument>
14+
</signature>
15+
<longdesc>
16+
<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>
17+
<p>To observe this method in action, set up a basic Ajax load request:</p>
18+
<pre><code>
19+
&lt;div class="trigger"&gt;Trigger&lt;/div&gt;
20+
&lt;div class="result"&gt;&lt;/div&gt;
21+
&lt;div class="log"&gt;&lt;/div&gt;
22+
</code></pre>
23+
<p>Attach the event handler to any element:</p>
24+
<pre><code>
25+
$( document ).on( "ajaxStart", function() {
26+
$( ".log" ).text( "Triggered ajaxStart handler." );
27+
} );
28+
</code></pre>
29+
<p>Now, make an Ajax request using any jQuery method:</p>
30+
<pre><code>
31+
$( ".trigger" ).on( "click", function() {
32+
$( ".result" ).load( "ajax/test.html" );
33+
} );
34+
</code></pre>
35+
<p>When the user clicks the element with class <code>trigger</code> and the Ajax request is sent, the log message is displayed.</p>
36+
</longdesc>
37+
<note id="global-ajax-event" type="additional" data-title="ajaxStart"/>
38+
<note id="ajax-global-false" type="additional" data-title="ajaxStart"/>
39+
<example>
40+
<desc>Show a loading message whenever an Ajax request starts (and none is already active).</desc>
41+
<code><![CDATA[
42+
$( document ).on( "ajaxStart", function() {
43+
$( "#loading" ).show();
44+
} );
45+
]]></code>
46+
</example>
47+
<category slug="ajax/global-ajax-event-handlers"/>
48+
<category slug="version/1.0"/>
49+
</entry>
50+
51+
<entry type="method" name="ajaxStart" return="jQuery" deprecated="3.3">
52+
<title>.ajaxStart()</title>
53+
<signature>
54+
<added>1.0</added>
55+
<argument name="handler" type="Function">
56+
<desc>The function to be invoked.</desc>
57+
</argument>
58+
</signature>
59+
<longdesc>
60+
<div class="warning">
61+
<p>This API is deprecated. Use <a href="#on1"><code>.on( "ajaxStart", handler )</code></a> instead.</p>
62+
</div>
63+
</longdesc>
64+
<category slug="ajax/global-ajax-event-handlers"/>
65+
<category slug="version/1.0"/>
66+
<category slug="deprecated/deprecated-3.3"/>
67+
</entry>
68+
</entries>

‎notes.xsl‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@
5353
If a request with <xsl:value-of select="@data-title"/> returns an error code, it will fail silently unless the script has also called the global <a href="/ajaxError/">.ajaxError() </a> method. Alternatively, as of jQuery 1.5, the <code>.error()</code> method of the <code>jqXHR</code> object returned by <xsl:value-of select="@data-title"/> is also available for error handling.
5454
</xsl:when>
5555
<xsl:when test="@id = 'ajax-global-false'">
56-
If <code><a href="/jQuery.Ajax/">$.ajax()</a></code> or <code><a href="/jQuery.ajaxSetup/">$.ajaxSetup()</a></code> is called with the <code>global</code> option set to <code>false</code>, the <code><xsl:value-of select="@data-title"/></code> method will not fire.
56+
If <code><a href="/jQuery.Ajax/">$.ajax()</a></code> or <code><a href="/jQuery.ajaxSetup/">$.ajaxSetup()</a></code> is called with the <code>global</code> option set to <code>false</code>, the <code><xsl:value-of select="@data-title"/></code> event will not fire.
5757
</xsl:when>
5858
<xsl:when test="@id = 'slide-in-ie'">
5959
If <code><xsl:value-of select="@data-title"/></code> is called on an unordered list (<code>&lt;ul&gt;</code>) and its <code>&lt;li&gt;</code> elements have position (relative, absolute, or fixed), the effect may not work properly in IE6 through at least IE9 unless the <code>&lt;ul&gt;</code> has "layout." To remedy the problem, add the <code>position: relative;</code> and <code>zoom: 1;</code> CSS declarations to the <code>ul</code>.
@@ -65,7 +65,7 @@
6565
Using this selector heavily can have performance implications, as it may force the browser to re-render the page before it can determine visibility. Tracking the visibility of elements via other methods, using a class for example, can provide better performance.
6666
</xsl:when>
6767
<xsl:when test="@id = 'global-ajax-event'">
68-
As of jQuery 1.9, all the handlers for the <a href="/category/ajax/global-ajax-event-handlers/">jQuery global Ajax events</a>, including those added with the <code><xsl:value-of select="@data-title"/></code> method, <em>must</em> be attached to <code>document</code>.
68+
As of jQuery 1.9, all the handlers for the <a href="/category/ajax/global-ajax-event-handlers/">jQuery global Ajax events</a>, including those added with <code>.on( "<xsl:value-of select="@data-title"/>", ... )</code>, <em>must</em> be attached to <code>document</code>.
6969
</xsl:when>
7070
<xsl:when test="@id = 'svg-support'">
7171
jQuery doesn't officially support SVG. Using jQuery methods on SVG documents, unless explicitly documented for that method, might cause unexpected behaviors. Examples of methods that support SVG as of jQuery 3.0 are <code>addClass</code> and <code>removeClass</code>.

0 commit comments

Comments
 (0)