index.mustache revision 5d3dc0444c51f18e44c016a89b16a8951529518c
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync text-transform: none;
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync<div class="intro component">
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <p>The YUI Event Utility provides APIs for working with the browser's DOM
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync event system. It simplifies tasks like subscribing to button `click`s or
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync canceling <form> `submit`s to, for example, allow sending data to the
92a27575521748a392dcd1b996fce55b87411a00vboxsync server via ajax.</p>
92a27575521748a392dcd1b996fce55b87411a00vboxsync <p>In addition, the "Synthetic event" system supplies <em>entirely new</em>
92a27575521748a392dcd1b996fce55b87411a00vboxsync DOM events to subscribe to as well as fixing events that behave differently
92a27575521748a392dcd1b996fce55b87411a00vboxsync across browsers. Implementers can create their own DOM events triggered by
92a27575521748a392dcd1b996fce55b87411a00vboxsync specific user actions or other environmental criteria.</p>
92a27575521748a392dcd1b996fce55b87411a00vboxsync <p>The API for working with DOM events is provided by the EventTarget class,
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync which also services the Custom event infrastructure that is used throughout
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync YUI. Read more about working with custom events <a
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync href="../event-custom/index.html">in the EventTarget user guide</a>.</p>
10cdf5733351fdcd857d439ca32189e812f18682vboxsync{{>getting-started}}
10cdf5733351fdcd857d439ca32189e812f18682vboxsync<h2>The Basics</h2>
10cdf5733351fdcd857d439ca32189e812f18682vboxsync<h4>Listening for events</h4>
10cdf5733351fdcd857d439ca32189e812f18682vboxsync// Step 1. Capture a button node
10cdf5733351fdcd857d439ca32189e812f18682vboxsyncvar button = Y.one("#readygo");
10cdf5733351fdcd857d439ca32189e812f18682vboxsync// Step 2. Subscribe to its click event with a callback function
10cdf5733351fdcd857d439ca32189e812f18682vboxsyncbutton.on("click", function (e) {
10cdf5733351fdcd857d439ca32189e812f18682vboxsync // Step 3. do stuff when the button is clicked
cd9e4940318086a06a68bf301960563dcb72b939vboxsync<p><code>on(<em>type</em>, <em>callback</em>)</code> is the main
cd9e4940318086a06a68bf301960563dcb72b939vboxsyncsubscription method, and is available on every <a href="../node/">`Node`</a>
cd9e4940318086a06a68bf301960563dcb72b939vboxsyncand <a href="../node/#nodelist">`NodeList`</a>.</p>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync<p>Replace "click" with <a href="#event-whitelist">any other event name</a> to subscribe to that event.</p>
10cdf5733351fdcd857d439ca32189e812f18682vboxsync<h4>The Callback and the Event Object</h4>
10cdf5733351fdcd857d439ca32189e812f18682vboxsyncbutton.on('click', function (e) {
10cdf5733351fdcd857d439ca32189e812f18682vboxsync // `this` is the button Node, NOT the DOM element
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync this.get('id'); // ==> 'readygo' (from <button id="readygo">...</button>)
10cdf5733351fdcd857d439ca32189e812f18682vboxsync // Event properties that point to the DOM are also Node instances
10cdf5733351fdcd857d439ca32189e812f18682vboxsync e.target.get('id'); // => 'readygo'
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync // Stop the event's default behavior
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync // Stop the event from bubbling up the DOM tree
cd9e4940318086a06a68bf301960563dcb72b939vboxsync<p>Subscribed callbacks are passed a <a href="#facade-properties">a normalized
10cdf5733351fdcd857d439ca32189e812f18682vboxsyncevent object</a> as their first argument.</p>
10cdf5733351fdcd857d439ca32189e812f18682vboxsync<p>The keyword "`this`" in the callback will refer to the Node or NodeList
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncthat you subscribed from.</p>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync<h4>`e.preventDefault()` and `e.stopPropagation()`</h4>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync<p>Many events have a default behavior, such as the `submit` event serializing
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncform data and making a new page request. Disable this behavior with
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncfunction setFilter(e) {
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync // Stop the link from loading the href page
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync // Now do my own thing instead
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync var url = this.get('href').replace(/page/, 'partial');
4a429a59b1a82ce092626ea5f7512466c18f2015vboxsync Y.one('#contentArea').load(url);
4a429a59b1a82ce092626ea5f7512466c18f2015vboxsync // `return false` is supported, but not preferred. use e.preventDefault()
4a429a59b1a82ce092626ea5f7512466c18f2015vboxsync return false;
4a429a59b1a82ce092626ea5f7512466c18f2015vboxsyncY.one('#table-filter-link').on('click', setFilter);
4a429a59b1a82ce092626ea5f7512466c18f2015vboxsync<p>Most events can be listened for on the specific element that originates them
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync<em>or from any of their parent elements</em>, all the way up to the
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync`document`. Prevent dispatching the event to subscriptions bound to elements
23ee8310386e73ba6760fa30831a7964713d34b6vboxsyncfurther up the DOM tree with `e.stopPropagation()`. In practice, this is
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncrarely useful.</p>
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync<p>Returning `false` from a callback will also stop the propagation of the
23ee8310386e73ba6760fa30831a7964713d34b6vboxsyncevent, which may cause unintended side effects.</p>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync<p>`e.stopPropagation()` won't prevent the execution of other subscribers
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsynclistening to the same element, only elements further up the DOM tree. If you
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncneed to stop all execution, use `e.stopImmediatePropagation()` or
86abc60770f825f8c2ed4257675b50a08743b687vboxsync`e.halt(true)`. The latter will also call `e.preventDefault()`.</p>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync<h4>Detaching subscriptions</h4>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync<p>`node.on()` and all
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync<a href="#more">other subscription methods</a> return a
23ee8310386e73ba6760fa30831a7964713d34b6vboxsyncsubscription object that can be used to unbind that subscription. Node also
23ee8310386e73ba6760fa30831a7964713d34b6vboxsyncsupports a `detach()` method and <a href="#detach-methods">other ways to cleaup
23ee8310386e73ba6760fa30831a7964713d34b6vboxsyncsubscriptions</a>.</p>
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync// on() returns a subscription handle...
23ee8310386e73ba6760fa30831a7964713d34b6vboxsyncvar sub = button.on("click", handleClick);
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync// ...that can be used to unbind the subscription
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync// Alternately, use the Node's detach() method
23ee8310386e73ba6760fa30831a7964713d34b6vboxsyncbutton.detach("click", handleClick);
23ee8310386e73ba6760fa30831a7964713d34b6vboxsync<p>Just this should take care of most of the simple event bindings you'll need.
23ee8310386e73ba6760fa30831a7964713d34b6vboxsyncThere's <a href="#more">a lot more you can do</a>, though, so read on!</p>
6967517de4be849f55b0141d6089add0eff2aa7bvboxsync<h2 id="modules">What to `use()`</h2>
7b213bb002950f9fcf809f605cc584fa543481advboxsync Before we get into <a href="#more">more API goodies</a>, let's talk about
7b213bb002950f9fcf809f605cc584fa543481advboxsync the Event Utility's module breakdown.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync For starters, in most cases <em>you probably won't `use('event')`</em>.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync The core DOM event system ("event-base") is required by the "node-base"
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync module, which itself if required by just about everything in YUI. So you
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync probably already have the DOM event API and didn't know it!
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync<p>Here is the full breakdown of modules in the DOM event system:</p>
cd9e4940318086a06a68bf301960563dcb72b939vboxsync <th>`use("______", ...)`</th>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <th>What's in it?</th>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <td><a href="{{apiDocs}}/module_event-base.html">`event-base`</a></td>
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync The core DOM event subscription system as well as the DOM
cd9e4940318086a06a68bf301960563dcb72b939vboxsync lifecycle events <a href="domready.html">`domready`,
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync `contentready`, and `available`</a>. Notably, it does NOT
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <li>event delegation</li>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <li>event simulation</li>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <li>synthetic events</li>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <p>If you've `use()`d anything, you probably have this already.</p>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <td><a href="{{apiDocs}}/module_event.html">`event`</a></td>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync A rollup of all modules below except
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <li>"event-simulate"</li>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <li>"node-event-simulate"</li>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <li>"node-event-delegate" (which is in the "node" rollup)</li>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <td><a href="{{apiDocs}}/module_event-delegate.html">`event-delegate`</a> &
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <a style="white-space: nowrap;" href="{{apiDocs}}/module_node-event-delegate.html">`node-event-delegate`</a></td>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync Adds the `Y.delegate(...)` and `node.delegate(...)` methods,
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync respectively, for <a href="#delegation">event delegation</a>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync convenience.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <td><a href="{{apiDocs}}/module_event-simulate.html">`event-simulate`</a> &
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <a style="white-space: nowrap;" href="{{apiDocs}}/module_node-event-simulate.html">`node-event-simulate`</a></td>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync Adds `Y.Event.simulate(...)` and `node.simulate(...)` for
08a80484275b5172ce23729ecccc934c6a92d201vboxsync <a href="#simulate">triggering native DOM events</a> for
08a80484275b5172ce23729ecccc934c6a92d201vboxsync unit testing.
86abc60770f825f8c2ed4257675b50a08743b687vboxsync <strong>Note: <a href="simulate.html#faking">Faking DOM events
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync should not be used in user facing code</a></strong>.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <td><a href="{{apiDocs}}/module_event-synthetic.html">`event-synthetic`</a></td>
fc148a6b23d25a87561beaffe0ba06c3ba93bf5avboxsync <p>Supplies the infrastructure for creating new DOM events, "fixing"
fc148a6b23d25a87561beaffe0ba06c3ba93bf5avboxsync existing events with undesirable or inconsistent behavior, and
fc148a6b23d25a87561beaffe0ba06c3ba93bf5avboxsync <a href="synths.html">all sorts of other things</a>.</p>
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync <p>All of the modules below are synthetics.</p>
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync <td><a href="{{apiDocs}}/module_event-flick.html">`event-flick`</a></td>
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync Adds a <a href="touch.html#flick">"flick" event</a> for touch or
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync mouse interaction.
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync <td><a href="{{apiDocs}}/module_event-focus.html">`event-focus`</a></td>
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync <a href="focus.html">Fixes `focus` and `blur` events</a> to bubble
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync (for delegation).
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync <td><a href="{{apiDocs}}/module_event-gestures.html">`event-gestures`</a></td>
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync <p>A rollup of the following modules:</p>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <li>"event-touch"</li>
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync <li>"event-move"</li>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <li>"event-flick"</li>
bc8beda7587b16cafe7de7bea19149de1bd4b498vboxsync <p>In the future, may contain more gesture abstraction modules.</p>
cc8517c11be66037a9873fa03f280e7742efed6dvboxsync <td><a href="{{apiDocs}}/module_event-hover.html">`event-hover`</a></td>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync Adds a <a href="mouseenter.html#hover">"hover" event</a> which
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync binds to two callbacks, one for the start, and one for the end of a
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync mouse hover.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <td><a href="{{apiDocs}}/module_event-key.html">`event-key`</a></td>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync Adds a <a href="key.html">"key" event</a> which listens for
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync specific, implementer defined, keys being pressed by the user.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <td><a href="{{apiDocs}}/module_event-mouseenter.html">`event-mouseenter`</a></td>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync Adds <a href="mouseenter.html">"mouseenter" and "mouseleave"
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync events</a>. You probably want to use these instead of "mouseover"
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync and "mouseout".
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <td><a href="{{apiDocs}}/module_event-mousewheel.html">`event-mousewheel`</a></td>
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync <p>Adds a "mousewheel" event for monitoring users scrolling the
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync window with the mousewheel. Event facades passed to the callback
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync will have an `e.wheelDelta` property corresponding to the amount of
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync scrolling.</p>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <p>Currently, this event can only be subscribed with
08a56d5836eceeb24642b61eaa52a4edb0a7b482vboxsync `Y.on("mousewheel", callback)`;</p>
3b3bc8a9383a065307e540b83fc3a3d6c548a082vboxsync <td><a href="{{apiDocs}}/module_event-move.html">`event-move`</a></td>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync Adds <a href="touch.html#move">"gesturemovestart", "gesturemove",
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync and "gesturemoveend" events</a> that serve as abstractions over
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync mouse and touch events, forking internally based on the client
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync <td><a href="{{apiDocs}}/module_event-outside.html">`event-outside`</a></td>
16aeb8f83239d4a4a10ecac1fb46fe24a8bdbb66vboxsync Adds a <a href="outside.html">"clickoutside" and several other
16aeb8f83239d4a4a10ecac1fb46fe24a8bdbb66vboxsync outside events</a> to trigger behavior based on actions taken
16aeb8f83239d4a4a10ecac1fb46fe24a8bdbb66vboxsync outside a specific element.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <td><a href="{{apiDocs}}/module_event-resize.html">`event-resize`</a></td>
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsync <p>Adds a "windowresize" event that only fires after a user has
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsync stopped dragging a window's resize handle. This normalizes the
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsync `window.onresize` event across browsers.</p>
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsync <p>This event can only be subscribed with
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsync `Y.on("windowresize", callback)`;</p>
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsync <td><a href="{{apiDocs}}/module_event-touch.html">`event-touch`</a></td>
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync Adds support for <a href="touch.html">subscribing to native touch
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsync and gesture events</a>.
f8244da4b4e02d8d4ce0669eeb4093e31c301888vboxsync <td><a href="{{apiDocs}}/module_event-valuechange.html">`event-valuechange`</a></td>
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync Adds a <a href="valuechange.html">"valueChange" event</a> that fires when input element text
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync changes (this is harder than you think).
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsync<h2 id="delegation">Event Delegation</h2>
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsync<p>If you don't already know what event delegation is, you should <a
1cc3bd5463294790ba54c78fde5313264185e50cvboxsynchref="delegation.html">read this quick overview</a>. Short form: <em>you need
1cc3bd5463294790ba54c78fde5313264185e50cvboxsyncto be using this</em>.</p>
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsync// single element subscription
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsyncnode.on("click", handleClick);
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync// delegated subscription for all button clicks from inside the node
1cc3bd5463294790ba54c78fde5313264185e50cvboxsyncnode.delegate("click", handleClick, "button, input[type=button]");
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsync<p>Creating a delegated subscription looks very much like creating any other
1cc3bd5463294790ba54c78fde5313264185e50cvboxsyncevent subscription with two differences. First, it's a different method name,
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsync`delegate`. Second, there is another argument: a CSS selector that is used to
1cc3bd5463294790ba54c78fde5313264185e50cvboxsynctest the event's originating element to decide if the callback should be
1cc3bd5463294790ba54c78fde5313264185e50cvboxsyncexecuted. If the event started at or inside an element matching the selector,
1cc3bd5463294790ba54c78fde5313264185e50cvboxsyncthe callback will execute.</p>
bee07f28c146fb5313ea13d84dcd508d8f604a10vboxsync<p>Unlike `node.on()` subscriptions, the `this` object in `node.delegate()`
441e51789084e8795573747fec9f5108e8b54e98vboxsynccallbacks will refer to the element that matched the css filter, not to `node`.
1cc3bd5463294790ba54c78fde5313264185e50cvboxsyncWe did this because likely your logic revolves around the nodes described by
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsyncthe filter, not around the element that contains them.</p>
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsyncfunction handleClick (e) {
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsync // `this` is the button with class .remove, not the #items element
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync // remove the containing LI
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync this.ancestor('li').remove();
1cc3bd5463294790ba54c78fde5313264185e50cvboxsyncY.one('#items').delegate('click', handleClick, 'button.remove');
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsync<p>For more complex target filtering, a function can be passed instead of a css
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsyncselector. See the
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsync<a href="{{apiDocs}}/module_event-delegate.html#method_delegate">API docs</a>
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsyncfor more details.</p>
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsync<p>As noted <a href="#modules">above</a>, the `event-delegate` module is
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsyncincluded in the `event` rollup, but `node-event-delegate` isn't. We recommend
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsyncusing delegation from the Node API, so you should `use()` either
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsync`node-event-delegate` or the `node` rollup.</p>
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync<h2 id="more">More Event API Goodness</h2>
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync Here is a sampling of some of the other ways to manage event subscriptions
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync<h4 id="y-on">Subscribe from `Y`</h4>
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync// Y.on() takes a third argument which is the Node, DOM element,
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync// or CSS selector of the element(s) to bind
1cc3bd5463294790ba54c78fde5313264185e50cvboxsyncY.on("click", handleClick, "#readygo");
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync// Y.delegate() similarly takes the containing element or selector
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync// as the third argument
1cc3bd5463294790ba54c78fde5313264185e50cvboxsyncY.delegate("click", handleClick, "#container", "button, input[type=button]");
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync An alternate syntax for DOM subscriptions is using `Y.on()` or
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync `Y.delegate()`. When identifying the target by a CSS selector, these
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync methods can be used regardless if the element is currently available for
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync scripting. If it's not yet on the page, a poll will regularly look for it
1cc3bd5463294790ba54c78fde5313264185e50cvboxsync (for a few seconds) and the subscription will be automatically attached
efda5c4c4db213abd0692df0ea34a26f6230d59avboxsync when the element is found. Relying on this behavior can introduce race
2705a216ac12110a0813d671e230797c886b4788vboxsync conditions, though, so use it wisely.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync Use of `Y.on()` instead of `node.on()` is largely a stylistic preference,
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync though <a href="#y-on-vs-node-on">there are some technical differences</a>.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync<h4 id="once">One time subscriptions</h4>
42d36464aee6c81b4f206b6c02035587501ff67cvboxsynctabLabel.once('mouseover', loadTabContent);
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync<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>
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync<p>The signature for `once()` is the same as `on()`.</p>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync<h4>Grouping subscriptions</h4>
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync<p>Pass an object to subscribe to multiple events, each with their own
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsynccallback</p>
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsyncfunction validate(e) { ... }
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncfunction clearPlaceholder(e) { ... }
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncvar groupSub = inputNode.on({
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync blur : validate,
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync keypress: validate,
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync focus : clearPlaceholder
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync// Detach the blur, keypress, and focus subscriptions in one call
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync<p>Pass an array to subscribe to multiple events with the same callback</p>
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsyncfunction activate(e) { ... }
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsyncgroupSub = inputNode.on(['focus', 'mouseover'], activate);
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync// Detach the focus and mouseover subscriptions
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync<p>Prefix the event name with a category to allow detaching multiple
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsyncsubscriptions by that category.</p>
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsyncinputNode.on('my-category|focus', activate);
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncinputNode.on('my-category|mouseover', activate);
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync// You can detach specific subscriptions by 'my-category|focus' or all with |*
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncinputNode.detach('my-category|*');
cd9e4940318086a06a68bf301960563dcb72b939vboxsync<p>The `once()` and `delegate()` methods also support these alternate
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncsignatures.</p>
5857f4e58ce2ef50d7f0c450fe4897026f9a9c3dvboxsync<h4 id="extended-signature">Binding `this` and additional callback arguments</h4>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync By default, the "`this`" object in subscription callbacks will be the Node
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync or NodeList that subscribed to them. Override this default by passing your
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync own `this` object as the third argument to `on()` or the fourth to
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync `delegate()`. Note that the argument index is shifted when using `Y.on()`
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync and `Y.delegate()` or <a href="synths.html">synthetic events with custom
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync signatures</a>.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync// equivalent to node.on('click', function (e) { overlay.hide(e); });
2705a216ac12110a0813d671e230797c886b4788vboxsync// `this` override comes after the filter; also shifted for the 'key' event's
2705a216ac12110a0813d671e230797c886b4788vboxsync// custome signature.
2705a216ac12110a0813d671e230797c886b4788vboxsynccontainer.delegate('key', validator.isValid, 'enter,tab', 'input', validator);
2705a216ac12110a0813d671e230797c886b4788vboxsync// Corresponding alternatives from Y
c0da96af18c7b40ac5cfd7e7ea398a398540f224vboxsyncY.delegate('key', validator.isValid, '#myForm', 'enter,tab', 'input', validator);
c0da96af18c7b40ac5cfd7e7ea398a398540f224vboxsync<p>Additional arguments passed to the subscription methods will be sent along
c0da96af18c7b40ac5cfd7e7ea398a398540f224vboxsyncto the callback after the event facade. If you want to bind extra arguments,
c0da96af18c7b40ac5cfd7e7ea398a398540f224vboxsyncbut don't want to override the "`this`" object, pass `null` for the `this`
c0da96af18c7b40ac5cfd7e7ea398a398540f224vboxsyncargument.</p>
2705a216ac12110a0813d671e230797c886b4788vboxsync someMethod: function (param) {
2705a216ac12110a0813d671e230797c886b4788vboxsync Y.log(param); // => "I'm Extra!"
95d42763b8808d795c23148d7dbc00a3b7b40d6fvboxsync handleClick: function (e, extraParam) {
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncvar instance = new Y.MyClass();
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync// The extra arg is passed as the second param to the callback after `e`
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncY.one('#readygo').on('click', instance.handleClick, instance, "I'm Extra!");
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync<h4 id="detach-methods">More ways to clean up subscriptions</h4>
5c571d69a0355bedb9a401ce4de992a2b0ef3515vboxsync<p>There are a lot of options for detaching events in YUI. See the table below for details.</p>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <th>Method</th>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <th>What it does</th>
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync var subscription = node.on('click', callback);
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync Removes a specific subscription or, if created with one of the
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync group subscription methods, a group of subscriptions.
17aee8484f9e8699c2515d450552c622aea0889evboxsync Generally, this is the best method to use.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <tr id="remove-by-category">
17aee8484f9e8699c2515d450552c622aea0889evboxsync node.on('foo-category|click', callback);
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync node.detach('foo-category|click');
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync node.detach('foo-category|*');
0c657f93ac727a3a1644497331d86fbcbc3722aavboxsync Removes a subscription or group of subscriptions that included
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync the specified category in the subscription event type.
42dc09ee69e746b8641cfa190931a15ecfd7295cvboxsync This is typically only safe in implementation code, not
42dc09ee69e746b8641cfa190931a15ecfd7295cvboxsync module code, because multiple subscriptions using the same type
ee6495ebe54829fea21ffbb6f1275315e72d4506vboxsync and category will be detached by the call to `detach`.
e0b91e4f93fb43371374df4aeb636dffea336056vboxsync node.detach('click', callback);
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync If you have a reference to the subscribed callback function,
17aee8484f9e8699c2515d450552c622aea0889evboxsync (but not a subscription handle) use the two argument signature.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync With one argument, `detach` will remove all subscriptions for
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync the specified event. With no arguments, it removes all
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync subscriptions for all events.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync `detach` does not remove subscriptions from descendant nodes.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync Works the same as `node.detach()`.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync node.purge(true, 'click');
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync With no arguments, `purge` works the same as `node.detach()`.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync Passing `true` as a first argument will remove all
17aee8484f9e8699c2515d450552c622aea0889evboxsync subscriptions for all events from the node <em>and its
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync descendant subtree</em>. Passing an event type as a second
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync argument will only deep purge subscriptions to that event.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync Removes subscriptions for all events <em>only from the
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync descendants of a node</em> after removing them from the DOM.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync With no arguments, works like `node.detach()`.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync With `true` as a first argument, it works like
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync The `destroy` method does more than detaching event
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync subscribers. Read the
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync <a href="{{apiDocs}}/classes/Node.html#method_destroy">API
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync docs</a> for details.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync Y.Event.detach('click', callback, '#foo');
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync Same as `Y.one('#foo').detach( [other args] )`.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync Y.Event.purgeElement('#foo', true, 'click');
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync Same as `Y.one('#foo').purge( [other args] )`.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync<h2 id="simulate">Simulate browser events</h2>
98bfcb808aa93fe8b532eb38da1f15a795a85f6dvboxsync For creating automated functional tests, being able to simulate user
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync interaction can be crucial. That's where the `node-event-simulate` module
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncYUI().use('test', 'node-event-simulate', 'fancy', function (Y) {
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncvar test = new Y.Test.Case({
var widget = new Y.MyFancyWidget().render('#here'),
uiBox = widget.get('boundingBox'),
closeButton = uiBox.one('.close-button');
closeButton.simulate('click');
`node.simulate( type, eventProperties )` creates a native DOM event that
For example, `node.simulate('submit')` will not send data to the server for
<p>Read <a href="simulate.html">more about event simulation here</a>.</p>
Y.one('#dialog').on('clickoutside', function (e) {
this.transition('fadeOut');
Y.one('#editable-table').delegate('key', saveAndAdvance, 'tab', 'input');
<a href="http://yuilibrary.com/gallery/">in the Gallery</a>. Most events
<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
subscription._handle = node.on('click', function (e) {
notifier.fire(e);
Y.later(300, this, this._clear, [subscription]);
Y.one('#hellokitty').on('tripleclick', omgYayCantClickEnough);
<p>There is additional configuration to <a href="synths.html">add support for
<h2>Troubleshooting/FAQ</h2>
<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="#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>
node.on('click', someFunction());
node.on('click', someFunction);
return value from the function to `node.on('click', [RETURN VALUE])`. To
<h4 id="wrong-this">I'm getting an error in my callback that "`(some object) has no method (someMethodOnMyObject)`". What am I missing?</h4>
<h4 id="y-on-vs-node-on">Why would I use `Y.on()` or `Y.delegate()` instead of `node.on()` and `node.delegate()`?</h4>
`Y.on()` uses the
<a href="{{apiDocs}}/classes/Selector.html">Selector engine</a>
directly rather than calling through `Y.all(...)`.
<h4 id="after">`EventTarget` also provides an `after()` method. How does that work for DOM events?</h4>
<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>
In the callback, `e.currentTarget` will always refer to the individual Node.
you can't reference the NodeList captured by `Y.all()` without calling
`Y.all()` again, but that results in unnecessary overhead, and may match
In general, you should avoid `nodelist.on()` anyway,
<h4 id="nodelist-delegate">Where is `nodelist.delegate()`?</h4>
`nodelist.delegate()` would be philosophically at odds with that. Either
call `node.delegate()` from an element higher up the DOM tree, or <em>if
nodelist.each(function (node) {
node.delegate('click', callback, '.not-recommended');
node = Y.one('#events');
node.all('td:nth-of-type(1)').each(function (node, i) {
Event: node.get('text'),
"Added By": node.next().get('text')
node.empty().addClass('yui3-skin-sam');
new Y.DataTable.Base({
}).plug(Y.Plugin.DataTableSort).render(node);
names to the `Y.Node.DOM_EVENTS` object.</p>
<dt>`e.preventDefault()`</dt>
Prevents the default action associated with the event. E.g. page
<dt>`e.stopPropagation()`</dt>
<dt>`e.stopImmediatePropagation()`</dt>
<dt>`e.halt( [immediate=false] )`</dt>
<dt>`e.type`</dt>
The name of the event. E.g. "click", "keyup", or "load".
<dt>`e.target`</dt>
href="delegation.html">the description of event delegation</a> for
<dt>`e.currentTarget`</dt>
<dt>`e.relatedTarget`</dt>
<dt>`e.keyCode`</dt>
<dt>`e.charCode`</dt>
<dt>`e.shiftKey`</dt>
<dt>`e.ctrlKey`</dt>
<dt>`e.altKey`</dt>
`true` if the alt/option key was depressed during a key event.
<dt>`e.metaKey`</dt>
<dt>`e.button`</dt>
<dt>`e.which`</dt>
Alias for e.button.
<dt>`e.pageX`</dt>
<dt>`e.pageY`</dt>
<dt>`e.clientX`</dt>
<dt>`e.clientY`</dt>
<dt>[`e.wheelDelta`]</dt>
<h4>Touch/Mobile related properties</h4>
<dt>[`e.touches`]</dt>
<dt>[`e.targetTouches`]</dt>
<dt>[`e.changedTouches`]</dt>
<dt>[`e.scale`]</dt>
<dt>[`e.rotation`]</dt>
<dt>[`e.identifier`]</dt>
<p>Synthetic events may add or modify event facade properties. These should be included in the documentation for the specific synthetic event.</p>
href="https://developer.mozilla.org/en/DOM/event#Properties">MDC