on(): Remove ambiguous information about event handlers on detached DOM elements. Fixes gh-548

Author: kswedberg

entries/on.xml

@@ -41,18 +41,18 @@
     <p>The majority of browser events <em>bubble</em>, or <em>propagate</em>, from the deepest, innermost element (the <strong>event target</strong>) in the document where they occur all the way up to the body and the <code>document</code> element. In Internet Explorer 8 and lower, a few events such as <code>change</code> and <code>submit</code> do not natively bubble but jQuery patches these to bubble and create consistent cross-browser behavior.</p>
     <p>If <code>selector</code> is omitted or is null, the event handler is referred to as <em>direct</em> or <em>directly-bound</em>. The handler is called every time an event occurs on the selected elements, whether it occurs directly on the element or bubbles from a descendant (inner) element.</p>
     <p>When a <code>selector</code> is provided, the event handler is referred to as <em>delegated</em>. The handler is not called when the event occurs directly on the bound element, but only for descendants (inner elements) that match the selector. jQuery bubbles the event from the event target up to the element where the handler is attached (i.e., innermost to outermost element) and runs the handler for any elements along that path matching the selector.</p>
-    <p><strong>Event handlers are bound only to the currently selected elements; they must exist on the page at the time your code makes the call to <code>.on()</code>.</strong> To ensure the elements are present and can be selected, perform event binding inside a document ready handler for elements that are in the HTML markup on the page. If new HTML is being injected into the page, select the elements and attach event handlers <em>after</em> the new HTML is placed into the page. Or, use delegated events to attach an event handler, as described next.</p>
-    <p>Delegated events have the advantage that they can process events from <em>descendant elements</em> that are added to the document at a later time. By picking an element that is guaranteed to be present at the time the delegated event handler is attached, you can use delegated events to avoid the need to frequently attach and remove event handlers. This element could be the container element of a view in a Model-View-Controller design, for example, or <code>document</code> if the event handler wants to monitor all bubbling events in the document. The <code>document</code> element is available in the <code>head</code> of the document before loading any other HTML, so it is safe to attach events there without waiting for the document to be ready.</p>
+    <p><strong>Event handlers are bound only to the currently selected elements; they must exist at the time your code makes the call to <code>.on()</code></strong>. To ensure the elements are present and can be selected, place scripts after the elements in the HTML markup or perform event binding inside a document ready handler. Alternatively, use delegated events to attach event handlers.</p>
+    <p><strong>Delegated events</strong> have the advantage that they can process events from <em>descendant elements</em> that are added to the document at a later time. By picking an element that is guaranteed to be present at the time the delegated event handler is attached, you can use delegated events to avoid the need to frequently attach and remove event handlers. This element could be the container element of a view in a Model-View-Controller design, for example, or <code>document</code> if the event handler wants to monitor all bubbling events in the document. The <code>document</code> element is available in the <code>head</code> of the document before loading any other HTML, so it is safe to attach events there without waiting for the document to be ready.</p>
     <p>In addition to their ability to handle events on descendant elements not yet created, another advantage of delegated events is their potential for much lower overhead when many elements must be monitored. On a data table with 1,000 rows in its <code>tbody</code>, this example attaches a handler to 1,000 elements:</p>
     <pre><code>
 $( "#dataTable tbody tr" ).on( "click", function() {
-  alert( $( this ).text() );
+  console.log( $( this ).text() );
 });
     </code></pre>
-    <p>A delegated-events approach attaches an event handler to only one element, the tbody, and the event only needs to bubble up one level (from the clicked <code>tr</code> to <code>tbody</code>):</p>
+    <p>An event-delegation approach attaches an event handler to only one element, the tbody, and the event only needs to bubble up one level (from the clicked <code>tr</code> to <code>tbody</code>):</p>
     <pre><code>
 $( "#dataTable tbody" ).on( "click", "tr", function() {
-  alert( $( this ).text() );
+  console.log( $( this ).text() );
 });
     </code></pre>
     <p><strong>Note:</strong> Delegated events do not work for SVG.</p>