Skip to content

Commit bcdb151

Browse files
dmethvinmgol
authored andcommitted
Event: Clarify valid chars for events and namespaces
Fixes jquery#1086 Fixes jquery#1085 Closes jquery#1093
1 parent 385c4db commit bcdb151

File tree

1 file changed

+4
-4
lines changed

1 file changed

+4
-4
lines changed

entries/on.xml

+4-4
Original file line numberDiff line numberDiff line change
@@ -35,14 +35,14 @@
3535
<p>The <code>.on()</code> method attaches event handlers to the currently selected set of elements in the jQuery object. As of jQuery 1.7, the <code>.on()</code> method provides all functionality required for attaching event handlers. For help in converting from older jQuery event methods, see <a href="/bind/"><code>.bind()</code></a>, <a href="/delegate/"><code>.delegate()</code></a>, and <a href="/live/"><code>.live()</code></a>. To remove events bound with <code>.on()</code>, see <a href="/off/"><code>.off()</code></a>. To attach an event that runs only once and then removes itself, see <a href="/one/"><code>.one()</code></a></p>
3636
<h2 id="event-names">Event names and namespaces</h2>
3737
<p>Any event names can be used for the <code>events</code> argument. jQuery will pass through the browser's standard JavaScript event types, calling the <code>handler</code> function when the browser generates events due to user actions such as <code>click</code>. In addition, the <a href="/trigger/"><code>.trigger()</code></a> method can trigger both standard browser event names and custom event names to call attached handlers. Event names should only contain alphanumerics, underscore, and colon characters.</p>
38-
<p>An event name can be qualified by <em>event namespaces</em> that simplify removing or triggering the event. For example, <code>"click.myPlugin.simple"</code> defines both the myPlugin and simple namespaces for this particular click event. A click event handler attached via that string could be removed with <code>.off("click.myPlugin")</code> or <code>.off("click.simple")</code> without disturbing other click handlers attached to the elements. Namespaces are similar to CSS classes in that they are not hierarchical; only one name needs to match. Namespaces beginning with an underscore are reserved for jQuery's use.</p>
38+
<p>An event name can be qualified by <em>event namespaces</em> that simplify removing or triggering the event. For example, <code>"click.myPlugin.simple"</code> defines both the myPlugin and simple namespaces for this particular click event. A click event handler attached via that string could be removed with <code>.off("click.myPlugin")</code> or <code>.off("click.simple")</code> without disturbing other click handlers attached to the elements. Namespaces are similar to CSS classes in that they are not hierarchical; only one name needs to match. Namespaces should contain upper/lowercase letters and digits only.</p>
3939
<p>In the second form of <code>.on()</code>, the <code>events</code> argument is a plain object. The keys are strings in the same form as the <code>events</code> argument with space-separated event type names and optional namespaces. The value for each key is a function (or <code>false</code> value) that is used as the <code>handler</code> instead of the final argument to the method. In other respects, the two forms are identical in their behavior as described below.</p>
40-
<h2 id="direct-and-delegated-events">Direct and delegated events</h2>
40+
<h2 id="direct-and-delegated-events">Direct and delegated event handlers</h2>
4141
<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>
4242
<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>
4343
<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>
4444
<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>
45-
<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>
45+
<p><strong>Delegated event handlers</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>
4646
<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>
4747
<pre><code>
4848
$( "#dataTable tbody tr" ).on( "click", function() {
@@ -55,7 +55,7 @@ $( "#dataTable tbody" ).on( "click", "tr", function() {
5555
console.log( $( this ).text() );
5656
});
5757
</code></pre>
58-
<p><strong>Note:</strong> Delegated events do not work for SVG.</p>
58+
<p><strong>Note:</strong> Delegated event handlers do not work for SVG.</p>
5959
<h2 id="event-handler">The event handler and its environment</h2>
6060
<p>The <code>handler</code> argument is a function (or the value <code>false</code>, see below), and is required unless you pass an object for the <code>events</code> argument. You can provide an anonymous handler function at the point of the <code>.on()</code> call, as the examples have done above, or declare a named function and pass its name:</p>
6161
<pre><code>

0 commit comments

Comments
 (0)