index.mustache revision e9b01de77b1a53553e58caf4f0c5392735102fc1
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>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>The primary workhorse for the event system is the `on()` method. It is
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithavailable on every <a href="../node/">`Node`</a> and <a href="../node/#nodelist">`NodeList`</a>.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith// Step 1. Capture a button node
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithvar button = Y.one("#readygo");
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithfunction handleClick(e) {
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // Step 3. do stuff
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith// Step 2. subscribe to its click event to execute `handleClick`
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithbutton.on("click", handleClick)
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>Replace "click" with any other event name to subscribe to that event.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>The callback will always receive a first argument `e`, which is a normalized
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithevent object called an "event facade". Meanwhile, the `this` in the callback
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithwill refer to the Node or NodeList that you subscribed from.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithfunction handleClick(e) {
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // `this` is the button Node, NOT the DOM element
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Y.log(this.get('id')); // 'readygo' (from <button id="readygo">...</button>)
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // Event properties that point to the DOM are also Node instances
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // Stop the event's default behavior
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // Stop the event from bubbling up the DOM tree
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>Look at <a href="appendix-b">Appendix B</a> (or the API docs) for a full list
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithof event facade properties and methods.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>An alternate syntax for DOM subscriptions is using `Y.on()`. Read more about <a href="#yon">using `Y.on()` instead of `node.on()`</a>.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith// Y.on() takes a third argument which is the Node, DOM element,
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith// or CSS selector of the element(s) to bind
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke SmithY.on("click", handleClick, "#readygo");
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h4>Detaching subscriptions</h4>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>`node.on()` and all [[#One time subscriptions|other subscription methods]]
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithreturn a subscription object that can be used to unbind that subscription.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke SmithNode also supports a `detach()` method and
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith[[#More ways to cleanup subscriptions|other ways to cleaup subscriptions]].</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.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke SmithThere's [[#Advanced 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>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <td>`event-base`</td>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith The Core DOM event subscription system as well as the <a
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith href="domready.html">DOM lifecycle events</a> `domready`,
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith `available`, and `contentready`. Notably, it does NOT include
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li>event delegation</li>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li>event simulation</li>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <li>synthetic events</li>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <td>`event`</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>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <td>`event-delegate` &
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <spen style="white-space: nowrap;"`node-event-delegate`</span></td>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Adds the `Y.delegate(...)` and `node.delegate(...)` methods,
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith respectively, for [[#Event Delegation|event delegation]] convenience.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <td>`event-simulate`</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>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <td>`event-synthetic`</td>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Supplies the infrastructure for "fixing" DOM events with
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith undesirable or inconsistent behavior. Also for creating new DOM
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith events. Most of the modules below are synthetics.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <td><a href="touch.html#flick">`event-flick`</a></td>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Adds a "flick" event for touch or mouse interaction.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <td><a href="focus.html">`event-focus`</a></td>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Fixes `focus` and `blur` events to bubble (for delegation).
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <td><a href="mouseenter.html">`event-hover`</a></td>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Adds a "hover" event which binds to two callbacks, one for the
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith start, and one for the end of a mouse hover.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <td><a href="key.html">`event-key`</a></td>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Adds a "key" event which listens for specific, implementer defined,
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith keys being pressed by the user.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <td><a href="mouseenter.html">`event-mouseenter`</a></td>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Adds "mouseenter" and "mouseleave" events. You probably want to
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith use these instead of "mouseover" and "mouseout".
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <td><a href="mousewheel.html">`event-mousewheel`</a></td>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Adds a "mousewheel" event for monitoring window scrolling.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Currently, this event can only be subscribed with
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith `Y.on("mousewheel", callback)`;
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <td><a href="touch.html#move">`event-move`</a></td>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Adds "gesturemovestart", "gesturemove", and "gesturemoveend" events
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith that serve as abstractions over mouse and touch events, forking
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith internally based on the client device.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <td><a href="outside.html">`event-outside`</a></td>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Adds a "clickoutside" and several other ___outside events to trigger
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith behavior based on actions taken outside a specific element.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <td><a href="windowresize.html">`event-resize`</a></td>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Adds a "windowresize" event to normalize reporting of the
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith `window`'s resize event.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <td><a href="touch.html">`event-touch`</a></td>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Adds support for subscribing to native touch and gesture events.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith <td><a href="valuechange.html">`event-valuechange`</a></td>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith Adds a "valuechange" event 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');
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>For more complex target filtering, a function can be passed instead of a css selector. See the <a href="{{apiDocs}}/module_event-delegate.html#method_delegate">API docs</a> for more details.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>As noted <a href="modules">above</a>, the `event-delegate` module is included in the `event` rollup, but `node-event-delegate` isn't. We recommend using delegation from the Node API, so you should `use()` either `node-event-delegate` or the `node` rollup.</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) {
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>You can do all sorts of things with synthetic events, including:</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith redefine native DOM events that behave inconsistently across browsers
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith (e.g. `focus` and `blur`)
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith provide abstract events that attach to different DOM events based on
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith the environment (e.g. `gesturemovestart` and family)
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith create events with different subscription signatures (e.g. `hover` or
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith create configurable events that only execute subscribers when criteria
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith passed during subscription are met (e.g. `flick` or `valuechange`)
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith create events that encapsulate common UX patterns (e.g. `clickoutside`)
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith create fun little easter eggs (e.g. <a
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith href="http://yuilibrary.com/gallery/show/event-konami">`konami`</a>)
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>The available synthetic events are listed in <a href="#modules">the table of
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithmodules above</a>.</p>
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) {
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) {
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // Clean up supporting DOM subscriptions when the synthetic event
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // subscription is detached.
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // The setup logic executed for `node.delegate('tripleclick', ...)`
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith delegate: function (node, subscription, notifier, filter) { ... },
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // Detach logic for delegate subscriptions
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith detachDelegate: function (node, subscription, notifier, filter) { ... },
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith // supporting methods can be referenced from `this`
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith _clear: function (subscription) {
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith subscription._counter = 0;
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith subscription._timer = null;
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>The delegation logic was omitted for brevity, but `delegate()` support and
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smithcustom subscription signatures are <a href="synths.html">detailed here</a>.</p>
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);
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h2>Advanced Options</h2>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h3>Binding `this` and additional callback arguments</h3>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h3>One time subscriptions</h3>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h3>Grouping subscriptions</h3>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke SmithThree ways, on({}), on([]), on('cat:type')
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h3>More ways to clean up subscriptions</h3>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h3>Adding to the DOM event whitelist</h3>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h3>Capture phase subscriptions</h3>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h3>Facade-less subscriptions</h3>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h3>Event Simulation</h3>
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>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h2>Appendix A: Whitelisted DOM events</h2>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<p>Also see the list of <a href="#synthetics">synthetic DOM events</a>.</p>
e9b01de77b1a53553e58caf4f0c5392735102fc1Luke Smith<h2 id="appendix-b">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>