42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith text-transform: none;
0b9d29819770568053cd440baed0fedeb42aa208Luke Smith .yui3-skin-sam td {
0b9d29819770568053cd440baed0fedeb42aa208Luke Smith background-color: #E6E9F5;
0b9d29819770568053cd440baed0fedeb42aa208Luke Smith .yui3-skin-sam .yui3-datatable td {
0b9d29819770568053cd440baed0fedeb42aa208Luke Smith background-color: transparent;
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<div class="intro component">
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <p>The YUI Event Utility provides APIs for working with the browser's DOM
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith event system. It simplifies tasks like subscribing to button `click`s or
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith canceling <form> `submit`s to, for example, allow sending data to the
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith server via ajax.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <p>In addition, the "Synthetic event" system supplies <em>entirely new</em>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith DOM events to subscribe to as well as fixing events that behave differently
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith across browsers. Implementers can create their own DOM events triggered by
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith specific user actions or other environmental criteria.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <p>The API for working with DOM events is provided by the EventTarget class,
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith which also services the Custom event infrastructure that is used throughout
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith YUI. Read more about working with custom events <a
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith href="../event-custom/index.html">in the EventTarget user guide</a>.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith{{>getting-started}}
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h2>The Basics</h2>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<h4>Listening for events</h4>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith// Step 1. Capture a button node
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithvar button = Y.one("#readygo");
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith// Step 2. Subscribe to its click event with a callback function
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithbutton.on("click", function (e) {
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith // Step 3. do stuff when the button is clicked
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove<p><code>on(<em>type</em>, <em>callback</em>)</code> is the main
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithsubscription method, and is available on every <a href="../node/">`Node`</a>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithand <a href="../node/#nodelist">`NodeList`</a>.</p>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<p>Replace "click" with <a href="#event-whitelist">any other event name</a> to subscribe to that event.</p>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<h4>The Callback and the Event Object</h4>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithbutton.on('click', function (e) {
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // `this` is the button Node, NOT the DOM element
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith this.get('id'); // ==> 'readygo' (from <button id="readygo">...</button>)
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // Event properties that point to the DOM are also Node instances
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith e.target.get('id'); // => 'readygo'
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // Stop the event's default behavior
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // Stop the event from bubbling up the DOM tree
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<p>Subscribed callbacks are passed a <a href="#facade-properties">a normalized
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithevent object</a> as their first argument.</p>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<p>The keyword "`this`" in the callback will refer to the Node or NodeList
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smiththat you subscribed from.</p>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<h4>`e.preventDefault()` and `e.stopPropagation()`</h4>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<p>Many events have a default behavior, such as the `submit` event serializing
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithform data and making a new page request. Disable this behavior with
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithfunction setFilter(e) {
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith // Stop the link from loading the href page
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith // Now do my own thing instead
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith var url = this.get('href').replace(/page/, 'partial');
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith Y.one('#contentArea').load(url);
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith // `return false` is supported, but not preferred. use e.preventDefault()
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith return false;
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke SmithY.one('#table-filter-link').on('click', setFilter);
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<p>Most events can be listened for on the specific element that originates them
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<em>or from any of their parent elements</em>, all the way up to the
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith`document`. Prevent dispatching the event to subscriptions bound to elements
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithfurther up the DOM tree with `e.stopPropagation()`. In practice, this is
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithrarely useful.</p>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<p>Returning `false` from a callback will also stop the propagation of the
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithevent, which may cause unintended side effects.</p>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<p>`e.stopPropagation()` won't prevent the execution of other subscribers
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithlistening to the same element, only elements further up the DOM tree. If you
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithneed to stop all execution, use `e.stopImmediatePropagation()` or
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith`e.halt(true)`. The latter will also call `e.preventDefault()`.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h4>Detaching subscriptions</h4>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<p>`node.on()` and all
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<a href="#more">other subscription methods</a> return a
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithsubscription object that can be used to unbind that subscription. Node also
b7514db172ccfbcf96d47baf7305d56c66ac832dRyuichi Okumurasupports a `detach()` method and <a href="#detach-methods">other ways to cleanup
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithsubscriptions</a>.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith// on() returns a subscription handle...
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithvar sub = button.on("click", handleClick);
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith// ...that can be used to unbind the subscription
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith// Alternately, use the Node's detach() method
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithbutton.detach("click", handleClick);
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>Just this should take care of most of the simple event bindings you'll need.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke SmithThere's <a href="#more">a lot more you can do</a>, though, so read on!</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h2 id="modules">What to `use()`</h2>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Before we get into <a href="#more">more API goodies</a>, let's talk about
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith the Event Utility's module breakdown.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith For starters, in most cases <em>you probably won't `use('event')`</em>.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith The core DOM event system ("event-base") is required by the "node-base"
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith module, which itself if required by just about everything in YUI. So you
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith probably already have the DOM event API and didn't know it!
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>Here is the full breakdown of modules in the DOM event system:</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <th>`use("______", ...)`</th>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <th>What's in it?</th>
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <td><a href="{{apiDocs}}/module_event-base.html">`event-base`</a></td>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith The core DOM event subscription system as well as the DOM
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith lifecycle events <a href="domready.html">`domready`,
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith `contentready`, and `available`</a>. Notably, it does NOT
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li>event delegation</li>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li>event simulation</li>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li>synthetic events</li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <p>If you've `use()`d anything, you probably have this already.</p>
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <td><a href="{{apiDocs}}/module_event.html">`event`</a></td>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith A rollup of all modules below except
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li>"event-simulate"</li>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li>"node-event-simulate"</li>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li>"node-event-delegate" (which is in the "node" rollup)</li>
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <td><a href="{{apiDocs}}/module_event-delegate.html">`event-delegate`</a> &
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <a style="white-space: nowrap;" href="{{apiDocs}}/module_node-event-delegate.html">`node-event-delegate`</a></td>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Adds the `Y.delegate(...)` and `node.delegate(...)` methods,
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith respectively, for <a href="#delegation">event delegation</a>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith convenience.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <td><a href="{{apiDocs}}/module_event-simulate.html">`event-simulate`</a> &
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <a style="white-space: nowrap;" href="{{apiDocs}}/module_node-event-simulate.html">`node-event-simulate`</a></td>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Adds `Y.Event.simulate(...)` and `node.simulate(...)` for
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <a href="#simulate">triggering native DOM events</a> for
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith unit testing.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <strong>Note: <a href="simulate.html#faking">Faking DOM events
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith should not be used in user facing code</a></strong>.
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <td><a href="{{apiDocs}}/module_event-synthetic.html">`event-synthetic`</a></td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <p>Supplies the infrastructure for creating new DOM events, "fixing"
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith existing events with undesirable or inconsistent behavior, and
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <a href="synths.html">all sorts of other things</a>.</p>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <p>All of the modules below are synthetics.</p>
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <td><a href="{{apiDocs}}/module_event-flick.html">`event-flick`</a></td>
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith Adds a <a href="touch.html#flick">"flick" event</a> for touch or
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith mouse interaction.
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <td><a href="{{apiDocs}}/module_event-focus.html">`event-focus`</a></td>
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <a href="focus.html">Fixes `focus` and `blur` events</a> to bubble
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith (for delegation).
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <td><a href="{{apiDocs}}/module_event-gestures.html">`event-gestures`</a></td>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <p>A rollup of the following modules:</p>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <li>"event-touch"</li>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <li>"event-move"</li>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <li>"event-flick"</li>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <p>In the future, may contain more gesture abstraction modules.</p>
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <td><a href="{{apiDocs}}/module_event-hover.html">`event-hover`</a></td>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Adds a <a href="mouseenter.html#hover">"hover" event</a> which
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith binds to two callbacks, one for the start, and one for the end of a
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith mouse hover.
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <td><a href="{{apiDocs}}/module_event-key.html">`event-key`</a></td>
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith Adds a <a href="key.html">"key" event</a> which listens for
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith specific, implementer defined, keys being pressed by the user.
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <td><a href="{{apiDocs}}/module_event-mouseenter.html">`event-mouseenter`</a></td>
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith Adds <a href="mouseenter.html">"mouseenter" and "mouseleave"
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith events</a>. You probably want to use these instead of "mouseover"
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith and "mouseout".
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <td><a href="{{apiDocs}}/module_event-mousewheel.html">`event-mousewheel`</a></td>
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith <p>Adds a "mousewheel" event for monitoring users scrolling the
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith window with the mousewheel. Event facades passed to the callback
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith will have an `e.wheelDelta` property corresponding to the amount of
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith scrolling.</p>
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith <p>Currently, this event can only be subscribed with
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith `Y.on("mousewheel", callback)`;</p>
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <td><a href="{{apiDocs}}/module_event-move.html">`event-move`</a></td>
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith Adds <a href="touch.html#move">"gesturemovestart", "gesturemove",
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith and "gesturemoveend" events</a> that serve as abstractions over
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith mouse and touch events, forking internally based on the client
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <td><a href="{{apiDocs}}/module_event-outside.html">`event-outside`</a></td>
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith Adds a <a href="outside.html">"clickoutside" and several other
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith outside events</a> to trigger behavior based on actions taken
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith outside a specific element.
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <td><a href="{{apiDocs}}/module_event-resize.html">`event-resize`</a></td>
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith <p>Adds a "windowresize" event that only fires after a user has
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith stopped dragging a window's resize handle. This normalizes the
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith `window.onresize` event across browsers.</p>
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith <p>This event can only be subscribed with
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith `Y.on("windowresize", callback)`;</p>
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <td><a href="{{apiDocs}}/module_event-touch.html">`event-touch`</a></td>
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith Adds support for <a href="touch.html">subscribing to native touch
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith and gesture events</a>.
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <td><a href="{{apiDocs}}/module_event-valuechange.html">`event-valuechange`</a></td>
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove Adds a <a href="valuechange.html">"valuechange" event</a> that fires when input element text
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith changes (this is harder than you think).
68b1d15dad8af70374cec83a13758dce5621de1dTodd Kloots <td><a href="{{apiDocs}}/module_event-contextmenu.html">`event-contextmenu`</a></td>
68b1d15dad8af70374cec83a13758dce5621de1dTodd Kloots <a href="contextmenu.html">Fixes bugs and inconstancies</a> that can occur when the "contextmenu" event is fired via the keyboard. <a href="contextmenu.html#the-value-of-the-contextmenu-synthetic-event">Adds sugar for working with the "contextmenu" event</a>.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h2 id="delegation">Event Delegation</h2>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>If you don't already know what event delegation is, you should <a
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithhref="delegation.html">read this quick overview</a>. Short form: <em>you need
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithto be using this</em>.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith// single element subscription
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithnode.on("click", handleClick);
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith// delegated subscription for all button clicks from inside the node
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithnode.delegate("click", handleClick, "button, input[type=button]");
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>Creating a delegated subscription looks very much like creating any other
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithevent subscription with two differences. First, it's a different method name,
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith`delegate`. Second, there is another argument: a CSS selector that is used to
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithtest the event's originating element to decide if the callback should be
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithexecuted. If the event started at or inside an element matching the selector,
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smiththe callback will execute.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>Unlike `node.on()` subscriptions, the `this` object in `node.delegate()`
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithcallbacks will refer to the element that matched the css filter, not to `node`.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke SmithWe did this because likely your logic revolves around the nodes described by
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smiththe filter, not around the element that contains them.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithfunction handleClick (e) {
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // `this` is the button with class .remove, not the #items element
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // remove the containing LI
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith this.ancestor('li').remove();
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke SmithY.one('#items').delegate('click', handleClick, 'button.remove');
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<p>For more complex target filtering, a function can be passed instead of a css
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithselector. See the
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<a href="{{apiDocs}}/module_event-delegate.html#method_delegate">API docs</a>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithfor more details.</p>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<p>As noted <a href="#modules">above</a>, the `event-delegate` module is
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithincluded in the `event` rollup, but `node-event-delegate` isn't. We recommend
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithusing delegation from the Node API, so you should `use()` either
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith`node-event-delegate` or the `node` rollup.</p>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h2 id="more">More Event API Goodness</h2>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Here is a sampling of some of the other ways to manage event subscriptions
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h4 id="y-on">Subscribe from `Y`</h4>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith// Y.on() takes a third argument which is the Node, DOM element,
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith// or CSS selector of the element(s) to bind
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke SmithY.on("click", handleClick, "#readygo");
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith// Y.delegate() similarly takes the containing element or selector
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith// as the third argument
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke SmithY.delegate("click", handleClick, "#container", "button, input[type=button]");
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith An alternate syntax for DOM subscriptions is using `Y.on()` or
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith `Y.delegate()`. When identifying the target by a CSS selector, these
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith methods can be used regardless if the element is currently available for
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith scripting. If it's not yet on the page, a poll will regularly look for it
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith (for a few seconds) and the subscription will be automatically attached
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith when the element is found. Relying on this behavior can introduce race
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith conditions, though, so use it wisely.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Use of `Y.on()` instead of `node.on()` is largely a stylistic preference,
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith though <a href="#y-on-vs-node-on">there are some technical differences</a>.
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<h4 id="once">One time subscriptions</h4>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke SmithtabLabel.once('mouseover', loadTabContent);
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<p>If you only want to execute a callback on the first occurrence of an event, use `node.once()` or `Y.once()`. The subscription will automatically be detached after the event fires.</p>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<p>The signature for `once()` is the same as `on()`.</p>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<h4>Grouping subscriptions</h4>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<p>Pass an object to subscribe to multiple events, each with their own
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smithfunction validate(e) { ... }
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smithfunction clearPlaceholder(e) { ... }
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithvar groupSub = inputNode.on({
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith blur : validate,
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith keypress: validate,
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith focus : clearPlaceholder
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith// Detach the blur, keypress, and focus subscriptions in one call
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<p>Pass an array to subscribe to multiple events with the same callback</p>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smithfunction activate(e) { ... }
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke SmithgroupSub = inputNode.on(['focus', 'mouseover'], activate);
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith// Detach the focus and mouseover subscriptions
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<p>Prefix the event name with a category to allow detaching multiple
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithsubscriptions by that category.</p>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke SmithinputNode.on('my-category|focus', activate);
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke SmithinputNode.on('my-category|mouseover', activate);
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith// You can detach specific subscriptions by 'my-category|focus' or all with |*
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke SmithinputNode.detach('my-category|*');
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<p>The `once()` and `delegate()` methods also support these alternate
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithsignatures.</p>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<h4 id="extended-signature">Binding `this` and additional callback arguments</h4>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith By default, the "`this`" object in subscription callbacks will be the Node
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith or NodeList that subscribed to them. Override this default by passing your
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith own `this` object as the third argument to `on()` or the fourth to
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith `delegate()`. Note that the argument index is shifted when using `Y.on()`
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith and `Y.delegate()` or <a href="synths.html">synthetic events with custom
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith signatures</a>.
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith// equivalent to node.on('click', function (e) { overlay.hide(e); });
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith// `this` override comes after the filter; also shifted for the 'key' event's
b7514db172ccfbcf96d47baf7305d56c66ac832dRyuichi Okumura// custom signature.
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithcontainer.delegate('key', validator.isValid, 'enter,tab', 'input', validator);
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith// Corresponding alternatives from Y
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke SmithY.once('mouseover', door.unlock, '#gate13', door);
5d3dc0444c51f18e44c016a89b16a8951529518cLuke SmithY.delegate('key', validator.isValid, '#myForm', 'enter,tab', 'input', validator);
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<p>Additional arguments passed to the subscription methods will be sent along
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithto the callback after the event facade. If you want to bind extra arguments,
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smithbut don't want to override the "`this`" object, pass `null` for the `this`
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithargument.</p>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith someMethod: function (param) {
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Y.log(param); // => "I'm Extra!"
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith handleClick: function (e, extraParam) {
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smithvar instance = new Y.MyClass();
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith// The extra arg is passed as the second param to the callback after `e`
5d3dc0444c51f18e44c016a89b16a8951529518cLuke SmithY.one('#readygo').on('click', instance.handleClick, instance, "I'm Extra!");
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h4 id="detach-methods">More ways to clean up subscriptions</h4>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<p>There are a lot of options for detaching events in YUI. See the table below for details.</p>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <th>Method</th>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <th>What it does</th>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith var subscription = node.on('click', callback);
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Removes a specific subscription or, if created with one of the
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith group subscription methods, a group of subscriptions.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Generally, this is the best method to use.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <tr id="remove-by-category">
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith node.on('foo-category|click', callback);
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith node.detach('foo-category|click');
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith node.detach('foo-category|*');
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Removes a subscription or group of subscriptions that included
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith the specified category in the subscription event type.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith This is typically only safe in implementation code, not
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith module code, because multiple subscriptions using the same type
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith and category will be detached by the call to `detach`.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith node.detach('click', callback);
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith If you have a reference to the subscribed callback function,
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith (but not a subscription handle) use the two argument signature.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith With one argument, `detach` will remove all subscriptions for
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith the specified event. With no arguments, it removes all
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith subscriptions for all events.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith `detach` does not remove subscriptions from descendant nodes.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Works the same as `node.detach()`.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith node.purge(true, 'click');
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith With no arguments, `purge` works the same as `node.detach()`.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Passing `true` as a first argument will remove all
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith subscriptions for all events from the node <em>and its
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith descendant subtree</em>. Passing an event type as a second
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith argument will only deep purge subscriptions to that event.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Removes subscriptions for all events <em>only from the
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith descendants of a node</em> after removing them from the DOM.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith With no arguments, works like `node.detach()`.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith With `true` as a first argument, it works like
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith The `destroy` method does more than detaching event
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith subscribers. Read the
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <a href="{{apiDocs}}/classes/Node.html#method_destroy">API
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith docs</a> for details.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Y.Event.detach('click', callback, '#foo');
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Same as `Y.one('#foo').detach( [other args] )`.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Y.Event.purgeElement('#foo', true, 'click');
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Same as `Y.one('#foo').purge( [other args] )`.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h2 id="simulate">Simulate browser events</h2>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith For creating automated functional tests, being able to simulate user
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith interaction can be crucial. That's where the `node-event-simulate` module
5d3dc0444c51f18e44c016a89b16a8951529518cLuke SmithYUI().use('test', 'node-event-simulate', 'fancy', function (Y) {
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smithvar test = new Y.Test.Case({
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith "clicking close button should dismiss UI": function () {
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith var widget = new Y.MyFancyWidget().render('#here'),
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith uiBox = widget.get('boundingBox'),
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith closeButton = uiBox.one('.close-button');
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith `node.simulate( type, eventProperties )` creates a native DOM event that
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith will bubble (if appropriate), but will not trigger native default behavior.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith For example, `node.simulate('submit')` will not send data to the server for
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith a page reload.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<p>Read <a href="simulate.html">more about event simulation here</a>.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h2>Synthetic Events</h2>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>The event system supports adding new abstractions over the native DOM
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithenvironment that behave like DOM events. These abstractions are called
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithsynthetic events, and you can subscribe to them like any other DOM event with
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke SmithY.one('#dialog').on('clickoutside', function (e) {
2e7441169df0fcc324f2d44947beba7d237f5a37Luke SmithY.one('#editable-table').delegate('key', saveAndAdvance, 'tab', 'input');
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith The synthetic events that are available as core YUI modules are listed in
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <a href="#modules">the table of modules above</a>, though there are others
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <a href="http://yuilibrary.com/gallery/">in the Gallery</a>. Most events
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith listed in the table are linked to pages that describe the specific event in
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith more detail.
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<h4>Creating DOM events</h4>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>Create your own synthetic events with `Y.Event.define(type, config)`.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke SmithY.Event.define("tripleclick", {
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // The setup logic executed when node.on('tripleclick', callback) is called
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith on: function (node, subscription, notifier) {
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith // supporting methods can be referenced from `this`
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith this._clear(subscription);
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // To make detaching easy, a common pattern is to add the subscription
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // for the supporting DOM event to the subscription object passed in.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // This is then referenced in the detach() method below.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith subscription._handle = node.on('click', function (e) {
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith if (subscription._timer) {
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith if (++subscription._counter === 3) {
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith this._clear(subscription);
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // The notifier triggers the subscriptions to be executed.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // Pass its fire() method the triggering DOM event facade
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith subscription._timer =
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Y.later(300, this, this._clear, [subscription]);
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // The logic executed when the 'tripleclick' subscription is `detach()`ed
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith detach: function (node, subscription, notifier) {
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith // Clean up supporting DOM subscriptions and other external hooks
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith // when the synthetic event subscription is detached.
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith if (subscription._timer) {
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith // Additional methods can be added to support the lifecycle methods
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith _clear: function (subscription) {
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith subscription._counter = 0;
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith subscription._timer = null;
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>After the synthetic event is defined, it is available for every Node and
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke SmithNodeList to subscribe to.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke SmithY.one('#hellokitty').on('tripleclick', omgYayCantClickEnough);
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith<p>There is additional configuration to <a href="synths.html">add support for
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith`delegate()` or extra subscription arguments</a>, but often very little extra
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smithcode is needed.</p>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li><a href="#function-reference">My callback is executing at the wrong time. What's going on?</a></li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li><a href="#wrong-this">I'm getting an error in my callback that "(some object) has no method (someMethodOnMyObject)". What am I missing?</a></li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li><a href="#which-events">What events can I subscribe to?</a></li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li><a href="#why-on-no-chain">Why isn't on() chainable?</a></li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li><a href="#y-on-vs-node-on">Why would I use `Y.on()` or `Y.delegate()` instead of `node.on()` and `node.delegate()`?</a></li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li><a href="#after">EventTarget also provides an `after()` method. How does that work for DOM events?</a></li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li><a href="#nodelist-this">When I subscribe to an event from a NodeList, `this` is the NodeList, not the individual Node. What's up with that?</a></li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <li><a href="#nodelist-delegate">Where is `nodelist.delegate()`?</a></li>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <!--li><a href="#">What works and what doesn't on mobile browsers?</a></li-->
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h4 id="function-reference">My callback is executing at the wrong time. What's going on?</h4>
b7514db172ccfbcf96d47baf7305d56c66ac832dRyuichi Okumura<p>It's likely that you've included parenthesis in the subscription.</p>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smithnode.on('click', someFunction());
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smithnode.on('click', someFunction);
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smithnode.on('click', myObject.someFunction, myObject);
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Including the parens makes the function execute immediately, and pass the
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith return value from the function to `node.on('click', [RETURN VALUE])`. To
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith pass a function around, just omit the parens.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h4 id="wrong-this">I'm getting an error in my callback that "`(some object) has no method (someMethodOnMyObject)`". What am I missing?</h4>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith You may be passing an object method to `on()`, but forgot to include
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <a href="#extended-signature">the `this` object override parameter</a> in
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith the subscription.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Another option to make sure object methods are called with the correct
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith `this` object is to use
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <a href="{{apiDocs}}/classes/YUI.html#method_bind">`Y.bind(obj.method,
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith obj)`</a> or
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <a href="{{apiDocs}}/classes/YUI.html#method_rbind">`Y.rbind(obj.method,
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith// RIGHT (alternate)
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h4 id="which-events">What events can I subscribe to?</h4>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith It depends what modules you've included. Check out the
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <a href="#event-whitelist">whitelisted events table</a>.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h4 id="why-on-no-chain">Why isn't on() chainable?</h4>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith After much deliberation, the YUI team decided that returning a subscription
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith handle was preferable to chaining in order to better support clean event
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith detaching across the various scenarios that DOM and custom events are used.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith In any sizable application, managing event subscriptions becomes
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith increasingly important, and detaching events must be done with precision.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Because YUI allows duplicate subscriptions, any host-based detach method
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith will necessarily be less than 100% reliable with respect to avoiding
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith removal of subscriptions made by other parts of the system.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Otherwise, it's common to subscribe to events with anonymous functions,
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith which makes it impossible to detach the specific subscription by signature
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith because you don't have a function reference to use to identify the specific
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith subscription to remove. Subscription categories can be used, but
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <a href="#remove-by-category">are also less precise</a> than
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith dealing with a specific subscription object.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h4 id="y-on-vs-node-on">Why would I use `Y.on()` or `Y.delegate()` instead of `node.on()` and `node.delegate()`?</h4>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith It's <a href="#y-on">largely a stylistic preference</a>, but there are some
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith technical differences when passing a selector string as a the third
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith `Y.on('click', callback, '#some select.or-string')`.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith `Y.on()` uses the
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <a href="{{apiDocs}}/classes/Selector.html">Selector engine</a>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith directly rather than calling through `Y.all(...)`.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith The benefit here is that the Node and NodeList constructors add the
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith slightest bit of overhead to the subscription process.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith When passing a selector that matches multiple elements, the `this` in
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith the callback will be the individual Node, not a
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <a href="#nodelist-this">NodeList wrapping all matched elements</a>.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith If called before the elements matching the selector are attached to
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith the DOM, it will poll for a few seconds and automatically attach
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith the subscription when the first matching element is found.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith Note, if using a selector that matches multiple elements, the poll
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith will attach the subscription the first time Selector finds a match.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith This <em>may not include all the elements</em> because either the
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith DOM is not fully updated yet, or the code that adds the matching
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith elements may happen in batches.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <p>In practice, it is best to avoid reliance on this behavior.</p>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h4 id="after">`EventTarget` also provides an `after()` method. How does that work for DOM events?</h4>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith `node.after(...)` is equivalent to `node.on(...)`. The DOM doesn't expose
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith an "after" moment to hook into.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h4 id="nodelist-this">When I subscribe to an event from a NodeList, `this` is the NodeList, not the individual Node. What's up with that?</h4>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith In the callback, `e.currentTarget` will always refer to the individual Node.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith However, if you call
5d3dc0444c51f18e44c016a89b16a8951529518cLuke SmithY.all('#some select.or-string').on('click', function (e) {
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith // how do I reference the NodeList?
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith you can't reference the NodeList captured by `Y.all()` without calling
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith `Y.all()` again, but that results in unnecessary overhead, and may match
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith different elements in the subsequent call.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith In general, you should avoid `nodelist.on()` anyway,
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith <a href="#delegation">in favor of event delegation</a>.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith<h4 id="nodelist-delegate">Where is `nodelist.delegate()`?</h4>
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith The point of delegation is to reduce the number of subscriptions being made.
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith `nodelist.delegate()` would be philosophically at odds with that. Either
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith call `node.delegate()` from an element higher up the DOM tree, or <em>if
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith you must</em> delegate the same event and callback from multiple
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith containers, use
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smithnodelist.each(function (node) {
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith node.delegate('click', callback, '.not-recommended');
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith<h2>More Reading</h2>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith<h3><a href="domready.html">Page Lifecycle events</a></h3>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith Details about `domready`, `available`, and `contentready` events provided in
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith the event core. <a href="domready.html">Read more...</a>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith<h3><a href="delegation.html">Event Delegation</a></h3>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith What is event delegation and why you should be using it. A lot.
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith <a href="delegation.html">Read more...</a>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith<h3><a href="simulate.html">Event Simulation</a></h3>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith How to simulate user events like "click" or "keypress", what events can be
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove simulated, and some important caveats.
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith <a href="simulate.html">Read more...</a>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith<h3><a href="synths.html">Create New DOM Events</a></h3>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith How to create a tailor made DOM event for subscription or delegation from
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith any Node. This is a great way to encapsulate and label more comples user
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith <a href="synths.html">Read more...</a>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith<h3><a href="touch.html">Working With Touch Events</a></h3>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith Details on the supported touch events, the touch/mouse abstraction layer
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith events, and gesture based events like "flick".
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith <a href="touch.html">Read more...</a>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith<h3><a href="focus.html">Delegating the `focus` and `blur` Events</a></h3>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith Using the `event-focus` module to simulate support for bubbling `focus` and
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith `blur` events.
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith <a href="focus.html">Read more...</a>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith<h3><a href="mouseenter.html">The `hover`, `mouseenter`, and `mouseleave` Events</a></h3>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith Describes why `mouseenter` and `mouseleave` events are usually what you
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith want when you subscribe to `mouseover` and `mouseout`, and goes over using
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith the `hover` event (which uses the other two under the hood).
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith <a href="mouseenter.html">Read more...</a>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith<h3><a href="key.html">Complex Keyboard Input Filtering</a></h3>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith Using the `key` event to respond to specific users pressing specific keys or
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith or key combinations.
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith <a href="key.html">Read more...</a>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith<h3><a href="outside.html">Responding to Events <em>outside</em> of a Node</a></h3>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith Details the host of "outside" events that can be used to trigger behavior
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith when users interact with element outside of the relevant Node. Think
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith closing popups if a user clicks somewhere else on the page.
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith <a href="outside.html">Read more...</a>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith<h3><a href="valuechange.html">Monitoring Changes to `<input>` and `<textarea>` Values</a></h3>
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove Using the `valuechange` event to catch the moments when a user types, cuts,
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith pastes, or otherwise alters the value in an input field. No,
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith `input.on('change', callback)` is not enough.
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith <a href="valuechange.html">Read more...</a>
50e21a9dabd37b5e80bd7be7d95a6bc22bd659c1Luke Smith<h3><a href="contextmenu.html">Keyboard Accessible `contextmenu` Events</a></h3>
50e21a9dabd37b5e80bd7be7d95a6bc22bd659c1Luke Smith Repairing cross browser keyboard support for the `contextmenu` event.
50e21a9dabd37b5e80bd7be7d95a6bc22bd659c1Luke Smith <a href="contextmenu.html">Read more...</a>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<h2 id="event-whitelist">Appendix A: Whitelisted DOM events</h2>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<div id="events">
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <th>Event</th>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <th>Added by</th>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>abort</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>beforeunload</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>blur</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>change</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>click</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>close</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>command</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>contextmenu</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>dblclick</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>DOMMouseScroll</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>drag</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>dragstart</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>dragenter</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>dragover</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>dragleave</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>dragend</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>drop</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>error</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>focus</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>key</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>keydown</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>keypress</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>keyup</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>load</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>message</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>mousedown</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>mouseenter</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>mouseleave</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>mousemove</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>mousemultiwheel</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>mouseout</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>mouseover</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>mouseup</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>mousewheel</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>orientationchange</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>reset</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>resize</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>select</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>selectstart</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>submit</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>scroll</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>textInput</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>unload</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-base</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>DOMActivate</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>DOMContentLoaded</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>afterprint</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>beforeprint</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>canplay</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>canplaythrough</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>durationchange</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>emptied</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>ended</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>formchange</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>forminput</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>hashchange</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>input</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>invalid</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>loadedmetadata</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>loadeddata</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>loadstart</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>offline</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>online</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>pagehide</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>pageshow</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>pause</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>play</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>playing</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>popstate</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5 or history</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>progress</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>ratechange</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>readystatechange</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>redo</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>seeking</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>seeked</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>show</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>stalled</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>suspend</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>timeupdate</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>undo</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>volumechange</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>waiting</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>node-event-html5</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>touchstart</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>event-touch</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>touchmove</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>event-touch</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>touchend</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>event-touch</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>touchcancel</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>event-touch</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>gesturestart</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>event-touch</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>gesturechange</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>event-touch</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>gestureend</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>event-touch</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>transitionend or webkitTransitionEnd</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith <td>transition-native</td>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke SmithYUI({ filter: 'raw' }).use('selector-css3', 'datatable-sort', function (Y) {
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith var data = [],
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith node = Y.one('#events');
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith node.all('td:nth-of-type(1)').each(function (node, i) {
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith Event: node.get('text'),
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith "Added By": node.next().get('text')
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith node.empty().addClass('yui3-skin-sam');
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith columns : [ 'Event', 'Added By' ],
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith data : data,
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith sortable: true
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith }).render(node);
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<h4>Adding to the DOM event whitelist</h4>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<p>If you need to use an event that isn't included in this list, and not
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithsupplied by a synthetic event, you can expand the whitelist by adding the event
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithnames to the `Y.Node.DOM_EVENTS` object.</p>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith// Allow for subscription to some mostly cross-browser mutation events
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith DOMNodeInserted: true,
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith DOMNodeRemoved: true,
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith DOMCharacterDataModified: true
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<h2 id="facade-properties">Appendix B: EventFacade properties and methods</h2>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h4>Methods</h4>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Prevents the default action associated with the event. E.g. page
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith navigation from an <a>nchor `click` or form submission and
b7514db172ccfbcf96d47baf7305d56c66ac832dRyuichi Okumura page reload from a <form> `submit`.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Stops the event from bubbling further up the DOM tree. This does
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith not prevent the default action if there is one. Subsequent event
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith subscribers will be executed.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Stops the event from bubbling further up the DOM tree. This does
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith not prevent the default action if there is one. Subsequent event
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith subscribers will NOT be executed.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <dt>`e.halt( [immediate=false] )`</dt>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Alias for `e.preventDefault(); e.stopPropagation();` or
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith `e.preventDefault(); e.stopImmediatePropagation();`, depending on
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith the <em>immediate</em> parameter.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h4>Basics</h4>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith The name of the event. E.g. "click", "keyup", or "load".
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith The Node instance that originated the event (see <a
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith href="delegation.html">the description of event delegation</a> for
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith The Node instance that subscribed to the event. In the case of
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith subscriptions from NodeLists, this is still the individual Node
5d3dc0444c51f18e44c016a89b16a8951529518cLuke Smith instance (see <a href="#nodelist-this">When I subscribe to an event
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith from a NodeList, `this` is the NodeList...</a>).
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith For `mouseover` events, this will be the Node instance of where the
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith mouse travelled <em>from</em>. For `mouseout`, it will be the Node
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith that the mouse travelled <em>to</em>.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h4>Keyboard event properties</h4>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith The unicode value of a non-character key in a `keypress` event or
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith any key in `keydown` or `keyup`. See <a
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith href="https://developer.mozilla.org/en/DOM/event.keyCode">event.keyCode
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith The Unicode value of a character key pressed during a keypress
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith event. See <a
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith href="https://developer.mozilla.org/en/DOM/event.charCode">event.charCode
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith `true` if the shift key was depressed during a key event.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith `true` if the control key was depressed during a key event.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith `true` if the alt/option key was depressed during a key event.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith `true` if the "Windows" key on PCs or command key on Macs was
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith depressed during a key event.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h4>Mouse event properties</h4>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith For `mouseup` events (<em>NOT `click` events</em>), indicates
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith which mouse button is pressed.<br>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith `1` = left click, `2` = middle click, `3` = right click.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith The horizontal coordinate of the event relative to whole document.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith The vertical coordinate of the event relative to whole document.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith The horizontal coordinate of the event relative to viewport,
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith regardless of scrolling.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith The vertical coordinate of the event relative to viewport,
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith regardless of scrolling.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith For `mousewheel` or `DOMMouseScroll` events, the pixel distance of
f0c6ea80852372776eb29f6025415a4781f8211bSatyen Desai<h4>Touch event properties</h4>
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove An array of `Touch` objects, where each `Touch` object represents a finger
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove currently touching the surface (regardless of the target of the current event).
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove For example, if you have two fingers on the surface, this array would have two
f0c6ea80852372776eb29f6025415a4781f8211bSatyen Desai `Touch` objects, one for each finger.
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove The common set of properties currently on a `Touch` object, which can be
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove relied up across environments, are `target`, `clientX`, `clientY`, `pageX`,
f0c6ea80852372776eb29f6025415a4781f8211bSatyen Desai `pageY`, `screenX`, `screenY` and `identifier`.
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove An array of `Touch` objects for every point of contact that is touching the
f0c6ea80852372776eb29f6025415a4781f8211bSatyen Desai surface, and started on the element that is the target of the current event.
f0c6ea80852372776eb29f6025415a4781f8211bSatyen Desai An array of `Touch` objects representing all touches that changed in this event.
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove This property is most useful in `touchEnd` events, to identify the set of touches
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove which were removed from the surface, which resulted in the firing of the event.
f0c6ea80852372776eb29f6025415a4781f8211bSatyen Desai<h4>Gesture event properties (currently iOS specific)</h4>
f0c6ea80852372776eb29f6025415a4781f8211bSatyen Desai<p>These properties are unique to Webkit on iOS currently, and are provided on the event facade when listening for the iOS `gesturestart`, `gesturechange` and `gestureend` multi-touch events.</p>
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove See Apple's documentation for <a href="http://developer.apple.com/library/safari/documentation/UserExperience/Reference/GestureEventClassReference/GestureEvent/GestureEvent.html#//apple_ref/javascript/instp/GestureEvent/scale">scale</a>.
f0c6ea80852372776eb29f6025415a4781f8211bSatyen Desai See Apple's documentation for <a href="http://developer.apple.com/library/safari/documentation/UserExperience/Reference/GestureEventClassReference/GestureEvent/GestureEvent.html#//apple_ref/javascript/instp/GestureEvent/rotation">rotation</a>.
f0c6ea80852372776eb29f6025415a4781f8211bSatyen Desai<p>See the <a href="http://www.w3.org/TR/touch-events/">W3C Touch Events Specification</a>, derived from the Webkit model, for more details.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>Synthetic events may add or modify event facade properties. These should be included in the documentation for the specific synthetic event.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>For more details, check out the <a
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithhref="https://developer.mozilla.org/en/DOM/event#Properties">MDC
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithdocumentation</a>.</p>