daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<style>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith h4 code {

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith text-transform: none;

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith }

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith .yui3-skin-sam td {

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith background-color: #E6E9F5;

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith }

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith .yui3-skin-sam .yui3-datatable td {

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith background-color: transparent;

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith }

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith</style>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<div class="intro component">

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <p>The YUI Event Utility provides APIs for working with the browser's DOM

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith event system. It simplifies tasks like subscribing to button `click`s or

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith canceling &lt;form&gt; `submit`s to, for example, allow sending data to the

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith server via ajax.</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <p>In addition, the "Synthetic event" system supplies <em>entirely new</em>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith DOM events to subscribe to as well as fixing events that behave differently

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith across browsers. Implementers can create their own DOM events triggered by

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith specific user actions or other environmental criteria.</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <p>The API for working with DOM events is provided by the EventTarget class,

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith which also services the Custom event infrastructure that is used throughout

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith YUI. Read more about working with custom events <a

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith href="../event-custom/index.html">in the EventTarget user guide</a>.</p>

949cffcab80cdd0b820d11da7f7514cfd070d9faEric Ferraiuolo</div>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

949cffcab80cdd0b820d11da7f7514cfd070d9faEric Ferraiuolo{{>getting-started}}

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h2>The Basics</h2>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h4>Listening for events</h4>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith```

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// Step 1. Capture a button node

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar button = Y.one("#readygo");

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// Step 2. Subscribe to its click event with a callback function

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithbutton.on("click", function (e) {

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith // Step 3. do stuff when the button is clicked

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith});

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith```

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<p><code>on(<em>type</em>, <em>callback</em>)</code> is the main

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithsubscription method, and is available on every <a href="../node/">`Node`</a>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithand <a href="../node/#nodelist">`NodeList`</a>.</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<p>Replace "click" with <a href="#event-whitelist">any other event name</a> to subscribe to that event.</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h4>The Callback and the Event Object</h4>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith```

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithbutton.on('click', function (e) {

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith // `this` is the button Node, NOT the DOM element

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith this.get('id'); // ==> 'readygo' (from <button id="readygo">...</button>)

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith // Event properties that point to the DOM are also Node instances

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith e.target.get('id'); // => 'readygo'

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith // Stop the event's default behavior

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith e.preventDefault();

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith // Stop the event from bubbling up the DOM tree

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith e.stopPropagation();

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith});

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith```

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<p>Subscribed callbacks are passed a <a href="#facade-properties">a normalized

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithevent object</a> as their first argument.</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<p>The keyword "`this`" in the callback will refer to the Node or NodeList

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smiththat you subscribed from.</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h4>`e.preventDefault()` and `e.stopPropagation()`</h4>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<p>Many events have a default behavior, such as the `submit` event serializing

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithform data and making a new page request. Disable this behavior with

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith`e.preventDefault()`.</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith```

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithfunction setFilter(e) {

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith // Stop the link from loading the href page

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith e.preventDefault();

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith // Now do my own thing instead

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith var url = this.get('href').replace(/page/, 'partial');

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Y.one('#contentArea').load(url);

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith // `return false` is supported, but not preferred. use e.preventDefault()

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith return false;

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith}

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithY.one('#table-filter-link').on('click', setFilter);

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith```

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<p>Most events can be listened for on the specific element that originates them

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<em>or from any of their parent elements</em>, all the way up to the

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith`document`. Prevent dispatching the event to subscriptions bound to elements

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithfurther up the DOM tree with `e.stopPropagation()`. In practice, this is

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithrarely useful.</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<p>Returning `false` from a callback will also stop the propagation of the

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithevent, which may cause unintended side effects.</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<p>`e.stopPropagation()` won't prevent the execution of other subscribers

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithlistening to the same element, only elements further up the DOM tree. If you

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithneed to stop all execution, use `e.stopImmediatePropagation()` or

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith`e.halt(true)`. The latter will also call `e.preventDefault()`.</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h4>Detaching subscriptions</h4>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<p>`node.on()` and all

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<a href="#more">other subscription methods</a> return a

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithsubscription object that can be used to unbind that subscription. Node also

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithsupports a `detach()` method and <a href="#detach-methods">other ways to cleanup

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithsubscriptions</a>.</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith```

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// on() returns a subscription handle...

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar sub = button.on("click", handleClick);

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// ...that can be used to unbind the subscription

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithsub.detach();

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// Alternately, use the Node's detach() method

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithbutton.detach("click", handleClick);

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith```

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<p>Just this should take care of most of the simple event bindings you'll need.

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithThere's <a href="#more">a lot more you can do</a>, though, so read on!</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h2 id="modules">What to `use()`</h2>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Before we get into <a href="#more">more API goodies</a>, let's talk about

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith the Event Utility's module breakdown.

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith For starters, in most cases <em>you probably won't `use('event')`</em>.

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith The core DOM event system ("event-base") is required by the "node-base"

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith module, which itself if required by just about everything in YUI. So you

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith probably already have the DOM event API and didn't know it!

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith<p>Here is the full breakdown of modules in the DOM event system:</p>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith<table>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith<thead>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <tr>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <th>`use("______", ...)`</th>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <th>What's in it?</th>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith</thead>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<tbody>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <tr>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <td><a href="{{apiDocs}}/module_event-base.html">`event-base`</a></td>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <td>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <p>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith The core DOM event subscription system as well as the DOM

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith lifecycle events <a href="domready.html">`domready`,

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith `contentready`, and `available`</a>. Notably, it does NOT

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith include

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith </p>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <ul>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <li>event delegation</li>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <li>event simulation</li>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <li>synthetic events</li>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </ul>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <p>If you've `use()`d anything, you probably have this already.</p>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith </td>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith </tr>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <tr>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <td><a href="{{apiDocs}}/module_event.html">`event`</a></td>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith A rollup of all modules below except

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <ul>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <li>"event-simulate"</li>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <li>"node-event-simulate"</li>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <li>"node-event-delegate" (which is in the "node" rollup)</li>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </ul>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <tr>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <td><a href="{{apiDocs}}/module_event-delegate.html">`event-delegate`</a> &amp;

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <br>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <a style="white-space: nowrap;" href="{{apiDocs}}/module_node-event-delegate.html">`node-event-delegate`</a></td>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <td>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith Adds the `Y.delegate(...)` and `node.delegate(...)` methods,

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith respectively, for <a href="#delegation">event delegation</a>

14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith convenience.

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><a href="{{apiDocs}}/module_event-simulate.html">`event-simulate`</a> &amp;

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <br>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <a style="white-space: nowrap;" href="{{apiDocs}}/module_node-event-simulate.html">`node-event-simulate`</a></td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Adds `Y.Event.simulate(...)` and `node.simulate(...)` for

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <a href="#simulate">triggering native DOM events</a> for

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith unit testing.

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <strong>Note: <a href="simulate.html#faking">Faking DOM events

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith should not be used in user facing code</a></strong>.

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><a href="{{apiDocs}}/module_event-synthetic.html">`event-synthetic`</a></td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <p>Supplies the infrastructure for creating new DOM events, "fixing"

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith existing events with undesirable or inconsistent behavior, and

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <a href="synths.html">all sorts of other things</a>.</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <p>All of the modules below are synthetics.</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><a href="{{apiDocs}}/module_event-flick.html">`event-flick`</a></td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Adds a <a href="touch.html#flick">"flick" event</a> for touch or

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith mouse interaction.

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><a href="{{apiDocs}}/module_event-focus.html">`event-focus`</a></td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <a href="focus.html">Fixes `focus` and `blur` events</a> to bubble

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith (for delegation).

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><a href="{{apiDocs}}/module_event-gestures.html">`event-gestures`</a></td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <p>A rollup of the following modules:</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <ul>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <li>"event-touch"</li>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <li>"event-move"</li>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <li>"event-flick"</li>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </ul>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <p>In the future, may contain more gesture abstraction modules.</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><a href="{{apiDocs}}/module_event-hover.html">`event-hover`</a></td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Adds a <a href="mouseenter.html#hover">"hover" event</a> which

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith binds to two callbacks, one for the start, and one for the end of a

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith mouse hover.

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><a href="{{apiDocs}}/module_event-key.html">`event-key`</a></td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Adds a <a href="key.html">"key" event</a> which listens for

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith specific, implementer defined, keys being pressed by the user.

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><a href="{{apiDocs}}/module_event-mouseenter.html">`event-mouseenter`</a></td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Adds <a href="mouseenter.html">"mouseenter" and "mouseleave"

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith events</a>. You probably want to use these instead of "mouseover"

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith and "mouseout".

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><a href="{{apiDocs}}/module_event-mousewheel.html">`event-mousewheel`</a></td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <p>Adds a "mousewheel" event for monitoring users scrolling the

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith window with the mousewheel. Event facades passed to the callback

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith will have an `e.wheelDelta` property corresponding to the amount of

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith scrolling.</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <p>Currently, this event can only be subscribed with

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith `Y.on("mousewheel", callback)`;</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><a href="{{apiDocs}}/module_event-move.html">`event-move`</a></td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Adds <a href="touch.html#move">"gesturemovestart", "gesturemove",

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith and "gesturemoveend" events</a> that serve as abstractions over

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith mouse and touch events, forking internally based on the client

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith device.

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><a href="{{apiDocs}}/module_event-outside.html">`event-outside`</a></td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Adds a <a href="outside.html">"clickoutside" and several other

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith outside events</a> to trigger behavior based on actions taken

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith outside a specific element.

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><a href="{{apiDocs}}/module_event-resize.html">`event-resize`</a></td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <p>Adds a "windowresize" event that only fires after a user has

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith stopped dragging a window's resize handle. This normalizes the

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith `window.onresize` event across browsers.</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <p>This event can only be subscribed with

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith `Y.on("windowresize", callback)`;</p>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><a href="{{apiDocs}}/module_event-touch.html">`event-touch`</a></td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Adds support for <a href="touch.html">subscribing to native touch

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith and gesture events</a>.

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith </tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <tr>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><a href="{{apiDocs}}/module_event-valuechange.html">`event-valuechange`</a></td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>

daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Adds a <a href="valuechange.html">"valuechange" event</a> that fires when input element text

changes (this is harder than you think).

</td>

</tr>

<tr>

<td><a href="{{apiDocs}}/module_event-contextmenu.html">`event-contextmenu`</a></td>

<td>

<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>.

</td>

</tr>

</tbody>

</table>

<h2 id="delegation">Event Delegation</h2>

<p>If you don't already know what event delegation is, you should <a

href="delegation.html">read this quick overview</a>. Short form: <em>you need

to be using this</em>.</p>

```

// single element subscription

node.on("click", handleClick);

// delegated subscription for all button clicks from inside the node

node.delegate("click", handleClick, "button, input[type=button]");

```

<p>Creating a delegated subscription looks very much like creating any other

event subscription with two differences. First, it's a different method name,

`delegate`. Second, there is another argument: a CSS selector that is used to

test the event's originating element to decide if the callback should be

executed. If the event started at or inside an element matching the selector,

the callback will execute.</p>

<p>Unlike `node.on()` subscriptions, the `this` object in `node.delegate()`

callbacks will refer to the element that matched the css filter, not to `node`.

We did this because likely your logic revolves around the nodes described by

the filter, not around the element that contains them.</p>

```

function handleClick (e) {

// `this` is the button with class .remove, not the #items element

// remove the containing LI

this.ancestor('li').remove();

// e.currentTarget is also the button.remove

// e.container === Y.one('#items')

}

Y.one('#items').delegate('click', handleClick, 'button.remove');

```

<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>

<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>

<h2 id="more">More Event API Goodness</h2>

<p>

Here is a sampling of some of the other ways to manage event subscriptions

in YUI.

</p>

<h4 id="y-on">Subscribe from `Y`</h4>

```

// Y.on() takes a third argument which is the Node, DOM element,

// or CSS selector of the element(s) to bind

Y.on("click", handleClick, "#readygo");

// Y.delegate() similarly takes the containing element or selector

// as the third argument

Y.delegate("click", handleClick, "#container", "button, input[type=button]");

```

<p>

An alternate syntax for DOM subscriptions is using `Y.on()` or

`Y.delegate()`. When identifying the target by a CSS selector, these

methods can be used regardless if the element is currently available for

scripting. If it's not yet on the page, a poll will regularly look for it

(for a few seconds) and the subscription will be automatically attached

when the element is found. Relying on this behavior can introduce race

conditions, though, so use it wisely.

</p>

<p>

Use of `Y.on()` instead of `node.on()` is largely a stylistic preference,

though <a href="#y-on-vs-node-on">there are some technical differences</a>.

</p>

<h4 id="once">One time subscriptions</h4>

```

tabLabel.once('mouseover', loadTabContent);

```

<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>

<p>The signature for `once()` is the same as `on()`.</p>

<h4>Grouping subscriptions</h4>

<p>Pass an object to subscribe to multiple events, each with their own

callback</p>

```

function validate(e) { ... }

function clearPlaceholder(e) { ... }

var groupSub = inputNode.on({

blur : validate,

keypress: validate,

focus : clearPlaceholder

});

// Detach the blur, keypress, and focus subscriptions in one call

groupSub.detach();

```

<p>Pass an array to subscribe to multiple events with the same callback</p>

```

function activate(e) { ... }

groupSub = inputNode.on(['focus', 'mouseover'], activate);

// Detach the focus and mouseover subscriptions

groupSub.detach();

```

<p>Prefix the event name with a category to allow detaching multiple

subscriptions by that category.</p>

```

inputNode.on('my-category|focus', activate);

inputNode.on('my-category|mouseover', activate);

// You can detach specific subscriptions by 'my-category|focus' or all with |*

inputNode.detach('my-category|*');

```

<p>The `once()` and `delegate()` methods also support these alternate

signatures.</p>

<h4 id="extended-signature">Binding `this` and additional callback arguments</h4>

<p>

By default, the "`this`" object in subscription callbacks will be the Node

or NodeList that subscribed to them. Override this default by passing your

own `this` object as the third argument to `on()` or the fourth to

`delegate()`. Note that the argument index is shifted when using `Y.on()`

and `Y.delegate()` or <a href="synths.html">synthetic events with custom

signatures</a>.

</p>

```

// equivalent to node.on('click', function (e) { overlay.hide(e); });

node.on('click', overlay.show, overlay);

node.once('mouseover', door.unlock, door);

// `this` override comes after the filter; also shifted for the 'key' event's

// custom signature.

container.delegate('key', validator.isValid, 'enter,tab', 'input', validator);

// Corresponding alternatives from Y

Y.on('click', overlay.show, '#show', overlay);

Y.once('mouseover', door.unlock, '#gate13', door);

Y.delegate('key', validator.isValid, '#myForm', 'enter,tab', 'input', validator);

```

<p>Additional arguments passed to the subscription methods will be sent along

to the callback after the event facade. If you want to bind extra arguments,

but don't want to override the "`this`" object, pass `null` for the `this`

argument.</p>

```

MyClass.prototype = {

someMethod: function (param) {

Y.log(param); // => "I'm Extra!"

},

handleClick: function (e, extraParam) {

this.someMethod(extraParam);

...

},

...

};

var instance = new Y.MyClass();

// The extra arg is passed as the second param to the callback after `e`

Y.one('#readygo').on('click', instance.handleClick, instance, "I'm Extra!");

```

<h4 id="detach-methods">More ways to clean up subscriptions</h4>

<p>There are a lot of options for detaching events in YUI. See the table below for details.</p>

<table>

<thead>

<tr>

<th>Method</th>

<th>What it does</th>

</tr>

</thead>

<tbody>

<tr>

<td>

```

var subscription = node.on('click', callback);

subscription.detach();

```

</td>

<td>

<p>

Removes a specific subscription or, if created with one of the

group subscription methods, a group of subscriptions.

</p>

<p>

Generally, this is the best method to use.

</p>

</td>

</tr>

<tr id="remove-by-category">

<td>

```

node.on('foo-category|click', callback);

node.detach('foo-category|click');

// OR

node.detach('foo-category|*');

```

</td>

<td>

<p>

Removes a subscription or group of subscriptions that included

the specified category in the subscription event type.

</p>

<p>

This is typically only safe in implementation code, not

module code, because multiple subscriptions using the same type

and category will be detached by the call to `detach`.

</p>

</td>

</tr>

<tr>

<td>

```

node.detach('click', callback);

// OR

node.detach('click');

// OR

node.detach():

```

</td>

<td>

<p>

If you have a reference to the subscribed callback function,

(but not a subscription handle) use the two argument signature.

</p>

<p>

With one argument, `detach` will remove all subscriptions for

the specified event. With no arguments, it removes all

subscriptions for all events.

</p>

<p>

`detach` does not remove subscriptions from descendant nodes.

</p>

</td>

</tr>

<tr>

<td>

```

node.detachAll();

```

</td>

<td>

<p>

Works the same as `node.detach()`.

</p>

</td>

</tr>

<tr>

<td>

```

node.purge();

// OR

node.purge(true);

// OR

node.purge(true, 'click');

```

</td>

<td>

<p>

With no arguments, `purge` works the same as `node.detach()`.

</p>

<p>

Passing `true` as a first argument will remove all

subscriptions for all events from the node <em>and its

descendant subtree</em>. Passing an event type as a second

argument will only deep purge subscriptions to that event.

</p>

</td>

</tr>

<tr>

<td>

```

node.empty();

```

</td>

<td>

<p>

Removes subscriptions for all events <em>only from the

descendants of a node</em> after removing them from the DOM.

</p>

</td>

</tr>

<tr>

<td>

```

node.destroy();

// OR

node.destroy(true);

```

</td>

<td>

<p>

With no arguments, works like `node.detach()`.

</p>

<p>

With `true` as a first argument, it works like

`node.purge(true)`.

</p>

<p>

The `destroy` method does more than detaching event

subscribers. Read the

<a href="{{apiDocs}}/classes/Node.html#method_destroy">API

docs</a> for details.

</p>

</td>

</tr>

<tr>

<td>

```

Y.Event.detach('click', callback, '#foo');

```

</td>

<td>

<p>

Same as `Y.one('#foo').detach( [other args] )`.

</p>

</td>

</tr>

<tr>

<td>

```

Y.Event.purgeElement('#foo', true, 'click');

```

</td>

<td>

<p>

Same as `Y.one('#foo').purge( [other args] )`.

</p>

</td>

</tr>

</tbody>

</table>

<h2 id="simulate">Simulate browser events</h2>

<p>

For creating automated functional tests, being able to simulate user

interaction can be crucial. That's where the `node-event-simulate` module

comes in.

</p>

```

YUI().use('test', 'node-event-simulate', 'fancy', function (Y) {

var test = new Y.Test.Case({

...

"clicking close button should dismiss UI": function () {

var widget = new Y.MyFancyWidget().render('#here'),

uiBox = widget.get('boundingBox'),

closeButton = uiBox.one('.close-button');

closeButton.simulate('click');

Y.Assert.isFalse( uiBox.inDoc() );

},

...

```

<p>

`node.simulate( type, eventProperties )` creates a native DOM event that

will bubble (if appropriate), but will not trigger native default behavior.

For example, `node.simulate('submit')` will not send data to the server for

a page reload.

</p>

<p>Read <a href="simulate.html">more about event simulation here</a>.</p>

<h2>Synthetic Events</h2>

<p>The event system supports adding new abstractions over the native DOM

environment that behave like DOM events. These abstractions are called

synthetic events, and you can subscribe to them like any other DOM event with

`node.on()` or `node.delegate()`.</p>

```

Y.one('#dialog').on('clickoutside', function (e) {

this.transition('fadeOut');

});

Y.one('#editable-table').delegate('key', saveAndAdvance, 'tab', 'input');

```

<p>

The synthetic events that are available as core YUI modules are listed in

<a href="#modules">the table of modules above</a>, though there are others

<a href="http://yuilibrary.com/gallery/">in the Gallery</a>. Most events

listed in the table are linked to pages that describe the specific event in

more detail.

</p>

<h4>Creating DOM events</h4>

<p>Create your own synthetic events with `Y.Event.define(type, config)`.</p>

```

Y.Event.define("tripleclick", {

// The setup logic executed when node.on('tripleclick', callback) is called

on: function (node, subscription, notifier) {

// supporting methods can be referenced from `this`

this._clear(subscription);

// To make detaching easy, a common pattern is to add the subscription

// for the supporting DOM event to the subscription object passed in.

// This is then referenced in the detach() method below.

subscription._handle = node.on('click', function (e) {

if (subscription._timer) {

subscription._timer.cancel();

}

if (++subscription._counter === 3) {

this._clear(subscription);

// The notifier triggers the subscriptions to be executed.

// Pass its fire() method the triggering DOM event facade

notifier.fire(e);

} else {

subscription._timer =

Y.later(300, this, this._clear, [subscription]);

}

});

},

// The logic executed when the 'tripleclick' subscription is `detach()`ed

detach: function (node, subscription, notifier) {

// Clean up supporting DOM subscriptions and other external hooks

// when the synthetic event subscription is detached.

subscription._handle.detach();

if (subscription._timer) {

subscription._timer.cancel();

}

},

// Additional methods can be added to support the lifecycle methods

_clear: function (subscription) {

subscription._counter = 0;

subscription._timer = null;

},

...

});

```

<p>After the synthetic event is defined, it is available for every Node and

NodeList to subscribe to.</p>

```

Y.one('#hellokitty').on('tripleclick', omgYayCantClickEnough);

```

<p>There is additional configuration to <a href="synths.html">add support for

`delegate()` or extra subscription arguments</a>, but often very little extra

code is needed.</p>

<h2>Troubleshooting/FAQ</h2>

<ul>

<li><a href="#function-reference">My callback is executing at the wrong time. What's going on?</a></li>

<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>

<li><a href="#which-events">What events can I subscribe to?</a></li>

<li><a href="#why-on-no-chain">Why isn't on() chainable?</a></li>

<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>

<li><a href="#after">EventTarget also provides an `after()` method. How does that work for DOM events?</a></li>

<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>

<li><a href="#nodelist-delegate">Where is `nodelist.delegate()`?</a></li>

<!--li><a href="#">What works and what doesn't on mobile browsers?</a></li-->

</ul>

<h4 id="function-reference">My callback is executing at the wrong time. What's going on?</h4>

<p>It's likely that you've included parenthesis in the subscription.</p>

```

// WRONG

node.on('click', someFunction());

node.on('click', myObject.someFunction());

// RIGHT

node.on('click', someFunction);

node.on('click', myObject.someFunction, myObject);

```

<p>

Including the parens makes the function execute immediately, and pass the

return value from the function to `node.on('click', [RETURN VALUE])`. To

pass a function around, just omit the parens.

</p>

<h4 id="wrong-this">I'm getting an error in my callback that "`(some object) has no method (someMethodOnMyObject)`". What am I missing?</h4>

<p>

You may be passing an object method to `on()`, but forgot to include

<a href="#extended-signature">the `this` object override parameter</a> in

the subscription.

</p>

<p>

Another option to make sure object methods are called with the correct

`this` object is to use

<a href="{{apiDocs}}/classes/YUI.html#method_bind">`Y.bind(obj.method,

obj)`</a> or

<a href="{{apiDocs}}/classes/YUI.html#method_rbind">`Y.rbind(obj.method,

obj)`</a>.

</p>

```

// WRONG

node.on('click', myObj.method);

// RIGHT

node.on('click', myObj.method, myObj);

// RIGHT (alternate)

node.on('click', Y.rbind(obj.method, obj));

```

<h4 id="which-events">What events can I subscribe to?</h4>

<p>

It depends what modules you've included. Check out the

<a href="#event-whitelist">whitelisted events table</a>.

</p>

<h4 id="why-on-no-chain">Why isn't on() chainable?</h4>

<p>

After much deliberation, the YUI team decided that returning a subscription

handle was preferable to chaining in order to better support clean event

detaching across the various scenarios that DOM and custom events are used.

</p>

<p>

In any sizable application, managing event subscriptions becomes

increasingly important, and detaching events must be done with precision.

Because YUI allows duplicate subscriptions, any host-based detach method

will necessarily be less than 100% reliable with respect to avoiding

removal of subscriptions made by other parts of the system.

</p>

<p>

Otherwise, it's common to subscribe to events with anonymous functions,

which makes it impossible to detach the specific subscription by signature

because you don't have a function reference to use to identify the specific

subscription to remove. Subscription categories can be used, but

<a href="#remove-by-category">are also less precise</a> than

dealing with a specific subscription object.

</p>

<h4 id="y-on-vs-node-on">Why would I use `Y.on()` or `Y.delegate()` instead of `node.on()` and `node.delegate()`?</h4>

<p>

It's <a href="#y-on">largely a stylistic preference</a>, but there are some

technical differences when passing a selector string as a the third

argument to `Y.on()` or `Y.delegate()` (ala

`Y.on('click', callback, '#some select.or-string')`.

</p>

<ol>

<li>

<p>

`Y.on()` uses the

<a href="{{apiDocs}}/classes/Selector.html">Selector engine</a>

directly rather than calling through `Y.all(...)`.

</p>

<p>

The benefit here is that the Node and NodeList constructors add the

slightest bit of overhead to the subscription process.

</p>

</li>

<li>

When passing a selector that matches multiple elements, the `this` in

the callback will be the individual Node, not a

<a href="#nodelist-this">NodeList wrapping all matched elements</a>.

</li>

<li>

<p>

If called before the elements matching the selector are attached to

the DOM, it will poll for a few seconds and automatically attach

the subscription when the first matching element is found.

</p>

<p>

Note, if using a selector that matches multiple elements, the poll

will attach the subscription the first time Selector finds a match.

This <em>may not include all the elements</em> because either the

DOM is not fully updated yet, or the code that adds the matching

elements may happen in batches.

</p>

<p>In practice, it is best to avoid reliance on this behavior.</p>

</li>

</ol>

<h4 id="after">`EventTarget` also provides an `after()` method. How does that work for DOM events?</h4>

<p>

`node.after(...)` is equivalent to `node.on(...)`. The DOM doesn't expose

an "after" moment to hook into.

</p>

<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>

<p>

In the callback, `e.currentTarget` will always refer to the individual Node.

However, if you call

</p>

```

Y.all('#some select.or-string').on('click', function (e) {

// how do I reference the NodeList?

});

```

<p>

you can't reference the NodeList captured by `Y.all()` without calling

`Y.all()` again, but that results in unnecessary overhead, and may match

different elements in the subsequent call.

</p>

<p>

In general, you should avoid `nodelist.on()` anyway,

<a href="#delegation">in favor of event delegation</a>.

</p>

<h4 id="nodelist-delegate">Where is `nodelist.delegate()`?</h4>

<p>

The point of delegation is to reduce the number of subscriptions being made.

`nodelist.delegate()` would be philosophically at odds with that. Either

call `node.delegate()` from an element higher up the DOM tree, or <em>if

you must</em> delegate the same event and callback from multiple

containers, use

</p>

```

nodelist.each(function (node) {

node.delegate('click', callback, '.not-recommended');

});

```

<h2>More Reading</h2>

<h3><a href="domready.html">Page Lifecycle events</a></h3>

<p>

Details about `domready`, `available`, and `contentready` events provided in

the event core. <a href="domready.html">Read more...</a>

</p>

<h3><a href="delegation.html">Event Delegation</a></h3>

<p>

What is event delegation and why you should be using it. A lot.

<a href="delegation.html">Read more...</a>

</p>

<h3><a href="simulate.html">Event Simulation</a></h3>

<p>

How to simulate user events like "click" or "keypress", what events can be

simulated, and some important caveats.

<a href="simulate.html">Read more...</a>

</p>

<h3><a href="synths.html">Create New DOM Events</a></h3>

<p>

How to create a tailor made DOM event for subscription or delegation from

any Node. This is a great way to encapsulate and label more comples user

behaviors.

<a href="synths.html">Read more...</a>

</p>

<h3><a href="touch.html">Working With Touch Events</a></h3>

<p>

Details on the supported touch events, the touch/mouse abstraction layer

events, and gesture based events like "flick".

<a href="touch.html">Read more...</a>

</p>

<h3><a href="focus.html">Delegating the `focus` and `blur` Events</a></h3>

<p>

Using the `event-focus` module to simulate support for bubbling `focus` and

`blur` events.

<a href="focus.html">Read more...</a>

</p>

<h3><a href="mouseenter.html">The `hover`, `mouseenter`, and `mouseleave` Events</a></h3>

<p>

Describes why `mouseenter` and `mouseleave` events are usually what you

want when you subscribe to `mouseover` and `mouseout`, and goes over using

the `hover` event (which uses the other two under the hood).

<a href="mouseenter.html">Read more...</a>

</p>

<h3><a href="key.html">Complex Keyboard Input Filtering</a></h3>

<p>

Using the `key` event to respond to specific users pressing specific keys or

or key combinations.

<a href="key.html">Read more...</a>

</p>

<h3><a href="outside.html">Responding to Events <em>outside</em> of a Node</a></h3>

<p>