index.mustache revision 949cffcab80cdd0b820d11da7f7514cfd070d9fa
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith text-transform: none;
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
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith href="../event-custom/">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
3cf5fc12a9b3107d66037af19814b4266dacf8eaLuke Smith<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
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<a href="#more-options">other subscription methods</a> return a
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithsubscription object that can be used to unbind that subscription. Node also
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithsupports a `detach()` method and <a href="#detach-methods">other ways to cleaup
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.
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke SmithThere's [[#More Options|a lot more you can do]], though, so read on!</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h2 id="modules">What to `use()`</h2>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>Before we get into more API goodies, let's talk about the Event Utility's module breakdown.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>For starters, in most cases <em>you probably won't
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith`use('event')`</em>. The core DOM event system ("event-base") is required by
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smiththe "node-base" module, which itself if required by just about everything in
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke SmithYUI. So you probably already have the DOM event API and didn't know it!</p>
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>
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith The Core DOM event subscription system as well as the DOM lifecycle
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith events <a href="domready.html">`domready`, `contentready`, and
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith `available`</a>. Notably, it does NOT include
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li>event delegation</li>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li>event simulation</li>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li>synthetic events</li>
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,
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith respectively, for [[#Event Delegation|event delegation]] convenience.
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <td><a href="{{apiDocs}}/module_event-simulate.html">`event-simulate`</a></td>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <p>Adds APIs for triggering native DOM events for unit testing.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <p><strong>Note: <a href="#faking">Faking DOM events should not be
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith used in user facing code</a></strong>.</p>
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>
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith Adds a <a href="mouseenter.html">"hover" event</a> which binds to
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith two callbacks, one for the start, and one for the end of a mouse
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
2e7441169df0fcc324f2d44947beba7d237f5a37Luke 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>
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith Adds a <a href="valuechange.html">"valueChange" event</a> that fires when input element text
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith changes (this is harder than you think).
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h2>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>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke 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>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<h2>More Options</h2>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<h4>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]");
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<p>An alternate syntax for DOM subscriptions is using `Y.on()` or
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith`Y.delegate()`. When identifying the target by a CSS selector, these methods
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithcan be used regardless if the element is currently available for scripting. If
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithit's not yet on the page, a poll will regularly look for it (for a few seconds)
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithand the subscription will be automatically attached when the element is
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithfound. Relying on this behavior can introduce race conditions, though, so use
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithit wisely. Otherwise, use of `node.on()` or `Y.on()` is a stylistic
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithpreference.</p>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<h4 id="once">One time subscriptions</h4>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke SmithtabLabel.once('mouseover', loadTabContent);
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke 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 be automatically detached after the event fires.</p>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<p>The signature for `once()` is the same as that for `on()`.</p>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<h4>Grouping subscriptions</h4>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<p>Pass an object to subscribe to multiple events, each with their own
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithvar groupSub = inputNode.on({
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith blur: validate,
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith keypress: validate,
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke 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>
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>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<p>By default, the "`this`" object in subscription callbacks will be the Node
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithor NodeList that subscribed to them. Override this default by passing your own
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith`this` object as the third argument to `node.on()` or the fourth to
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith`node.delegate()`. Note that the argument index is shifted when using `Y.on()`
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithand `Y.delegate()` or synthetic events with custom signatures.</p>
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
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith// custome 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);
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke SmithY.delegate('click', 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,
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithbut don't want to override the "`this'" object, pass `null` for the `this`
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smithargument.</p>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<h4>More ways to clean up subscriptions</h4>
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith<h2>Event Simulation</h2>
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');
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>The available synthetic events are listed in <a href="#modules">the table of
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smithmodules above</a>. Most are linked to pages further detailing the specific eevnts.</p>
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>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li><a href="#">My callback is executing at the wrong time. What's going on?</a></li>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li><a href="#">I'm getting an error in my callback that "(some object) has no method (someMethodOnMyObject)". What am I missing?</a></li>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li><a href="#">What events can I subscribe to?</a></li>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li><a href="#">Why isn't on() chainable?</a></li>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li><a href="#">Why would I use `Y.on()` or `Y.delegate()` instead of `node.on()` and `node.delegate()`?</a></li>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li><a href="#">EventTarget also provides an `after()` method. How does that work for DOM events?</a></li>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li><a href="#">When I subscribe to an event from a NodeList, `this` is the NodeList, not the individual Node. What's up with that?</a></li>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li><a href="#">Where is `nodelist.delegate()`?</a></li>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li><a href="#">What works and what doesn't on mobile browsers?</a></li>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li><a href="#faking">Why shouldn't I fake DOM events in user facing code?</a></li>
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');
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith columnset: [
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith { key: 'Event', sortable: true },
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith { key: 'Added By', sortable: true }
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith recordset: data
42f04b06465678a6d795fc4c3aa4bcc5aa8bfda8Luke Smith }).plug(Y.Plugin.DataTableSort).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
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith page reload from a %lt;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
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith href="#currenttarget">What's the difference between `e.target` and
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
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith instance (see <a href="#nodelistthis">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
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h4>Touch/Mobile related properties</h4>
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>