Skip to content

Commit 027012f

Browse files
mgolmgol
committed
All: Add separate shorthand pages for load/unload
1 parent db29f90 commit 027012f

File tree

4 files changed

+145
-49
lines changed

4 files changed

+145
-49
lines changed

‎entries/load-event.xml

+35-27
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,15 @@
11
<?xml version="1.0"?>
2-
<entry type="method" name="load" return="jQuery" deprecated="1.8" removed="3.0">
3-
<title>.load()</title>
2+
<entries>
3+
<desc>Bind an event handler to the "load" event, or trigger that event on an element.</desc>
4+
5+
<entry type="method" name="on" return="jQuery">
6+
<title>load event</title>
47
<desc>Bind an event handler to the "load" event.</desc>
58
<signature>
6-
<added>1.0</added>
7-
<argument name="handler" type="Function">
8-
<desc>A function to execute when the event is triggered.</desc>
9-
<argument name="eventObject" type="Event" />
9+
<added>1.7</added>
10+
<argument name="&quot;load&quot;" type="string">
11+
<desc>The string <code>"load"</code>.</desc>
1012
</argument>
11-
</signature>
12-
<signature>
13-
<added>1.4.3</added>
1413
<argument name="eventData" type="Anything" optional="true">
1514
<desc>An object containing data that will be passed to the event handler.</desc>
1615
</argument>
@@ -20,31 +19,24 @@
2019
</argument>
2120
</signature>
2221
<longdesc>
23-
<div class="warning">
24-
<p>Note: This API has been removed in jQuery 3.0; please use <code>.on( "load", handler )</code> instead of <code>.load( handler )</code> and <code>.trigger( "load" )</code> instead of <code>.load()</code>.</p>
25-
</div>
26-
<p>This method is a shortcut for <code>.on( "load", handler )</code>.</p>
2722
<p>The <code>load</code> event is sent to an element when it and all sub-elements have been completely loaded. This event can be sent to any element associated with a URL: images, scripts, frames, iframes, and the <code>window</code> object.</p>
2823
<p>For example, consider a page with a simple image:</p>
2924
<pre><code>
3025
&lt;img src="book.png" alt="Book" id="book"&gt;
3126
</code></pre>
3227
<p>The event handler can be bound to the image:</p>
3328
<pre><code>
34-
$( "#book" ).load(function() {
35-
// Handler for .load() called.
36-
});
29+
$( "#book" ).on( "load", function() {
30+
// Handler for `load` called.
31+
} );
3732
</code></pre>
3833
<p>As soon as the image has been loaded, the handler is called.</p>
3934
<p>In general, it is not necessary to wait for all images to be fully loaded. If code can be executed earlier, it is usually best to place it in a handler sent to the <code>.ready()</code> method.
4035
</p>
41-
<div class="warning">
42-
<p>The Ajax module also has a method named <code><a href="/load/">.load()</a></code>. Which one is fired depends on the set of arguments passed.</p>
43-
</div>
4436
<div class="warning">
4537
<p>
4638
<b>Caveats of the <code>load</code> event when used with images</b>
47-
<p>A common challenge developers attempt to solve using the <code>.load()</code> shortcut is to execute a function when an image (or collection of images) have completely loaded. There are several known caveats with this that should be noted. These are:</p>
39+
<p>A common challenge developers attempt to solve using the <code>load</code> shortcut is to execute a function when an image (or collection of images) have completely loaded. There are several known caveats with this that should be noted. These are:</p>
4840
<ul>
4941
<li>It doesn't work consistently nor reliably cross-browser</li>
5042
<li>It doesn't fire correctly in WebKit if the image src is set to the same src as before</li>
@@ -60,24 +52,40 @@ $( "#book" ).load(function() {
6052
<example>
6153
<desc>Run a function when the page is fully loaded including graphics.</desc>
6254
<code><![CDATA[
63-
$( window ).load(function() {
55+
$( window ).on( "load", function() {
6456
// Run code
65-
});
57+
} );
6658
]]></code>
6759
</example>
6860
<example>
6961
<desc>Add the class bigImg to all images with height greater than 100 upon each image load.</desc>
7062
<code><![CDATA[
71-
$( "img.userIcon" ).load(function() {
63+
$( "img.userIcon" ).on( "load", function() {
7264
if ( $( this ).height() > 100) {
7365
$( this ).addClass( "bigImg" );
7466
}
75-
});
67+
} );
7668
]]></code>
7769
</example>
7870
<category slug="events/document-loading"/>
7971
<category slug="version/1.0"/>
80-
<category slug="version/1.4.3"/>
81-
<category slug="deprecated/deprecated-1.8"/>
82-
<category slug="removed"/>
72+
<category slug="version/1.7"/>
73+
</entry>
74+
75+
<entry type="method" name="trigger" return="jQuery">
76+
<title>load event</title>
77+
<desc>Trigger the "load" event on an element.</desc>
78+
<signature>
79+
<added>1.0</added>
80+
<argument name="&quot;load&quot;" type="string">
81+
<desc>The string <code>"load"</code>.</desc>
82+
</argument>
83+
</signature>
84+
<longdesc>
85+
<p>See the description for <a href="#on1"><code>.on( "load", ... )</code></a>.</p>
86+
</longdesc>
87+
<category slug="events/document-loading"/>
88+
<category slug="version/1.0"/>
8389
</entry>
90+
91+
</entries>

‎entries/load-shorthand.xml

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
<?xml version="1.0"?>
2+
<entry type="method" name="load" return="jQuery" deprecated="1.8" removed="3.0">
3+
<title>.load()</title>
4+
<desc>Bind an event handler to the "load" event, or trigger that event on an element.</desc>
5+
<signature>
6+
<added>1.0</added>
7+
<argument name="handler" type="Function">
8+
<desc>A function to execute each time the event is triggered.</desc>
9+
<argument name="eventObject" type="Event" />
10+
</argument>
11+
</signature>
12+
<signature>
13+
<added>1.4.3</added>
14+
<argument name="eventData" type="Anything" optional="true">
15+
<desc>An object containing data that will be passed to the event handler.</desc>
16+
</argument>
17+
<argument name="handler" type="Function">
18+
<desc>A function to execute each time the event is triggered.</desc>
19+
<argument name="eventObject" type="Event" />
20+
</argument>
21+
</signature>
22+
<signature>
23+
<added>1.0</added>
24+
</signature>
25+
<longdesc>
26+
<div class="warning">
27+
<p>This API has been removed in jQuery 3.0.</p>
28+
<p>Instead of <code>.load( handler )</code> or <code>.load( eventData, handler )</code>, use <a href="/load-event/#on1"><code>.on( "load", handler )</code></a> or <a href="/load-event/#on1"><code>.on( "load", eventData, handler )</code></a>, respectively.</p>
29+
<p>Instead of <code>.load()</code>, use <a href="/load-event/#trigger2"><code>.trigger( "load" )</code></a>.</p>
30+
</div>
31+
<div class="warning">
32+
<p>The Ajax module also has a method named <code><a href="/load/">.load()</a></code>. Which one is fired depends on the set of arguments passed.</p>
33+
</div>
34+
</longdesc>
35+
<category slug="events/document-loading"/>
36+
<category slug="version/1.0"/>
37+
<category slug="version/1.4.3"/>
38+
<category slug="deprecated/deprecated-1.8"/>
39+
<category slug="removed"/>
40+
</entry>

‎entries/unload-shorthand.xml

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
<?xml version="1.0"?>
2+
<entry type="method" name="unload" return="jQuery" deprecated="1.8" removed="3.0">
3+
<title>.unload()</title>
4+
<desc>Bind an event handler to the "unload" event, or trigger that event on an element.</desc>
5+
<signature>
6+
<added>1.0</added>
7+
<argument name="handler" type="Function">
8+
<desc>A function to execute each time the event is triggered.</desc>
9+
<argument name="eventObject" type="Event" />
10+
</argument>
11+
</signature>
12+
<signature>
13+
<added>1.4.3</added>
14+
<argument name="eventData" type="Anything" optional="true">
15+
<desc>An object containing data that will be passed to the event handler.</desc>
16+
</argument>
17+
<argument name="handler" type="Function">
18+
<desc>A function to execute each time the event is triggered.</desc>
19+
<argument name="eventObject" type="Event" />
20+
</argument>
21+
</signature>
22+
<signature>
23+
<added>1.0</added>
24+
</signature>
25+
<longdesc>
26+
<div class="warning">
27+
<p>This API has been removed in jQuery 3.0.</p>
28+
<p>Instead of <code>.unload( handler )</code> or <code>.unload( eventData, handler )</code>, use <a href="/unload/#on1"><code>.on( "unload", handler )</code></a> or <a href="/unload/#on1"><code>.on( "unload", eventData, handler )</code></a>, respectively.</p>
29+
<p>Instead of <code>.unload()</code>, use <a href="/unload/#trigger2"><code>.trigger( "unload" )</code></a>.</p>
30+
</div>
31+
</longdesc>
32+
<category slug="events/document-loading"/>
33+
<category slug="version/1.0"/>
34+
<category slug="version/1.4.3"/>
35+
<category slug="deprecated/deprecated-1.8"/>
36+
<category slug="removed"/>
37+
</entry>

‎entries/unload.xml

+33-22
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
<?xml version="1.0"?>
2-
<entry type="method" name="unload" return="jQuery" deprecated="1.8" removed="3.0">
3-
<title>.unload()</title>
2+
<entries>
3+
<desc>Bind an event handler to the "unload" event, or trigger that event on an element.</desc>
4+
5+
<entry type="method" name="on" return="jQuery">
6+
<title>unload event</title>
7+
<desc>Bind an event handler to the "unload" event.</desc>
48
<signature>
5-
<added>1.0</added>
6-
<argument name="handler" type="Function">
7-
<desc>A function to execute when the event is triggered.</desc>
8-
<argument name="eventObject" type="Event" />
9+
<added>1.7</added>
10+
<argument name="&quot;unload&quot;" type="string">
11+
<desc>The string <code>"unload"</code>.</desc>
912
</argument>
10-
</signature>
11-
<signature>
12-
<added>1.4.3</added>
1313
<argument name="eventData" type="Anything" optional="true">
1414
<desc>A plain object of data that will be passed to the event handler.</desc>
1515
</argument>
@@ -18,35 +18,46 @@
1818
<argument name="eventObject" type="Event" />
1919
</argument>
2020
</signature>
21-
<desc>Bind an event handler to the "unload" event.</desc>
2221
<longdesc>
23-
<div class="warning">
24-
<p>Note: This API has been removed in jQuery 3.0; please use <code>.on( "unload", handler )</code> instead of <code>.unload( handler )</code> and <code>.trigger( "unload" )</code> instead of <code>.unload()</code>.</p>
25-
</div>
26-
<p>This method is a shortcut for <code>.on( "unload", handler )</code>.</p>
2722
<p>The <code>unload</code> event is sent to the <code>window</code> element when the user navigates away from the page. This could mean one of many things. The user could have clicked on a link to leave the page, or typed in a new URL in the address bar. The forward and back buttons will trigger the event. Closing the browser window will cause the event to be triggered. Even a page reload will first create an <code>unload</code> event.</p>
2823
<div class="warning">
2924
<p>The exact handling of the <code>unload</code> event has varied from version to version of browsers. For example, some versions of Firefox trigger the event when a link is followed, but not when the window is closed. In practical usage, behavior should be tested on all supported browsers and contrasted with the similar <code>beforeunload</code> event.</p>
3025
</div>
3126
<p>Any <code>unload</code> event handler should be bound to the <code>window</code> object:</p>
3227
<pre><code>
33-
$( window ).unload(function() {
34-
return "Handler for .unload() called.";
35-
});
28+
$( window ).on( "unload", function() {
29+
return "Handler for `unload` called.";
30+
} );
3631
</code></pre>
3732
<p>This event is available so that scripts can perform cleanup when the user leaves the page. Most browsers will ignore calls to <code>alert()</code>, <code>confirm()</code> and <code>prompt()</code> inside the event handler. The string you return may be used in a confirmation dialog, but not all browsers support this. It is not possible to cancel the <code>unload</code> event with <code>.preventDefault()</code>.</p>
3833
</longdesc>
3934
<example>
4035
<desc>To display an alert when a page is unloaded:</desc>
4136
<code><![CDATA[
42-
$( window ).unload(function() {
37+
$( window ).on( "unload", function() {
4338
return "Bye now!";
44-
});
39+
} );
4540
]]></code>
4641
</example>
4742
<category slug="events/document-loading"/>
4843
<category slug="version/1.0"/>
49-
<category slug="version/1.4.3"/>
50-
<category slug="deprecated/deprecated-1.8"/>
51-
<category slug="removed"/>
44+
<category slug="version/1.7"/>
45+
</entry>
46+
47+
<entry type="method" name="trigger" return="jQuery">
48+
<title>unload event</title>
49+
<desc>Trigger the "unload" event on an element.</desc>
50+
<signature>
51+
<added>1.0</added>
52+
<argument name="&quot;unload&quot;" type="string">
53+
<desc>The string <code>"unload"</code>.</desc>
54+
</argument>
55+
</signature>
56+
<longdesc>
57+
<p>See the description for <a href="#on1"><code>.on( "unload", ... )</code></a>.</p>
58+
</longdesc>
59+
<category slug="events/document-loading"/>
60+
<category slug="version/1.0"/>
5261
</entry>
62+
63+
</entries>

0 commit comments

Comments
 (0)