Events: add note about detaching to all shorthand methods

arthurvr · arthurvr · commit e420da6cacea · 2015-04-17T21:05:12.000+02:00
Fixes gh-717 Closes gh-719
diff --git a/entries/blur.xml b/entries/blur.xml
@@ -52,6 +52,7 @@ $( "#other" ).click(function() {
     <p>After this code executes, clicks on <samp>Trigger the handler</samp> will also alert the message.</p>
     <p>The <code>blur</code> event does not bubble in Internet Explorer. Therefore, scripts that rely on event delegation with the <code>blur</code> event will not work consistently across browsers. As of version 1.4.2, however, jQuery works around this limitation by mapping <code>blur</code> to the <code>focusout</code> event in its event delegation methods, <a href="/live/"><code>.live()</code></a> and <a href="/delegate/"><code>.delegate()</code></a>.</p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="blur"/>
   <example>
     <desc>To trigger the blur event on all paragraphs:</desc>
     <code><![CDATA[
diff --git a/entries/change.xml b/entries/change.xml
@@ -56,6 +56,7 @@ $( "#other" ).click(function() {
 	  <p><strong>Note: </strong>Changing the value of an input element using JavaScript, using <a href="/val"><code>.val()</code></a> for example, won't fire the event.</p>
     </div>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="change"/>
   <example>
     <desc>Attaches a change event to the select that gets the text for each selected option and writes them in the div.  It then triggers the event for the initial text draw.</desc>
     <code><![CDATA[
diff --git a/entries/click.xml b/entries/click.xml
@@ -61,6 +61,7 @@ $( "#other" ).click(function() {
     </ul>
     <p>This is usually the desired sequence before taking an action. If this is not required, the <code>mousedown</code> or <code>mouseup</code> event may be more suitable.</p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="click"/>
   <example>
     <desc>Hide paragraphs on a page when they are clicked:</desc>
     <code><![CDATA[
diff --git a/entries/dblclick.xml b/entries/dblclick.xml
@@ -64,6 +64,7 @@ $( "#other" ).click(function() {
     <p>It is inadvisable to bind handlers to both the <code>click</code> and <code>dblclick</code> events for the same element. The sequence of events triggered varies from browser to browser, with some receiving two <code>click</code> events before the <code>dblclick</code> and others only one. Double-click sensitivity (maximum time between clicks that is detected as a double click) can vary by operating system and browser, and is often user-configurable.
     </p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="dblclick"/>
   <example>
     <desc>To bind a "Hello World!" alert box the dblclick event on every paragraph on the page:</desc>
     <code><![CDATA[
diff --git a/entries/error.xml b/entries/error.xml
@@ -43,6 +43,7 @@ $( "#book" )
     </div>
     <p>Note: A jQuery error event handler should not be attached to the window object. The browser fires the window's error event when a script error occurs. However, the window error event receives different arguments and has different return value requirements than conventional event handlers. Use <code>window.onerror</code> instead.</p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="error"/>
   <example>
     <desc>To hide the "broken image" icons for IE users, you can try:</desc>
     <code><![CDATA[
diff --git a/entries/focus.xml b/entries/focus.xml
@@ -60,6 +60,7 @@ $( "#other" ).click(function() {
     <p>After this code executes, clicks on <samp>Trigger the handler</samp> will also alert the message.</p>
     <p>The <code>focus</code> event does not bubble in Internet Explorer. Therefore, scripts that rely on event delegation with the <code>focus</code> event will not work consistently across browsers. As of version 1.4.2, however, jQuery works around this limitation by mapping <code>focus</code> to the <code>focusin</code> event in its event delegation methods, <a href="/live/"><code>.live()</code></a> and <a href="/delegate/"><code>.delegate()</code></a>.</p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="focus"/>
   <example>
     <desc>Fire focus.</desc>
     <css><![CDATA[
diff --git a/entries/focusin.xml b/entries/focusin.xml
@@ -24,6 +24,7 @@
     <p>The <code>focusin</code> event is sent to an element when it, or any element inside of it, gains focus. This is distinct from the <a href="/focus/">focus</a> event in that it supports detecting the focus event on parent elements (in other words, it supports event bubbling).</p>
     <p>This event will likely be used together with the <a href="/focusout/">focusout</a> event.</p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="focusin"/>
   <example>
     <desc>Watch for a focus to occur within the paragraphs on the page.</desc>
     <css><![CDATA[
diff --git a/entries/focusout.xml b/entries/focusout.xml
@@ -24,6 +24,7 @@
     <p>The <code>focusout</code> event is sent to an element when it, or any element inside of it, loses focus. This is distinct from the <a href="/blur/">blur</a> event in that it supports detecting the loss of focus on descendant elements (in other words, it supports event bubbling).</p>
     <p>This event will likely be used together with the <a href="/focusin/">focusin</a> event.</p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="focusout"/>
   <example>
     <desc>Watch for a loss of focus to occur inside paragraphs and note the difference between the <code>focusout</code> count and the <code>blur</code> count. (The <code>blur</code> count does not change because those events do not bubble.)</desc>
     <css><![CDATA[
diff --git a/entries/keydown.xml b/entries/keydown.xml
@@ -54,6 +54,7 @@ $( "#other" ).click(function() {
     <p>If key presses anywhere need to be caught (for example, to implement global shortcut keys on a page), it is useful to attach this behavior to the <code>document</code> object. Because of event bubbling, all key presses will make their way up the DOM to the <code>document</code> object unless explicitly stopped.</p>
     <p>To determine which key was pressed, examine the <a href="/category/events/event-object/">event object</a> that is passed to the handler function. While browsers use differing properties to store this information, jQuery normalizes the <code>.which</code> property so you can reliably use it to retrieve the key code. This code corresponds to a key on the keyboard, including codes for special keys such as arrows. For catching actual text entry, <code>.keypress()</code> may be a better choice.</p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="keydown"/>
   <example>
     <desc>Show the event object for the keydown handler when a key is pressed in the input.</desc>
     <code><![CDATA[
diff --git a/entries/keypress.xml b/entries/keypress.xml
@@ -59,6 +59,7 @@ $( "#other" ).click(function() {
     <p>To determine which character was entered, examine the <code>event</code> object that is passed to the handler function. While browsers use differing properties to store this information, jQuery normalizes the <code>.which</code> property so you can reliably use it to retrieve the character code.</p>
     <p>Note that <code>keydown</code> and <code>keyup</code> provide a code indicating which key is pressed, while <code>keypress</code> indicates which character was entered. For example, a lowercase "a" will be reported as 65 by <code>keydown</code> and <code>keyup</code>, but as 97 by <code>keypress</code>. An uppercase "A" is reported as 65 by all events. Because of this distinction, when catching special keystrokes such as arrow keys, <code>.keydown()</code> or <code>.keyup()</code> is a better choice.</p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="keypress"/>
   <example>
     <desc>Show the event object when a key is pressed in the input. Note: This demo relies on a simple $.print() plugin (http://api.jquery.com/resources/events.js) for the event object's output.</desc>
     <code><![CDATA[
diff --git a/entries/keyup.xml b/entries/keyup.xml
@@ -54,6 +54,7 @@ $( "#other" ).click(function() {
     <p>If key presses anywhere need to be caught (for example, to implement global shortcut keys on a page), it is useful to attach this behavior to the <code>document</code> object. Because of event bubbling, all key presses will make their way up the DOM to the <code>document</code> object unless explicitly stopped.</p>
     <p>To determine which key was pressed, examine the event object that is passed to the handler function. While browsers use differing properties to store this information, jQuery normalizes the <code>.which</code> property so you can reliably use it to retrieve the key code. This code corresponds to a key on the keyboard, including codes for special keys such as arrows. For catching actual text entry, <code>.keypress()</code> may be a better choice.</p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="keyup"/>
   <example>
     <desc>Show the event object for the keyup handler (using a simple $.print plugin) when a key is released in the input.</desc>
     <code><![CDATA[
diff --git a/entries/mousedown.xml b/entries/mousedown.xml
@@ -57,6 +57,7 @@ $( "#other" ).click(function() {
     <p>This event is primarily useful for ensuring that the primary button was used to begin a drag operation; if ignored, strange results can occur when the user attempts to use a context menu. While the middle and right buttons can be detected with these properties, this is not reliable. In Opera and Safari, for example, right mouse button clicks are not detectable by default.</p>
     <p>If the user clicks on an element, drags away from it, and releases the button, this is still counted as a <code>mousedown</code> event. This sequence of actions is treated as a "canceling" of the button press in most user interfaces, so it is usually better to use the <code>click</code> event unless we know that the <code>mousedown</code> event is preferable for a particular situation.</p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="mousedown"/>
   <example>
     <desc>Show texts when mouseup and mousedown event triggering.</desc>
     <code><![CDATA[
diff --git a/entries/mouseenter.xml b/entries/mouseenter.xml
@@ -55,6 +55,7 @@ $( "#other" ).click(function() {
     <p>After this code executes, clicks on <samp>Trigger the handler</samp> will also append the message.</p>
     <p>The <code>mouseenter</code> event differs from <code>mouseover</code> in the way it handles event bubbling. If <code>mouseover</code> were used in this example, then when the mouse pointer moved over the <samp>Inner</samp> element, the handler would be triggered. This is usually undesirable behavior. The <code>mouseenter</code> event, on the other hand, only triggers its handler when the mouse enters the element it is bound to, not a descendant. So in this example, the handler is triggered when the mouse enters the <samp>Outer</samp> element, but not the <samp>Inner</samp> element.</p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="mouseenter"/>
   <example>
     <desc>Show texts when mouseenter and mouseout event triggering.
     <code>mouseover</code> fires when the pointer moves into the child element as well, while <code>mouseenter</code> fires only when the pointer moves into the bound element.</desc>
diff --git a/entries/mouseleave.xml b/entries/mouseleave.xml
@@ -55,6 +55,7 @@ $( "#other" ).click(function() {
     <p>After this code executes, clicks on <samp>Trigger the handler</samp> will also append the message.</p>
     <p>The <code>mouseleave</code> event differs from <code>mouseout</code> in the way it handles event bubbling. If <code>mouseout</code> were used in this example, then when the mouse pointer moved out of the <samp>Inner</samp> element, the handler would be triggered. This is usually undesirable behavior. The <code>mouseleave</code> event, on the other hand, only triggers its handler when the mouse leaves the element it is bound to, not a descendant. So in this example, the handler is triggered when the mouse leaves the <samp>Outer</samp> element, but not the <samp>Inner</samp> element.</p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="mouseleave"/>
   <example>
     <desc>Show number of times mouseout and mouseleave events are triggered. <code>mouseout</code> fires when the pointer moves out of child element as well, while <code>mouseleave</code> fires only when the pointer moves out of the bound element.</desc>
     <css><![CDATA[
diff --git a/entries/mousemove.xml b/entries/mousemove.xml
@@ -68,6 +68,7 @@ $( "#other" ).click(function() {
     <p>Keep in mind that the <code>mousemove</code> event is triggered whenever the mouse pointer moves, even for a pixel. This means that hundreds of events can be generated over a very small amount of time. If the handler has to do any significant processing, or if multiple handlers for the event exist, this can be a serious performance drain on the browser. It is important, therefore, to optimize <code>mousemove </code>handlers as much as possible, and to unbind them as soon as they are no longer needed.</p>
     <p>A common pattern is to bind the <code>mousemove</code> handler from within a <code>mousedown</code> hander, and to unbind it from a corresponding <code>mouseup</code> handler. If implementing this sequence of events, remember that the <code>mouseup</code> event might be sent to a different HTML element than the <code>mousemove</code> event was. To account for this, the <code>mouseup</code> handler should typically be bound to an element high up in the DOM tree, such as <code>&lt;body&gt;</code>.</p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="mousemove"/>
   <example>
     <desc>Show the mouse coordinates when the mouse is moved over the yellow div.  Coordinates are relative to the window, which in this case is the iframe.</desc>
     <code><![CDATA[
diff --git a/entries/mouseout.xml b/entries/mouseout.xml
@@ -56,6 +56,7 @@ $( "#other" ).click(function() {
     <p>After this code executes, clicks on <samp>Trigger the handler</samp> will also append the message.</p>
     <p>This event type can cause many headaches due to event bubbling. For instance, when the mouse pointer moves out of the <samp>Inner</samp> element in this example, a <code>mouseout</code> event will be sent to that, then trickle up to <samp>Outer</samp>. This can trigger the bound <code>mouseout</code> handler at inopportune times. See the discussion for <code>.<a href="/mouseleave/">mouseleave</a>()</code> for a useful alternative.</p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="mouseout"/>
   <example>
     <desc>Show the number of times mouseout and mouseleave events are triggered.
   <code>mouseout</code> fires when the pointer moves out of the child element as well, while <code>mouseleave</code> fires only when the pointer moves out of the bound element.</desc>
diff --git a/entries/mouseover.xml b/entries/mouseover.xml
@@ -56,6 +56,7 @@ $( "#other" ).click(function() {
     <p>After this code executes, clicks on <samp>Trigger the handler</samp> will also append the message.</p>
     <p>This event type can cause many headaches due to event bubbling. For instance, when the mouse pointer moves over the <samp>Inner</samp> element in this example, a <code>mouseover</code> event will be sent to that, then trickle up to <samp>Outer</samp>. This can trigger our bound <code>mouseover</code> handler at inopportune times. See the discussion for <code>.mouseenter()</code> for a useful alternative.</p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="mouseover"/>
   <example>
     <desc>Show the number of times mouseover and mouseenter events are triggered.
 <code>mouseover</code> fires when the pointer moves into the child element as well, while <code>mouseenter</code> fires only when the pointer moves into the bound element.</desc>
diff --git a/entries/mouseup.xml b/entries/mouseup.xml
@@ -56,6 +56,7 @@ $( "#other" ).click(function() {
     <p>After this code executes, clicks on <samp>Trigger the handler</samp> will also alert the message.</p>
     <p>If the user clicks outside an element, drags onto it, and releases the button, this is still counted as a <code>mouseup</code> event. This sequence of actions is not treated as a button press in most user interfaces, so it is usually better to use the <code>click</code> event unless we know that the <code>mouseup</code> event is preferable for a particular situation.</p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="mouseup"/>
   <example>
     <desc>Show texts when mouseup and mousedown event triggering.</desc>
     <code><![CDATA[
diff --git a/entries/resize.xml b/entries/resize.xml
@@ -33,6 +33,7 @@ $( window ).resize(function() {
     <p>Now whenever the browser window's size is changed, the message is appended to &lt;div id="log"&gt; one or more times, depending on the browser.</p>
     <p>Code in a <code>resize</code> handler should never rely on the number of times the handler is called. Depending on implementation, <code>resize</code> events can be sent continuously as the resizing is in progress (the typical behavior in Internet Explorer and WebKit-based browsers such as Safari and Chrome), or only once at the end of the resize operation (the typical behavior in some other browsers such as Opera).</p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="resize"/>
   <example>
     <desc>To see the window width while (or after) it is resized, try:</desc>
     <code><![CDATA[
diff --git a/entries/scroll.xml b/entries/scroll.xml
@@ -65,6 +65,7 @@ $( "#other" ).click(function() {
     <p>After this code executes, clicks on <samp>Trigger the handler</samp> will also append the message.</p>
     <p>A <code>scroll</code> event is sent whenever the element's scroll position changes, regardless of the cause. A mouse click or drag on the scroll bar, dragging inside the element, pressing the arrow keys, or using the mouse's scroll wheel could cause this event.</p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="scroll"/>
   <example>
     <desc>To do something when your page is scrolled:</desc>
     <code><![CDATA[
diff --git a/entries/select.xml b/entries/select.xml
@@ -54,6 +54,7 @@ $( "#other").click(function() {
       <p>The method for retrieving the current selected text differs from one browser to another. A number of jQuery plug-ins offer cross-platform solutions.</p>
     </div>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="select"/>
   <example>
     <desc>To do something when text in input boxes is selected:</desc>
     <code><![CDATA[
diff --git a/entries/submit.xml b/entries/submit.xml
@@ -53,6 +53,7 @@ $( "#other" ).click(function() {
     <p>After this code executes, clicks on <samp>Trigger the handler</samp> will also display the message. In addition, the default <code>submit</code> action on the form will be fired, so the form will be submitted.</p>
     <p>The JavaScript <code>submit</code> event does not bubble in Internet Explorer. However, scripts that rely on event delegation with the <code>submit</code> event will work consistently across browsers as of jQuery 1.4, which has normalized the event's behavior. </p>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="submit"/>
   <note id="domlint" type="additional"/>
   <example>
     <desc>If you'd like to prevent forms from being submitted unless a flag variable is set, try:</desc>
diff --git a/entries/unload.xml b/entries/unload.xml
@@ -33,6 +33,7 @@ $( window ).unload(function() {
     </code></pre>
     <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>
   </longdesc>
+  <note id="detach-shorthand" type="additional" data-event="unload"/>
   <example>
     <desc>To display an alert when a page is unloaded:</desc>
     <code><![CDATA[
diff --git a/notes.xsl b/notes.xsl
@@ -61,6 +61,9 @@
 		<xsl:when test="@id = 'hidden-forces-layout'">
 			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.
 		</xsl:when>
+		<xsl:when test="@id = 'detach-shorthand'">
+			As the <code>.<xsl:value-of select="@data-event"/>()</code> method is just a shorthand for <code>.on( "<xsl:value-of select="@data-event"/>", handler )</code>, detaching is possible using <code>.off( "<xsl:value-of select="@data-event"/>" )</code>.
+		</xsl:when>
 	</xsl:choose>
 </xsl:template>
 </xsl:stylesheet>
