← Back to branch summary

~ubuntu-branches/ubuntu/raring/maas/raring-updates

« back to all changes in this revision

Viewing changes to src/maasserver/static/jslibs/yui/3.4.1/docs/event/index.html

  • Committer: Package Import Robot
  • Author(s): Andres Rodriguez
  • Date: 2012-07-03 17:42:37 UTC
  • mfrom: (1.1.13)
  • Revision ID: package-import@ubuntu.com-20120703174237-p8l0keuuznfg721k
Tags: 0.1+bzr709+dfsg-0ubuntu1
* New Upstream release
* debian/control:
  - Depends on python-celery, python-tempita, libjs-yui3-{full,min},
    libjs-raphael
* debian/maas.install:
  - Install apiclient, celeryconfig.py, maas-import-pxe-files, preseeds_v2.
  - Update to install various files from chroot, rather tha manually copy
    them from the source.
* debian/maas.links: symlink celeryconfig.py
* debian/maas.maas-celery.upstart: Add job.
* debian/rules:
  - Install celery upstart job.
  - Do not install jslibs as packages are now used.
  - Drop copying of maas_local_settings_sample.py as source now ships
    a maas_local_settings.py
* debian/patches:
  - 04-maas-http-fix.patch: Drop. Merged upstream.
  - 01-fix-database-settings.patch: Refreshed.
  - 99_enums_js.patch: Added until creation of enum.js / build process
    is fixed.
* debian/maas.postinst: Update bzr version to correctly handle upgrades.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/maasserver/static/jslibs/yui/3.4.1/docs/event/index.html
1
 
<!DOCTYPE html>
2
 
<html lang="en">
3
 
<head>
4
 
    <meta charset="utf-8">
5
 
    <title>Event</title>
6
 
    <link rel="stylesheet" href="http://yui.yahooapis.com/3.4.0pr3/build/cssgrids/grids-min.css">
7
 
    <link rel="stylesheet" href="../assets/css/main.css">
8
 
    <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
9
 
    <script src="../../build/yui/yui-min.js"></script>
10
 
</head>
11
 
<body>
12
 
 
13
 
<div id="doc">
14
 
    <h1>Event</h1>
15
 
 
16
 
    
17
 
        <a href="#toc" class="jump">Jump to Table of Contents</a>
18
 
    
19
 
 
20
 
    <div class="yui3-g">
21
 
        <div id="main" class="yui3-u">
22
 
            <div class="content"><style>
23
 
    h4 code {
24
 
        text-transform: none;
25
 
    }
26
 
    .yui3-skin-sam td {
27
 
        background-color: #E6E9F5;
28
 
    }
29
 
    .yui3-skin-sam .yui3-datatable td {
30
 
        background-color: transparent;
31
 
    }
32
 
</style>
33
 
 
34
 
<div class="intro component">
35
 
    <p>The YUI Event Utility provides APIs for working with the browser's DOM
36
 
    event system.  It simplifies tasks like subscribing to button <code>click</code>s or
37
 
    canceling &lt;form&gt; <code>submit</code>s to, for example, allow sending data to the
38
 
    server via ajax.</p>
39
 
    
40
 
    <p>In addition, the "Synthetic event" system supplies <em>entirely new</em>
41
 
    DOM events to subscribe to as well as fixing events that behave differently
42
 
    across browsers.  Implementers can create their own DOM events triggered by
43
 
    specific user actions or other environmental criteria.</p>
44
 
 
45
 
    <p>The API for working with DOM events is provided by the EventTarget class,
46
 
    which also services the Custom event infrastructure that is used throughout
47
 
    YUI.  Read more about working with custom events <a
48
 
    href="../event-custom/index.html">in the EventTarget user guide</a>.</p>
49
 
</div>
50
 
 
51
 
<h2 id="getting-started">Getting Started</h2>
52
 
 
53
 
<p>
54
 
To include the source files for Event and its dependencies, first load
55
 
the YUI seed file if you haven't already loaded it.
56
 
</p>
57
 
 
58
 
<pre class="code prettyprint">&lt;script src=&quot;http:&#x2F;&#x2F;yui.yahooapis.com&#x2F;3.4.1&#x2F;build&#x2F;yui&#x2F;yui-min.js&quot;&gt;&lt;&#x2F;script&gt;</pre>
59
 
 
60
 
 
61
 
<p>
62
 
Next, create a new YUI instance for your application and populate it with the
63
 
modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
64
 
YUI will automatically load any dependencies required by the modules you
65
 
specify.
66
 
</p>
67
 
 
68
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a new YUI instance and populate it with the required modules.
69
 
YUI().use(&#x27;event&#x27;, function (Y) {
70
 
    &#x2F;&#x2F; Event is available and ready for use. Add implementation
71
 
    &#x2F;&#x2F; code here.
72
 
});</pre>
73
 
 
74
 
 
75
 
<p>
76
 
For more information on creating YUI instances and on the
77
 
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
78
 
documentation for the <a href="../yui/index.html">YUI Global object</a>.
79
 
</p>
80
 
 
81
 
 
82
 
<h2 id="the-basics">The Basics</h2>
83
 
 
84
 
<h4 id="listening-for-events">Listening for events</h4>
85
 
<pre class="code prettyprint">&#x2F;&#x2F; Step 1. Capture a button node
86
 
var button = Y.one(&quot;#readygo&quot;);
87
 
 
88
 
&#x2F;&#x2F; Step 2. Subscribe to its click event with a callback function
89
 
button.on(&quot;click&quot;, function (e) {
90
 
 
91
 
    &#x2F;&#x2F; Step 3. do stuff when the button is clicked
92
 
 
93
 
});</pre>
94
 
 
95
 
 
96
 
<p><code>on(<em>type</em>, <em>callback</em>)</code> is the main 
97
 
subscription method, and is available on every <a href="../node/"><code>Node</code></a>
98
 
and <a href="../node/#nodelist"><code>NodeList</code></a>.</p>
99
 
 
100
 
<p>Replace "click" with <a href="#event-whitelist">any other event name</a> to subscribe to that event.</p>
101
 
 
102
 
<h4 id="the-callback-and-the-event-object">The Callback and the Event Object</h4>
103
 
 
104
 
<pre class="code prettyprint">button.on(&#x27;click&#x27;, function (e) {
105
 
    &#x2F;&#x2F; &#x60;this&#x60; is the button Node, NOT the DOM element
106
 
    this.get(&#x27;id&#x27;); &#x2F;&#x2F; ==&gt; &#x27;readygo&#x27; (from &lt;button id=&quot;readygo&quot;&gt;...&lt;&#x2F;button&gt;)
107
 
 
108
 
    &#x2F;&#x2F; Event properties that point to the DOM are also Node instances
109
 
    e.target.get(&#x27;id&#x27;); &#x2F;&#x2F; =&gt; &#x27;readygo&#x27;
110
 
    
111
 
    &#x2F;&#x2F; Stop the event&#x27;s default behavior
112
 
    e.preventDefault();
113
 
 
114
 
    &#x2F;&#x2F; Stop the event from bubbling up the DOM tree
115
 
    e.stopPropagation();
116
 
});</pre>
117
 
 
118
 
 
119
 
<p>Subscribed callbacks are passed a <a href="#facade-properties">a normalized
120
 
event object</a> as their first argument.</p>
121
 
 
122
 
<p>The keyword "<code>this</code>" in the callback will refer to the Node or NodeList
123
 
that you subscribed from.</p>
124
 
 
125
 
<h4 id="epreventdefault-and-estoppropagation"><code>e.preventDefault()</code> and <code>e.stopPropagation()</code></h4>
126
 
 
127
 
<p>Many events have a default behavior, such as the <code>submit</code> event serializing
128
 
form data and making a new page request.  Disable this behavior with
129
 
<code>e.preventDefault()</code>.</p>
130
 
 
131
 
<pre class="code prettyprint">function setFilter(e) {
132
 
    &#x2F;&#x2F; Stop the link from loading the href page
133
 
    e.preventDefault();
134
 
 
135
 
    &#x2F;&#x2F; Now do my own thing instead
136
 
    var url = this.get(&#x27;href&#x27;).replace(&#x2F;page&#x2F;, &#x27;partial&#x27;);
137
 
 
138
 
    Y.one(&#x27;#contentArea&#x27;).load(url);
139
 
 
140
 
    &#x2F;&#x2F; &#x60;return false&#x60; is supported, but not preferred. use e.preventDefault()
141
 
    return false;
142
 
}
143
 
 
144
 
Y.one(&#x27;#table-filter-link&#x27;).on(&#x27;click&#x27;, setFilter);</pre>
145
 
 
146
 
 
147
 
<p>Most events can be listened for on the specific element that originates them
148
 
<em>or from any of their parent elements</em>, all the way up to the
149
 
<code>document</code>.  Prevent dispatching the event to subscriptions bound to elements
150
 
further up the DOM tree with <code>e.stopPropagation()</code>.  In practice, this is
151
 
rarely useful.</p>
152
 
 
153
 
<p>Returning <code>false</code> from a callback will also stop the propagation of the
154
 
event, which may cause unintended side effects.</p>
155
 
 
156
 
<p><code>e.stopPropagation()</code> won't prevent the execution of other subscribers
157
 
listening to the same element, only elements further up the DOM tree.  If you
158
 
need to stop all execution, use <code>e.stopImmediatePropagation()</code> or
159
 
<code>e.halt(true)</code>. The latter will also call <code>e.preventDefault()</code>.</p>
160
 
 
161
 
<h4 id="detaching-subscriptions">Detaching subscriptions</h4>
162
 
 
163
 
<p><code>node.on()</code> and all
164
 
<a href="#more">other subscription methods</a> return a
165
 
subscription object that can be used to unbind that subscription.  Node also
166
 
supports a <code>detach()</code> method and <a href="#detach-methods">other ways to cleaup
167
 
subscriptions</a>.</p>
168
 
 
169
 
<pre class="code prettyprint">&#x2F;&#x2F; on() returns a subscription handle...
170
 
var sub = button.on(&quot;click&quot;, handleClick);
171
 
 
172
 
&#x2F;&#x2F; ...that can be used to unbind the subscription
173
 
sub.detach();
174
 
 
175
 
&#x2F;&#x2F; Alternately, use the Node&#x27;s detach() method
176
 
button.detach(&quot;click&quot;, handleClick);</pre>
177
 
 
178
 
 
179
 
<p>Just this should take care of most of the simple event bindings you'll need.
180
 
There's <a href="#more">a lot more you can do</a>, though, so read on!</p>
181
 
 
182
 
<h2 id="modules">What to <code>use()</code></h2>
183
 
 
184
 
<p>
185
 
    Before we get into <a href="#more">more API goodies</a>, let's talk about
186
 
    the Event Utility's module breakdown.
187
 
</p>
188
 
 
189
 
<p>
190
 
    For starters, in most cases <em>you probably won't <code>use(&#x27;event&#x27;)</code></em>.
191
 
    The core DOM event system ("event-base") is required by the "node-base"
192
 
    module, which itself if required by just about everything in YUI.  So you
193
 
    probably already have the DOM event API and didn't know it!
194
 
</p>
195
 
 
196
 
<p>Here is the full breakdown of modules in the DOM event system:</p>
197
 
 
198
 
<table>
199
 
<thead>
200
 
    <tr>
201
 
        <th><code>use(&quot;______&quot;, ...)</code></th>
202
 
        <th>What's in it?</th>
203
 
    </tr>
204
 
</thead>
205
 
<tbody>
206
 
    <tr>
207
 
        <td><a href="http://yuilibrary.com/yui/docs/api/module_event-base.html"><code>event-base</code></a></td>
208
 
        <td>
209
 
            <p>
210
 
                The core DOM event subscription system as well as the DOM
211
 
                lifecycle events <a href="domready.html"><code>domready</code>,
212
 
                <code>contentready</code>, and <code>available</code></a>.  Notably, it does NOT
213
 
                include
214
 
            </p>
215
 
            <ul>
216
 
                <li>event delegation</li>
217
 
                <li>event simulation</li>
218
 
                <li>synthetic events</li>
219
 
            </ul>
220
 
 
221
 
            <p>If you've <code>use()</code>d anything, you probably have this already.</p>
222
 
        </td>
223
 
    </tr>
224
 
    <tr>
225
 
        <td><a href="http://yuilibrary.com/yui/docs/api/module_event.html"><code>event</code></a></td>
226
 
        <td>
227
 
            A rollup of all modules below except
228
 
            <ul>
229
 
                <li>"event-simulate"</li>
230
 
                <li>"node-event-simulate"</li>
231
 
                <li>"node-event-delegate" (which is in the "node" rollup)</li>
232
 
            </ul>
233
 
        </td>
234
 
    </tr>
235
 
    <tr>
236
 
        <td><a href="http://yuilibrary.com/yui/docs/api/module_event-delegate.html"><code>event-delegate</code></a> &amp;
237
 
            <br>
238
 
            <a style="white-space: nowrap;" href="http://yuilibrary.com/yui/docs/api/module_node-event-delegate.html"><code>node-event-delegate</code></a></td>
239
 
        <td>
240
 
            Adds the <code>Y.delegate(...)</code> and <code>node.delegate(...)</code> methods,
241
 
            respectively, for <a href="#delegation">event delegation</a>
242
 
            convenience.
243
 
        </td>
244
 
    </tr>
245
 
    <tr>
246
 
        <td><a href="http://yuilibrary.com/yui/docs/api/module_event-simulate.html"><code>event-simulate</code></a> &amp;
247
 
            <br>
248
 
            <a style="white-space: nowrap;" href="http://yuilibrary.com/yui/docs/api/module_node-event-simulate.html"><code>node-event-simulate</code></a></td>
249
 
        </td>
250
 
        <td>
251
 
            <p>
252
 
                Adds <code>Y.Event.simulate(...)</code> and <code>node.simulate(...)</code> for
253
 
                <a href="#simulate">triggering native DOM events</a> for
254
 
                unit testing.
255
 
            </p>
256
 
            <p>
257
 
                <strong>Note: <a href="simulate.html#faking">Faking DOM events
258
 
                should not be used in user facing code</a></strong>.
259
 
            </p>
260
 
        </td>
261
 
    </tr>
262
 
    <tr>
263
 
        <td><a href="http://yuilibrary.com/yui/docs/api/module_event-synthetic.html"><code>event-synthetic</code></a></td>
264
 
        <td>
265
 
            <p>Supplies the infrastructure for creating new DOM events, "fixing"
266
 
            existing events with undesirable or inconsistent behavior, and
267
 
            <a href="synths.html">all sorts of other things</a>.</p>
268
 
            
269
 
            <p>All of the modules below are synthetics.</p>
270
 
        </td>
271
 
    </tr>
272
 
    <tr>
273
 
        <td><a href="http://yuilibrary.com/yui/docs/api/module_event-flick.html"><code>event-flick</code></a></td>
274
 
        <td>
275
 
            Adds a <a href="touch.html#flick">"flick" event</a> for touch or
276
 
            mouse interaction.
277
 
        </td>
278
 
    </tr>
279
 
    <tr>
280
 
        <td><a href="http://yuilibrary.com/yui/docs/api/module_event-focus.html"><code>event-focus</code></a></td>
281
 
        <td>
282
 
            <a href="focus.html">Fixes <code>focus</code> and <code>blur</code> events</a> to bubble
283
 
            (for delegation).
284
 
        </td>
285
 
    </tr>
286
 
        <td><a href="http://yuilibrary.com/yui/docs/api/module_event-gestures.html"><code>event-gestures</code></a></td>
287
 
        <td>
288
 
            <p>A rollup of the following modules:</p>
289
 
 
290
 
            <ul>
291
 
                <li>"event-touch"</li>
292
 
                <li>"event-move"</li>
293
 
                <li>"event-flick"</li>
294
 
            </ul>
295
 
 
296
 
            <p>In the future, may contain more gesture abstraction modules.</p>
297
 
        </td>
298
 
    <tr>
299
 
        <td><a href="http://yuilibrary.com/yui/docs/api/module_event-hover.html"><code>event-hover</code></a></td>
300
 
        <td>
301
 
            Adds a <a href="mouseenter.html#hover">"hover" event</a> which
302
 
            binds to two callbacks, one for the start, and one for the end of a
303
 
            mouse hover.
304
 
        </td>
305
 
    </tr>
306
 
    <tr>
307
 
        <td><a href="http://yuilibrary.com/yui/docs/api/module_event-key.html"><code>event-key</code></a></td>
308
 
        <td>
309
 
            Adds a <a href="key.html">"key" event</a> which listens for
310
 
            specific, implementer defined, keys being pressed by the user.
311
 
        </td>
312
 
    </tr>
313
 
    <tr>
314
 
        <td><a href="http://yuilibrary.com/yui/docs/api/module_event-mouseenter.html"><code>event-mouseenter</code></a></td>
315
 
        <td>
316
 
            Adds <a href="mouseenter.html">"mouseenter" and "mouseleave"
317
 
            events</a>.  You probably want to use these instead of "mouseover"
318
 
            and "mouseout".
319
 
        </td>
320
 
    </tr>
321
 
    <tr>
322
 
        <td><a href="http://yuilibrary.com/yui/docs/api/module_event-mousewheel.html"><code>event-mousewheel</code></a></td>
323
 
        <td>
324
 
            <p>Adds a "mousewheel" event for monitoring users scrolling the
325
 
            window with the mousewheel.  Event facades passed to the callback
326
 
            will have an <code>e.wheelDelta</code> property corresponding to the amount of
327
 
            scrolling.</p>
328
 
 
329
 
            <p>Currently, this event can only be subscribed with
330
 
            <code>Y.on(&quot;mousewheel&quot;, callback)</code>;</p>
331
 
        </td>
332
 
    </tr>
333
 
    <tr>
334
 
        <td><a href="http://yuilibrary.com/yui/docs/api/module_event-move.html"><code>event-move</code></a></td>
335
 
        <td>
336
 
            Adds <a href="touch.html#move">"gesturemovestart", "gesturemove",
337
 
            and "gesturemoveend" events</a> that serve as abstractions over
338
 
            mouse and touch events, forking internally based on the client
339
 
            device.
340
 
        </td>
341
 
    </tr>
342
 
    <tr>
343
 
        <td><a href="http://yuilibrary.com/yui/docs/api/module_event-outside.html"><code>event-outside</code></a></td>
344
 
        <td>
345
 
            Adds a <a href="outside.html">"clickoutside" and several other
346
 
            outside events</a> to trigger behavior based on actions taken
347
 
            outside a specific element.
348
 
        </td>
349
 
    </tr>
350
 
    <tr>
351
 
        <td><a href="http://yuilibrary.com/yui/docs/api/module_event-resize.html"><code>event-resize</code></a></td>
352
 
        <td>
353
 
            <p>Adds a "windowresize" event that only fires after a user has
354
 
            stopped dragging a window's resize handle.  This normalizes the
355
 
            <code>window.onresize</code> event across browsers.</p>
356
 
 
357
 
            <p>This event can only be subscribed with
358
 
            <code>Y.on(&quot;windowresize&quot;, callback)</code>;</p>
359
 
        </td>
360
 
    </tr>
361
 
    <tr>
362
 
        <td><a href="http://yuilibrary.com/yui/docs/api/module_event-touch.html"><code>event-touch</code></a></td>
363
 
        <td>
364
 
            Adds support for <a href="touch.html">subscribing to native touch
365
 
            and gesture events</a>.
366
 
        </td>
367
 
    </tr>
368
 
    <tr>
369
 
        <td><a href="http://yuilibrary.com/yui/docs/api/module_event-valuechange.html"><code>event-valuechange</code></a></td>
370
 
        <td>
371
 
            Adds a <a href="valuechange.html">"valueChange" event</a> that fires when input element text
372
 
            changes (this is harder than you think).
373
 
        </td>
374
 
    </tr>
375
 
</tbody>
376
 
</table>
377
 
 
378
 
<h2 id="delegation">Event Delegation</h2>
379
 
 
380
 
<p>If you don't already know what event delegation is, you should <a
381
 
href="delegation.html">read this quick overview</a>. Short form: <em>you need
382
 
to be using this</em>.</p>
383
 
 
384
 
<pre class="code prettyprint">&#x2F;&#x2F; single element subscription
385
 
node.on(&quot;click&quot;, handleClick);
386
 
 
387
 
&#x2F;&#x2F; delegated subscription for all button clicks from inside the node
388
 
node.delegate(&quot;click&quot;, handleClick, &quot;button, input[type=button]&quot;);</pre>
389
 
 
390
 
 
391
 
<p>Creating a delegated subscription looks very much like creating any other
392
 
event subscription with two differences. First, it's a different method name,
393
 
<code>delegate</code>.  Second, there is another argument: a CSS selector that is used to
394
 
test the event's originating element to decide if the callback should be
395
 
executed.  If the event started at or inside an element matching the selector,
396
 
the callback will execute.</p>
397
 
 
398
 
<p>Unlike <code>node.on()</code> subscriptions, the <code>this</code> object in <code>node.delegate()</code>
399
 
callbacks will refer to the element that matched the css filter, not to <code>node</code>.
400
 
We did this because likely your logic revolves around the nodes described by
401
 
the filter, not around the element that contains them.</p>
402
 
 
403
 
<pre class="code prettyprint">function handleClick (e) {
404
 
    &#x2F;&#x2F; &#x60;this&#x60; is the button with class .remove, not the #items element
405
 
    &#x2F;&#x2F; remove the containing LI
406
 
    this.ancestor(&#x27;li&#x27;).remove();
407
 
 
408
 
    &#x2F;&#x2F; e.currentTarget is also the button.remove
409
 
    &#x2F;&#x2F; e.container === Y.one(&#x27;#items&#x27;)
410
 
}
411
 
 
412
 
Y.one(&#x27;#items&#x27;).delegate(&#x27;click&#x27;, handleClick, &#x27;button.remove&#x27;);</pre>
413
 
 
414
 
 
415
 
<p>For more complex target filtering, a function can be passed instead of a css
416
 
selector.  See the
417
 
<a href="http://yuilibrary.com/yui/docs/api/module_event-delegate.html#method_delegate">API docs</a>
418
 
for more details.</p>
419
 
 
420
 
<p>As noted <a href="#modules">above</a>, the <code>event-delegate</code> module is
421
 
included in the <code>event</code> rollup, but <code>node-event-delegate</code> isn't.  We recommend
422
 
using delegation from the Node API, so you should <code>use()</code> either
423
 
<code>node-event-delegate</code> or the <code>node</code> rollup.</p>
424
 
 
425
 
 
426
 
<h2 id="more">More Event API Goodness</h2>
427
 
 
428
 
<p>
429
 
    Here is a sampling of some of the other ways to manage event subscriptions
430
 
    in YUI.
431
 
</p>
432
 
 
433
 
<h4 id="y-on">Subscribe from <code>Y</code></h4>
434
 
 
435
 
<pre class="code prettyprint">&#x2F;&#x2F; Y.on() takes a third argument which is the Node, DOM element,
436
 
&#x2F;&#x2F; or CSS selector of the element(s) to bind
437
 
Y.on(&quot;click&quot;, handleClick, &quot;#readygo&quot;);
438
 
 
439
 
&#x2F;&#x2F; Y.delegate() similarly takes the containing element or selector
440
 
&#x2F;&#x2F; as the third argument
441
 
Y.delegate(&quot;click&quot;, handleClick, &quot;#container&quot;, &quot;button, input[type=button]&quot;);</pre>
442
 
 
443
 
 
444
 
<p>
445
 
    An alternate syntax for DOM subscriptions is using <code>Y.on()</code> or
446
 
    <code>Y.delegate()</code>.  When identifying the target by a CSS selector, these
447
 
    methods can be used regardless if the element is currently available for
448
 
    scripting.  If it's not yet on the page, a poll will regularly look for it
449
 
    (for a few seconds) and the subscription will be automatically attached
450
 
    when the element is found.  Relying on this behavior can introduce race
451
 
    conditions, though, so use it wisely.
452
 
</p>
453
 
<p>
454
 
    Use of <code>Y.on()</code> instead of <code>node.on()</code> is largely a stylistic preference,
455
 
    though <a href="#y-on-vs-node-on">there are some technical differences</a>.
456
 
</p>
457
 
 
458
 
 
459
 
<h4 id="once">One time subscriptions</h4>
460
 
 
461
 
<pre class="code prettyprint">tabLabel.once(&#x27;mouseover&#x27;, loadTabContent);</pre>
462
 
 
463
 
 
464
 
<p>If you only want to execute a callback on the first occurrence of an event, use <code>node.once()</code> or <code>Y.once()</code>.  The subscription will automatically be detached after the event fires.</p>
465
 
 
466
 
<p>The signature for <code>once()</code> is the same as <code>on()</code>.</p>
467
 
 
468
 
<h4 id="grouping-subscriptions">Grouping subscriptions</h4>
469
 
 
470
 
<p>Pass an object to subscribe to multiple events, each with their own
471
 
callback</p>
472
 
 
473
 
<pre class="code prettyprint">function validate(e) { ... }
474
 
function clearPlaceholder(e) { ... }
475
 
 
476
 
var groupSub = inputNode.on({
477
 
    blur    : validate,
478
 
    keypress: validate,
479
 
    focus   : clearPlaceholder
480
 
});
481
 
 
482
 
&#x2F;&#x2F; Detach the blur, keypress, and focus subscriptions in one call
483
 
groupSub.detach();</pre>
484
 
 
485
 
 
486
 
<p>Pass an array to subscribe to multiple events with the same callback</p>
487
 
<pre class="code prettyprint">function activate(e) { ... }
488
 
 
489
 
groupSub = inputNode.on([&#x27;focus&#x27;, &#x27;mouseover&#x27;], activate);
490
 
 
491
 
&#x2F;&#x2F; Detach the focus and mouseover subscriptions
492
 
groupSub.detach();</pre>
493
 
 
494
 
 
495
 
<p>Prefix the event name with a category to allow detaching multiple
496
 
subscriptions by that category.</p>
497
 
 
498
 
<pre class="code prettyprint">inputNode.on(&#x27;my-category|focus&#x27;, activate);
499
 
inputNode.on(&#x27;my-category|mouseover&#x27;, activate);
500
 
 
501
 
&#x2F;&#x2F; You can detach specific subscriptions by &#x27;my-category|focus&#x27; or all with |*
502
 
inputNode.detach(&#x27;my-category|*&#x27;);</pre>
503
 
 
504
 
 
505
 
<p>The <code>once()</code> and <code>delegate()</code> methods also support these alternate
506
 
signatures.</p>
507
 
 
508
 
<h4 id="extended-signature">Binding <code>this</code> and additional callback arguments</h4>
509
 
 
510
 
<p>
511
 
    By default, the "<code>this</code>" object in subscription callbacks will be the Node
512
 
    or NodeList that subscribed to them.  Override this default by passing your
513
 
    own <code>this</code> object as the third argument to <code>on()</code> or the fourth to
514
 
    <code>delegate()</code>.  Note that the argument index is shifted when using <code>Y.on()</code>
515
 
    and <code>Y.delegate()</code> or <a href="synths.html">synthetic events with custom
516
 
    signatures</a>.
517
 
</p>
518
 
 
519
 
<pre class="code prettyprint">&#x2F;&#x2F; equivalent to node.on(&#x27;click&#x27;, function (e) { overlay.hide(e); });
520
 
node.on(&#x27;click&#x27;, overlay.show, overlay);
521
 
 
522
 
node.once(&#x27;mouseover&#x27;, door.unlock, door);
523
 
 
524
 
&#x2F;&#x2F; &#x60;this&#x60; override comes after the filter; also shifted for the &#x27;key&#x27; event&#x27;s
525
 
&#x2F;&#x2F; custome signature.
526
 
container.delegate(&#x27;key&#x27;, validator.isValid, &#x27;enter,tab&#x27;, &#x27;input&#x27;, validator);
527
 
 
528
 
&#x2F;&#x2F; Corresponding alternatives from Y
529
 
Y.on(&#x27;click&#x27;, overlay.show, &#x27;#show&#x27;, overlay);
530
 
 
531
 
Y.once(&#x27;mouseover&#x27;, door.unlock, &#x27;#gate13&#x27;, door);
532
 
 
533
 
Y.delegate(&#x27;key&#x27;, validator.isValid, &#x27;#myForm&#x27;, &#x27;enter,tab&#x27;, &#x27;input&#x27;, validator);</pre>
534
 
 
535
 
 
536
 
<p>Additional arguments passed to the subscription methods will be sent along
537
 
to the callback after the event facade. If you want to bind extra arguments,
538
 
but don't want to override the "<code>this</code>" object, pass <code>null</code> for the <code>this</code>
539
 
argument.</p>
540
 
 
541
 
<pre class="code prettyprint">MyClass.prototype = {
542
 
    someMethod: function (param) {
543
 
        Y.log(param); &#x2F;&#x2F; =&gt; &quot;I&#x27;m Extra!&quot;
544
 
    },
545
 
 
546
 
    handleClick: function (e, extraParam) {
547
 
        this.someMethod(extraParam);
548
 
        ...
549
 
    },
550
 
    ...
551
 
};
552
 
 
553
 
var instance = new Y.MyClass();
554
 
 
555
 
&#x2F;&#x2F; The extra arg is passed as the second param to the callback after &#x60;e&#x60;
556
 
Y.one(&#x27;#readygo&#x27;).on(&#x27;click&#x27;, instance.handleClick, instance, &quot;I&#x27;m Extra!&quot;);</pre>
557
 
 
558
 
 
559
 
<h4 id="detach-methods">More ways to clean up subscriptions</h4>
560
 
 
561
 
<p>There are a lot of options for detaching events in YUI.  See the table below for details.</p>
562
 
 
563
 
<table>
564
 
<thead>
565
 
    <tr>
566
 
        <th>Method</th>
567
 
        <th>What it does</th>
568
 
    </tr>
569
 
</thead>
570
 
<tbody>
571
 
    <tr>
572
 
        <td>
573
 
<pre class="code prettyprint">var subscription = node.on(&#x27;click&#x27;, callback);
574
 
 
575
 
subscription.detach();</pre>
576
 
 
577
 
        </td>
578
 
        <td>
579
 
            <p>
580
 
                Removes a specific subscription or, if created with one of the
581
 
                group subscription methods, a group of subscriptions.
582
 
            </p>
583
 
            <p>
584
 
                Generally, this is the best method to use.
585
 
            </p>
586
 
        </td>
587
 
    </tr>
588
 
    <tr id="remove-by-category">
589
 
        <td>
590
 
<pre class="code prettyprint">node.on(&#x27;foo-category|click&#x27;, callback);
591
 
 
592
 
node.detach(&#x27;foo-category|click&#x27;);
593
 
&#x2F;&#x2F; OR
594
 
node.detach(&#x27;foo-category|*&#x27;);</pre>
595
 
 
596
 
        </td>
597
 
        <td>
598
 
            <p>
599
 
                Removes a subscription or group of subscriptions that included
600
 
                the specified category in the subscription event type.
601
 
            </p>
602
 
            <p>
603
 
                This is typically only safe in implementation code, not
604
 
                module code, because multiple subscriptions using the same type
605
 
                and category will be detached by the call to <code>detach</code>.
606
 
            </p>
607
 
        </td>
608
 
    </tr>
609
 
    <tr>
610
 
        <td>
611
 
<pre class="code prettyprint">node.detach(&#x27;click&#x27;, callback);
612
 
&#x2F;&#x2F; OR
613
 
node.detach(&#x27;click&#x27;);
614
 
&#x2F;&#x2F; OR
615
 
node.detach():</pre>
616
 
 
617
 
        </td>
618
 
        <td>
619
 
            <p>
620
 
                If you have a reference to the subscribed callback function,
621
 
                (but not a subscription handle) use the two argument signature.
622
 
            </p>
623
 
            <p>
624
 
                With one argument, <code>detach</code> will remove all subscriptions for
625
 
                the specified event.  With no arguments, it removes all
626
 
                subscriptions for all events.
627
 
            </p>
628
 
            <p>
629
 
                <code>detach</code> does not remove subscriptions from descendant nodes.
630
 
            </p>
631
 
        </td>
632
 
    </tr>
633
 
    <tr>
634
 
        <td>
635
 
<pre class="code prettyprint">node.detachAll();</pre>
636
 
 
637
 
        </td>
638
 
        <td>
639
 
            <p>
640
 
                Works the same as <code>node.detach()</code>.
641
 
            </p>
642
 
        </td>
643
 
    </tr>
644
 
    <tr>
645
 
        <td>
646
 
<pre class="code prettyprint">node.purge();
647
 
&#x2F;&#x2F; OR
648
 
node.purge(true);
649
 
&#x2F;&#x2F; OR
650
 
node.purge(true, &#x27;click&#x27;);</pre>
651
 
 
652
 
        </td>
653
 
        <td>
654
 
            <p>
655
 
                With no arguments, <code>purge</code> works the same as <code>node.detach()</code>.
656
 
            </p>
657
 
            <p>
658
 
                Passing <code>true</code> as a first argument will remove all
659
 
                subscriptions for all events from the node <em>and its
660
 
                descendant subtree</em>. Passing an event type as a second
661
 
                argument will only deep purge subscriptions to that event.
662
 
            </p>
663
 
        </td>
664
 
    </tr>
665
 
    <tr>
666
 
        <td>
667
 
<pre class="code prettyprint">node.empty();</pre>
668
 
 
669
 
        </td>
670
 
        <td>
671
 
            <p>
672
 
                Removes subscriptions for all events <em>only from the
673
 
                descendants of a node</em> after removing them from the DOM.
674
 
            </p>
675
 
        </td>
676
 
    </tr>
677
 
    <tr>
678
 
        <td>
679
 
<pre class="code prettyprint">node.destroy();
680
 
&#x2F;&#x2F; OR
681
 
node.destroy(true);</pre>
682
 
 
683
 
        </td>
684
 
        <td>
685
 
            <p>
686
 
                With no arguments, works like <code>node.detach()</code>.
687
 
            </p>
688
 
            <p>
689
 
                With <code>true</code> as a first argument, it works like
690
 
                <code>node.purge(true)</code>.
691
 
            </p>
692
 
            <p>
693
 
                The <code>destroy</code> method does more than detaching event
694
 
                subscribers.  Read the
695
 
                <a href="http://yuilibrary.com/yui/docs/api/classes/Node.html#method_destroy">API
696
 
                docs</a> for details.
697
 
            </p>
698
 
        </td>
699
 
    </tr>
700
 
    <tr>
701
 
        <td>
702
 
<pre class="code prettyprint">Y.Event.detach(&#x27;click&#x27;, callback, &#x27;#foo&#x27;);</pre>
703
 
 
704
 
        </td>
705
 
        <td>
706
 
            <p>
707
 
                Same as <code>Y.one(&#x27;#foo&#x27;).detach( [other args] )</code>.
708
 
            </p>
709
 
        </td>
710
 
    </tr>
711
 
    <tr>
712
 
        <td>
713
 
<pre class="code prettyprint">Y.Event.purgeElement(&#x27;#foo&#x27;, true, &#x27;click&#x27;);</pre>
714
 
 
715
 
        </td>
716
 
        <td>
717
 
            <p>
718
 
                Same as <code>Y.one(&#x27;#foo&#x27;).purge( [other args] )</code>.
719
 
            </p>
720
 
        </td>
721
 
    </tr>
722
 
</tbody>
723
 
</table>
724
 
 
725
 
<h2 id="simulate">Simulate browser events</h2>
726
 
 
727
 
<p>
728
 
    For creating automated functional tests, being able to simulate user
729
 
    interaction can be crucial.  That's where the <code>node-event-simulate</code> module
730
 
    comes in.
731
 
</p>
732
 
 
733
 
<pre class="code prettyprint">YUI().use(&#x27;test&#x27;, &#x27;node-event-simulate&#x27;, &#x27;fancy&#x27;, function (Y) {
734
 
 
735
 
var test = new Y.Test.Case({
736
 
    ...
737
 
 
738
 
    &quot;clicking close button should dismiss UI&quot;: function () {
739
 
 
740
 
        var widget      = new Y.MyFancyWidget().render(&#x27;#here&#x27;),
741
 
            uiBox       = widget.get(&#x27;boundingBox&#x27;),
742
 
            closeButton = uiBox.one(&#x27;.close-button&#x27;);
743
 
 
744
 
        closeButton.simulate(&#x27;click&#x27;);
745
 
 
746
 
        Y.Assert.isFalse( uiBox.inDoc() );
747
 
    },
748
 
    ...</pre>
749
 
 
750
 
 
751
 
<p>
752
 
    <code>node.simulate( type, eventProperties )</code> creates a native DOM event that
753
 
    will bubble (if appropriate), but will not trigger native default behavior.
754
 
    For example, <code>node.simulate(&#x27;submit&#x27;)</code> will not send data to the server for
755
 
    a page reload.
756
 
</p>
757
 
 
758
 
<p>Read <a href="simulate.html">more about event simulation here</a>.</p>
759
 
 
760
 
<h2 id="synthetic-events">Synthetic Events</h2>
761
 
 
762
 
<p>The event system supports adding new abstractions over the native DOM
763
 
environment that behave like DOM events.  These abstractions are called
764
 
synthetic events, and you can subscribe to them like any other DOM event with
765
 
<code>node.on()</code> or <code>node.delegate()</code>.</p>
766
 
 
767
 
<pre class="code prettyprint">Y.one(&#x27;#dialog&#x27;).on(&#x27;clickoutside&#x27;, function (e) {
768
 
    this.transition(&#x27;fadeOut&#x27;);
769
 
});
770
 
 
771
 
Y.one(&#x27;#editable-table&#x27;).delegate(&#x27;key&#x27;, saveAndAdvance, &#x27;tab&#x27;, &#x27;input&#x27;);</pre>
772
 
 
773
 
 
774
 
<p>
775
 
    The synthetic events that are available as core YUI modules are listed in
776
 
    <a href="#modules">the table of modules above</a>, though there are others
777
 
    <a href="http://yuilibrary.com/gallery/">in the Gallery</a>.  Most events
778
 
    listed in the table are linked to pages that describe the specific event in
779
 
    more detail.
780
 
</p>
781
 
 
782
 
<h4 id="creating-dom-events">Creating DOM events</h4>
783
 
 
784
 
<p>Create your own synthetic events with <code>Y.Event.define(type, config)</code>.</p>
785
 
 
786
 
<pre class="code prettyprint">Y.Event.define(&quot;tripleclick&quot;, {
787
 
 
788
 
    &#x2F;&#x2F; The setup logic executed when node.on(&#x27;tripleclick&#x27;, callback) is called
789
 
    on: function (node, subscription, notifier) {
790
 
        &#x2F;&#x2F; supporting methods can be referenced from &#x60;this&#x60;
791
 
        this._clear(subscription);
792
 
 
793
 
        &#x2F;&#x2F; To make detaching easy, a common pattern is to add the subscription
794
 
        &#x2F;&#x2F; for the supporting DOM event to the subscription object passed in.
795
 
        &#x2F;&#x2F; This is then referenced in the detach() method below.
796
 
        subscription._handle = node.on(&#x27;click&#x27;, function (e) {
797
 
            if (subscription._timer) {
798
 
                subscription._timer.cancel();
799
 
            }
800
 
 
801
 
            if (++subscription._counter === 3) {
802
 
                this._clear(subscription);
803
 
 
804
 
                &#x2F;&#x2F; The notifier triggers the subscriptions to be executed.
805
 
                &#x2F;&#x2F; Pass its fire() method the triggering DOM event facade
806
 
                notifier.fire(e);
807
 
            } else {
808
 
                subscription._timer =
809
 
                    Y.later(300, this, this._clear, [subscription]);
810
 
            }
811
 
        });
812
 
    },
813
 
 
814
 
    &#x2F;&#x2F; The logic executed when the &#x27;tripleclick&#x27; subscription is &#x60;detach()&#x60;ed
815
 
    detach: function (node, subscription, notifier) {
816
 
        &#x2F;&#x2F; Clean up supporting DOM subscriptions and other external hooks
817
 
        &#x2F;&#x2F; when the synthetic event subscription is detached.
818
 
        subscription._handle.detach();
819
 
 
820
 
        if (subscription._timer) {
821
 
            subscription._timer.cancel();
822
 
        }
823
 
    },
824
 
 
825
 
    &#x2F;&#x2F; Additional methods can be added to support the lifecycle methods
826
 
    _clear: function (subscription) {
827
 
        subscription._counter = 0;
828
 
        subscription._timer = null;
829
 
    },
830
 
    
831
 
    ...
832
 
});</pre>
833
 
 
834
 
 
835
 
<p>After the synthetic event is defined, it is available for every Node and
836
 
NodeList to subscribe to.</p>
837
 
 
838
 
<pre class="code prettyprint">Y.one(&#x27;#hellokitty&#x27;).on(&#x27;tripleclick&#x27;, omgYayCantClickEnough);</pre>
839
 
 
840
 
 
841
 
<p>There is additional configuration to <a href="synths.html">add support for
842
 
<code>delegate()</code> or extra subscription arguments</a>, but often very little extra
843
 
code is needed.</p>
844
 
 
845
 
<h2 id="troubleshootingfaq">Troubleshooting/FAQ</h2>
846
 
 
847
 
<ul>
848
 
    <li><a href="#function-reference">My callback is executing at the wrong time. What's going on?</a></li>
849
 
    <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>
850
 
    <li><a href="#which-events">What events can I subscribe to?</a></li>
851
 
    <li><a href="#why-on-no-chain">Why isn't on() chainable?</a></li>
852
 
    <li><a href="#y-on-vs-node-on">Why would I use <code>Y.on()</code> or <code>Y.delegate()</code> instead of <code>node.on()</code> and <code>node.delegate()</code>?</a></li>
853
 
    <li><a href="#after">EventTarget also provides an <code>after()</code> method. How does that work for DOM events?</a></li>
854
 
    <li><a href="#nodelist-this">When I subscribe to an event from a NodeList, <code>this</code> is the NodeList, not the individual Node.  What's up with that?</a></li>
855
 
    <li><a href="#nodelist-delegate">Where is <code>nodelist.delegate()</code>?</a></li>
856
 
    <!--li><a href="#">What works and what doesn't on mobile browsers?</a></li-->
857
 
</ul>
858
 
 
859
 
<h4 id="function-reference">My callback is executing at the wrong time. What's going on?</h4>
860
 
 
861
 
<p>It's likely that you've included parenthese in the subscription.</p>
862
 
<pre class="code prettyprint">&#x2F;&#x2F; WRONG
863
 
node.on(&#x27;click&#x27;, someFunction());
864
 
node.on(&#x27;click&#x27;, myObject.someFunction());
865
 
 
866
 
&#x2F;&#x2F; RIGHT
867
 
node.on(&#x27;click&#x27;, someFunction);
868
 
node.on(&#x27;click&#x27;, myObject.someFunction, myObject);</pre>
869
 
 
870
 
 
871
 
<p>
872
 
    Including the parens makes the function execute immediately, and pass the
873
 
    return value from the function to <code>node.on(&#x27;click&#x27;, [RETURN VALUE])</code>.  To
874
 
    pass a function around, just omit the parens.
875
 
</p>
876
 
 
877
 
<h4 id="wrong-this">I'm getting an error in my callback that "<code>(some object) has no method (someMethodOnMyObject)</code>". What am I missing?</h4>
878
 
 
879
 
<p>
880
 
    You may be passing an object method to <code>on()</code>, but forgot to include
881
 
    <a href="#extended-signature">the <code>this</code> object override parameter</a> in
882
 
    the subscription.
883
 
</p>
884
 
 
885
 
<p>
886
 
    Another option to make sure object methods are called with the correct
887
 
    <code>this</code> object is to use
888
 
    <a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_bind">`Y.bind(obj.method,
889
 
    obj)`</a> or
890
 
    <a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_rbind">`Y.rbind(obj.method,
891
 
    obj)`</a>.
892
 
</p>
893
 
 
894
 
<pre class="code prettyprint">&#x2F;&#x2F; WRONG
895
 
node.on(&#x27;click&#x27;, myObj.method);
896
 
 
897
 
&#x2F;&#x2F; RIGHT
898
 
node.on(&#x27;click&#x27;, myObj.method, myObj);
899
 
 
900
 
&#x2F;&#x2F; RIGHT (alternate)
901
 
node.on(&#x27;click&#x27;, Y.rbind(obj.method, obj));</pre>
902
 
 
903
 
 
904
 
<h4 id="which-events">What events can I subscribe to?</h4>
905
 
 
906
 
<p>
907
 
    It depends what modules you've included.  Check out the
908
 
    <a href="#event-whitelist">whitelisted events table</a>.
909
 
</p>
910
 
 
911
 
<h4 id="why-on-no-chain">Why isn't on() chainable?</h4>
912
 
 
913
 
<p>
914
 
    After much deliberation, the YUI team decided that returning a subscription
915
 
    handle was preferable to chaining in order to better support clean event
916
 
    detaching across the various scenarios that DOM and custom events are used.
917
 
</p>
918
 
<p>
919
 
    In any sizable application, managing event subscriptions becomes
920
 
    increasingly important, and detaching events must be done with precision.
921
 
    Because YUI allows duplicate subscriptions, any host-based detach method
922
 
    will necessarily be less than 100% reliable with respect to avoiding
923
 
    removal of subscriptions made by other parts of the system.
924
 
</p>
925
 
<p>
926
 
    Otherwise, it's common to subscribe to events with anonymous functions,
927
 
    which makes it impossible to detach the specific subscription by signature
928
 
    because you don't have a function reference to use to identify the specific
929
 
    subscription to remove.  Subscription categories can be used, but
930
 
    <a href="#remove-by-category">are also less precise</a> than
931
 
    dealing with a specific subscription object.
932
 
</p>
933
 
 
934
 
<h4 id="y-on-vs-node-on">Why would I use <code>Y.on()</code> or <code>Y.delegate()</code> instead of <code>node.on()</code> and <code>node.delegate()</code>?</h4>
935
 
 
936
 
<p>
937
 
    It's <a href="#y-on">largely a stylistic preference</a>, but there are some
938
 
    technical differences when passing a selector string as a the third
939
 
    argument to <code>Y.on()</code> or <code>Y.delegate()</code> (ala
940
 
    <code>Y.on(&#x27;click&#x27;, callback, &#x27;#some select.or-string&#x27;)</code>.
941
 
</p>
942
 
 
943
 
<ol>
944
 
    <li>
945
 
        <p>
946
 
            <code>Y.on()</code> uses the
947
 
            <a href="http://yuilibrary.com/yui/docs/api/classes/Selector.html">Selector engine</a>
948
 
            directly rather than calling through <code>Y.all(...)</code>.
949
 
        </p>
950
 
        <p>
951
 
            The benefit here is that the Node and NodeList constructors add the
952
 
            slightest bit of overhead to the subscription process.
953
 
        </p>
954
 
    </li>
955
 
    <li>
956
 
        When passing a selector that matches multiple elements, the <code>this</code> in
957
 
        the callback will be the individual Node, not a
958
 
        <a href="#nodelist-this">NodeList wrapping all matched elements</a>.
959
 
    </li>
960
 
    <li>
961
 
        <p>
962
 
            If called before the elements matching the selector are attached to
963
 
            the DOM, it will poll for a few seconds and automatically attach
964
 
            the subscription when the first matching element is found.
965
 
        </p>
966
 
        <p>
967
 
            Note, if using a selector that matches multiple elements, the poll
968
 
            will attach the subscription the first time Selector finds a match.
969
 
            This <em>may not include all the elements</em> because either the
970
 
            DOM is not fully updated yet, or the code that adds the matching
971
 
            elements may happen in batches.
972
 
        </p>
973
 
        <p>In practice, it is best to avoid reliance on this behavior.</p>
974
 
    </li>
975
 
</ol>
976
 
 
977
 
<h4 id="after"><code>EventTarget</code> also provides an <code>after()</code> method. How does that work for DOM events?</h4>
978
 
 
979
 
<p>
980
 
    <code>node.after(...)</code> is equivalent to <code>node.on(...)</code>.  The DOM doesn't expose
981
 
    an "after" moment to hook into.
982
 
</p>
983
 
 
984
 
<h4 id="nodelist-this">When I subscribe to an event from a NodeList, <code>this</code> is the NodeList, not the individual Node.  What's up with that?</h4>
985
 
 
986
 
<p>
987
 
    In the callback, <code>e.currentTarget</code> will always refer to the individual Node.
988
 
    However, if you call
989
 
</p>
990
 
 
991
 
<pre class="code prettyprint">Y.all(&#x27;#some select.or-string&#x27;).on(&#x27;click&#x27;, function (e) {
992
 
    &#x2F;&#x2F; how do I reference the NodeList?
993
 
});</pre>
994
 
 
995
 
 
996
 
<p>
997
 
    you can't reference the NodeList captured by <code>Y.all()</code> without calling
998
 
    <code>Y.all()</code> again, but that results in unnecessary overhead, and may match
999
 
    different elements in the subsequent call.
1000
 
</p>
1001
 
 
1002
 
<p>
1003
 
    In general, you should avoid <code>nodelist.on()</code> anyway,
1004
 
    <a href="#delegation">in favor of event delegation</a>.
1005
 
</p>
1006
 
 
1007
 
<h4 id="nodelist-delegate">Where is <code>nodelist.delegate()</code>?</h4>
1008
 
 
1009
 
<p>
1010
 
    The point of delegation is to reduce the number of subscriptions being made.
1011
 
    <code>nodelist.delegate()</code> would be philosophically at odds with that. Either
1012
 
    call <code>node.delegate()</code> from an element higher up the DOM tree, or <em>if
1013
 
    you must</em> delegate the same event and callback from multiple
1014
 
    containers, use
1015
 
</p>
1016
 
 
1017
 
<pre class="code prettyprint">nodelist.each(function (node) {
1018
 
    node.delegate(&#x27;click&#x27;, callback, &#x27;.not-recommended&#x27;);
1019
 
});</pre>
1020
 
 
1021
 
 
1022
 
<h2 id="event-whitelist">Appendix A: Whitelisted DOM events</h2>
1023
 
 
1024
 
<div id="events">
1025
 
<table>
1026
 
<thead>
1027
 
    <tr>
1028
 
        <th>Event</th>
1029
 
        <th>Added by</th>
1030
 
    </tr>
1031
 
</thead>
1032
 
<tbody>
1033
 
    <tr>
1034
 
        <td>abort</td>
1035
 
        <td>node-base</td>
1036
 
    </tr>
1037
 
    <tr>
1038
 
        <td>beforeunload</td>
1039
 
        <td>node-base</td>
1040
 
    </tr>
1041
 
    <tr>
1042
 
        <td>blur</td>
1043
 
        <td>node-base</td>
1044
 
    </tr>
1045
 
    <tr>
1046
 
        <td>change</td>
1047
 
        <td>node-base</td>
1048
 
    </tr>
1049
 
    <tr>
1050
 
        <td>click</td>
1051
 
        <td>node-base</td>
1052
 
    </tr>
1053
 
    <tr>
1054
 
        <td>close</td>
1055
 
        <td>node-base</td>
1056
 
    </tr>
1057
 
    <tr>
1058
 
        <td>command</td>
1059
 
        <td>node-base</td>
1060
 
    </tr>
1061
 
    <tr>
1062
 
        <td>contextmenu</td>
1063
 
        <td>node-base</td>
1064
 
    </tr>
1065
 
    <tr>
1066
 
        <td>dblclick</td>
1067
 
        <td>node-base</td>
1068
 
    </tr>
1069
 
    <tr>
1070
 
        <td>DOMMouseScroll</td>
1071
 
        <td>node-base</td>
1072
 
    </tr>
1073
 
    <tr>
1074
 
        <td>drag</td>
1075
 
        <td>node-base</td>
1076
 
    </tr>
1077
 
    <tr>
1078
 
        <td>dragstart</td>
1079
 
        <td>node-base</td>
1080
 
    </tr>
1081
 
    <tr>
1082
 
        <td>dragenter</td>
1083
 
        <td>node-base</td>
1084
 
    </tr>
1085
 
    <tr>
1086
 
        <td>dragover</td>
1087
 
        <td>node-base</td>
1088
 
    </tr>
1089
 
    <tr>
1090
 
        <td>dragleave</td>
1091
 
        <td>node-base</td>
1092
 
    </tr>
1093
 
    <tr>
1094
 
        <td>dragend</td>
1095
 
        <td>node-base</td>
1096
 
    </tr>
1097
 
    <tr>
1098
 
        <td>drop</td>
1099
 
        <td>node-base</td>
1100
 
    </tr>
1101
 
    <tr>
1102
 
        <td>error</td>
1103
 
        <td>node-base</td>
1104
 
    </tr>
1105
 
    <tr>
1106
 
        <td>focus</td>
1107
 
        <td>node-base</td>
1108
 
    </tr>
1109
 
    <tr>
1110
 
        <td>key</td>
1111
 
        <td>node-base</td>
1112
 
    </tr>
1113
 
    <tr>
1114
 
        <td>keydown</td>
1115
 
        <td>node-base</td>
1116
 
    </tr>
1117
 
    <tr>
1118
 
        <td>keypress</td>
1119
 
        <td>node-base</td>
1120
 
    </tr>
1121
 
    <tr>
1122
 
        <td>keyup</td>
1123
 
        <td>node-base</td>
1124
 
    </tr>
1125
 
    <tr>
1126
 
        <td>load</td>
1127
 
        <td>node-base</td>
1128
 
    </tr>
1129
 
    <tr>
1130
 
        <td>message</td>
1131
 
        <td>node-base</td>
1132
 
    </tr>
1133
 
    <tr>
1134
 
        <td>mousedown</td>
1135
 
        <td>node-base</td>
1136
 
    </tr>
1137
 
    <tr>
1138
 
        <td>mouseenter</td>
1139
 
        <td>node-base</td>
1140
 
    </tr>
1141
 
    <tr>
1142
 
        <td>mouseleave</td>
1143
 
        <td>node-base</td>
1144
 
    </tr>
1145
 
    <tr>
1146
 
        <td>mousemove</td>
1147
 
        <td>node-base</td>
1148
 
    </tr>
1149
 
    <tr>
1150
 
        <td>mousemultiwheel</td>
1151
 
        <td>node-base</td>
1152
 
    </tr>
1153
 
    <tr>
1154
 
        <td>mouseout</td>
1155
 
        <td>node-base</td>
1156
 
    </tr>
1157
 
    <tr>
1158
 
        <td>mouseover</td>
1159
 
        <td>node-base</td>
1160
 
    </tr>
1161
 
    <tr>
1162
 
        <td>mouseup</td>
1163
 
        <td>node-base</td>
1164
 
    </tr>
1165
 
    <tr>
1166
 
        <td>mousewheel</td>
1167
 
        <td>node-base</td>
1168
 
    </tr>
1169
 
    <tr>
1170
 
        <td>orientationchange</td>
1171
 
        <td>node-base</td>
1172
 
    </tr>
1173
 
    <tr>
1174
 
        <td>reset</td>
1175
 
        <td>node-base</td>
1176
 
    </tr>
1177
 
    <tr>
1178
 
        <td>resize</td>
1179
 
        <td>node-base</td>
1180
 
    </tr>
1181
 
    <tr>
1182
 
        <td>select</td>
1183
 
        <td>node-base</td>
1184
 
    </tr>
1185
 
    <tr>
1186
 
        <td>selectstart</td>
1187
 
        <td>node-base</td>
1188
 
    </tr>
1189
 
    <tr>
1190
 
        <td>submit</td>
1191
 
        <td>node-base</td>
1192
 
    </tr>
1193
 
    <tr>
1194
 
        <td>scroll</td>
1195
 
        <td>node-base</td>
1196
 
    </tr>
1197
 
    <tr>
1198
 
        <td>textInput</td>
1199
 
        <td>node-base</td>
1200
 
    </tr>
1201
 
    <tr>
1202
 
        <td>unload</td>
1203
 
        <td>node-base</td>
1204
 
    </tr>
1205
 
 
1206
 
    <tr>
1207
 
        <td>DOMActivate</td>
1208
 
        <td>node-event-html5</td>
1209
 
    </tr>
1210
 
    <tr>
1211
 
        <td>DOMContentLoaded</td>
1212
 
        <td>node-event-html5</td>
1213
 
    </tr>
1214
 
    <tr>
1215
 
        <td>afterprint</td>
1216
 
        <td>node-event-html5</td>
1217
 
    </tr>
1218
 
    <tr>
1219
 
        <td>beforeprint</td>
1220
 
        <td>node-event-html5</td>
1221
 
    </tr>
1222
 
    <tr>
1223
 
        <td>canplay</td>
1224
 
        <td>node-event-html5</td>
1225
 
    </tr>
1226
 
    <tr>
1227
 
        <td>canplaythrough</td>
1228
 
        <td>node-event-html5</td>
1229
 
    </tr>
1230
 
    <tr>
1231
 
        <td>durationchange</td>
1232
 
        <td>node-event-html5</td>
1233
 
    </tr>
1234
 
    <tr>
1235
 
        <td>emptied</td>
1236
 
        <td>node-event-html5</td>
1237
 
    </tr>
1238
 
    <tr>
1239
 
        <td>ended</td>
1240
 
        <td>node-event-html5</td>
1241
 
    </tr>
1242
 
    <tr>
1243
 
        <td>formchange</td>
1244
 
        <td>node-event-html5</td>
1245
 
    </tr>
1246
 
    <tr>
1247
 
        <td>forminput</td>
1248
 
        <td>node-event-html5</td>
1249
 
    </tr>
1250
 
    <tr>
1251
 
        <td>hashchange</td>
1252
 
        <td>node-event-html5</td>
1253
 
    </tr>
1254
 
    <tr>
1255
 
        <td>input</td>
1256
 
        <td>node-event-html5</td>
1257
 
    </tr>
1258
 
    <tr>
1259
 
        <td>invalid</td>
1260
 
        <td>node-event-html5</td>
1261
 
    </tr>
1262
 
    <tr>
1263
 
        <td>loadedmetadata</td>
1264
 
        <td>node-event-html5</td>
1265
 
    </tr>
1266
 
    <tr>
1267
 
        <td>loadeddata</td>
1268
 
        <td>node-event-html5</td>
1269
 
    </tr>
1270
 
    <tr>
1271
 
        <td>loadstart</td>
1272
 
        <td>node-event-html5</td>
1273
 
    </tr>
1274
 
    <tr>
1275
 
        <td>offline</td>
1276
 
        <td>node-event-html5</td>
1277
 
    </tr>
1278
 
    <tr>
1279
 
        <td>online</td>
1280
 
        <td>node-event-html5</td>
1281
 
    </tr>
1282
 
    <tr>
1283
 
        <td>pagehide</td>
1284
 
        <td>node-event-html5</td>
1285
 
    </tr>
1286
 
    <tr>
1287
 
        <td>pageshow</td>
1288
 
        <td>node-event-html5</td>
1289
 
    </tr>
1290
 
    <tr>
1291
 
        <td>pause</td>
1292
 
        <td>node-event-html5</td>
1293
 
    </tr>
1294
 
    <tr>
1295
 
        <td>play</td>
1296
 
        <td>node-event-html5</td>
1297
 
    </tr>
1298
 
    <tr>
1299
 
        <td>playing</td>
1300
 
        <td>node-event-html5</td>
1301
 
    </tr>
1302
 
    <tr>
1303
 
        <td>popstate</td>
1304
 
        <td>node-event-html5 or history</td>
1305
 
    </tr>
1306
 
    <tr>
1307
 
        <td>progress</td>
1308
 
        <td>node-event-html5</td>
1309
 
    </tr>
1310
 
    <tr>
1311
 
        <td>ratechange</td>
1312
 
        <td>node-event-html5</td>
1313
 
    </tr>
1314
 
    <tr>
1315
 
        <td>readystatechange</td>
1316
 
        <td>node-event-html5</td>
1317
 
    </tr>
1318
 
    <tr>
1319
 
        <td>redo</td>
1320
 
        <td>node-event-html5</td>
1321
 
    </tr>
1322
 
    <tr>
1323
 
        <td>seeking</td>
1324
 
        <td>node-event-html5</td>
1325
 
    </tr>
1326
 
    <tr>
1327
 
        <td>seeked</td>
1328
 
        <td>node-event-html5</td>
1329
 
    </tr>
1330
 
    <tr>
1331
 
        <td>show</td>
1332
 
        <td>node-event-html5</td>
1333
 
    </tr>
1334
 
    <tr>
1335
 
        <td>stalled</td>
1336
 
        <td>node-event-html5</td>
1337
 
    </tr>
1338
 
    <tr>
1339
 
        <td>suspend</td>
1340
 
        <td>node-event-html5</td>
1341
 
    </tr>
1342
 
    <tr>
1343
 
        <td>timeupdate</td>
1344
 
        <td>node-event-html5</td>
1345
 
    </tr>
1346
 
    <tr>
1347
 
        <td>undo</td>
1348
 
        <td>node-event-html5</td>
1349
 
    </tr>
1350
 
    <tr>
1351
 
        <td>volumechange</td>
1352
 
        <td>node-event-html5</td>
1353
 
    </tr>
1354
 
    <tr>
1355
 
        <td>waiting</td>
1356
 
        <td>node-event-html5</td>
1357
 
    </tr>
1358
 
 
1359
 
    <tr>
1360
 
        <td>touchstart</td>
1361
 
        <td>event-touch</td>
1362
 
    </tr>
1363
 
    <tr>
1364
 
        <td>touchmove</td>
1365
 
        <td>event-touch</td>
1366
 
    </tr>
1367
 
    <tr>
1368
 
        <td>touchend</td>
1369
 
        <td>event-touch</td>
1370
 
    </tr>
1371
 
    <tr>
1372
 
        <td>touchcancel</td>
1373
 
        <td>event-touch</td>
1374
 
    </tr>
1375
 
    <tr>
1376
 
        <td>gesturestart</td>
1377
 
        <td>event-touch</td>
1378
 
    </tr>
1379
 
    <tr>
1380
 
        <td>gesturechange</td>
1381
 
        <td>event-touch</td>
1382
 
    </tr>
1383
 
    <tr>
1384
 
        <td>gestureend</td>
1385
 
        <td>event-touch</td>
1386
 
    </tr>
1387
 
 
1388
 
    <tr>
1389
 
        <td>transitionend or webkitTransitionEnd</td>
1390
 
        <td>transition-native</td>
1391
 
    </tr>
1392
 
</tbody>
1393
 
</table>
1394
 
</div>
1395
 
<script>
1396
 
YUI({ filter: 'raw' }).use('selector-css3', 'datatable-sort', function (Y) {
1397
 
    var data = [],
1398
 
        node = Y.one('#events');
1399
 
 
1400
 
    node.all('td:nth-of-type(1)').each(function (node, i) {
1401
 
        data.push({
1402
 
            Event: node.get('text'),
1403
 
            "Added By": node.next().get('text')
1404
 
        });
1405
 
    });
1406
 
 
1407
 
    node.empty().addClass('yui3-skin-sam');
1408
 
    new Y.DataTable.Base({
1409
 
        columnset: [
1410
 
            { key: 'Event', sortable: true },
1411
 
            { key: 'Added By', sortable: true }
1412
 
        ],
1413
 
        recordset: data
1414
 
    }).plug(Y.Plugin.DataTableSort).render(node);
1415
 
 
1416
 
});
1417
 
</script>
1418
 
 
1419
 
<h4 id="adding-to-the-dom-event-whitelist">Adding to the DOM event whitelist</h4>
1420
 
 
1421
 
<p>If you need to use an event that isn't included in this list, and not
1422
 
supplied by a synthetic event, you can expand the whitelist by adding the event
1423
 
names to the <code>Y.Node.DOM_EVENTS</code> object.</p>
1424
 
 
1425
 
<pre class="code prettyprint">&#x2F;&#x2F; Allow for subscription to some mostly cross-browser mutation events
1426
 
Y.mix(Y.Node.DOM_EVENTS, {
1427
 
    DOMNodeInserted: true,
1428
 
    DOMNodeRemoved: true,
1429
 
    DOMCharacterDataModified: true
1430
 
});</pre>
1431
 
 
1432
 
 
1433
 
<h2 id="facade-properties">Appendix B: EventFacade properties and methods</h2>
1434
 
 
1435
 
<h4 id="methods">Methods</h4>
1436
 
<dl>
1437
 
    <dt><code>e.preventDefault()</code></dt>
1438
 
        <dd>
1439
 
            Prevents the default action associated with the event. E.g. page
1440
 
            navigation from an &lt;a&gt;nchor <code>click</code> or form submission and
1441
 
            page reload from a %lt;form&gt; <code>submit</code>.
1442
 
        </dd>
1443
 
    <dt><code>e.stopPropagation()</code></dt>
1444
 
        <dd>
1445
 
            Stops the event from bubbling further up the DOM tree.  This does
1446
 
            not prevent the default action if there is one.  Subsequent event
1447
 
            subscribers will be executed.
1448
 
        </dd>
1449
 
    <dt><code>e.stopImmediatePropagation()</code></dt>
1450
 
        <dd>
1451
 
            Stops the event from bubbling further up the DOM tree.  This does
1452
 
            not prevent the default action if there is one.  Subsequent event
1453
 
            subscribers will NOT be executed.
1454
 
        </dd>
1455
 
    <dt><code>e.halt( [immediate=false] )</code></dt>
1456
 
        <dd>
1457
 
            Alias for <code>e.preventDefault(); e.stopPropagation();</code> or
1458
 
            <code>e.preventDefault(); e.stopImmediatePropagation();</code>, depending on
1459
 
            the <em>immediate</em> parameter.
1460
 
        </dd>
1461
 
</dl>
1462
 
 
1463
 
<h4 id="basics">Basics</h4>
1464
 
<dl>
1465
 
    <dt><code>e.type</code></dt>
1466
 
        <dd>
1467
 
            The name of the event. E.g. "click", "keyup", or "load".
1468
 
        </dd>
1469
 
 
1470
 
    <dt><code>e.target</code></dt>
1471
 
        <dd>
1472
 
            The Node instance that originated the event (see <a
1473
 
            href="delegation.html">the description of event delegation</a> for
1474
 
            reference)
1475
 
        </dd>
1476
 
    <dt><code>e.currentTarget</code></dt>
1477
 
        <dd>
1478
 
            The Node instance that subscribed to the event. In the case of
1479
 
            subscriptions from NodeLists, this is still the individual Node
1480
 
            instance (see <a href="#nodelist-this">When I subscribe to an event
1481
 
            from a NodeList, <code>this</code> is the NodeList...</a>).
1482
 
        </dd>
1483
 
    <dt><code>e.relatedTarget</code></dt>
1484
 
        <dd>
1485
 
            For <code>mouseover</code> events, this will be the Node instance of where the
1486
 
            mouse travelled <em>from</em>.  For <code>mouseout</code>, it will be the Node
1487
 
            that the mouse travelled <em>to</em>.
1488
 
        </dd>
1489
 
</dl>
1490
 
 
1491
 
<h4 id="keyboard-event-properties">Keyboard event properties</h4>
1492
 
    <dt><code>e.keyCode</code></dt>
1493
 
        <dd>
1494
 
            The unicode value of a non-character key in a <code>keypress</code> event or
1495
 
            any key in <code>keydown</code> or <code>keyup</code>.  See <a
1496
 
            href="https://developer.mozilla.org/en/DOM/event.keyCode">event.keyCode
1497
 
            on MDC</a>.
1498
 
        </dd>
1499
 
    <dt><code>e.charCode</code></dt>
1500
 
        <dd>
1501
 
            The Unicode value of a character key pressed during a keypress
1502
 
            event.  See <a
1503
 
            href="https://developer.mozilla.org/en/DOM/event.charCode">event.charCode
1504
 
            on MDC</a>.
1505
 
        </dd>
1506
 
    <dt><code>e.shiftKey</code></dt>
1507
 
        <dd>
1508
 
            <code>true</code> if the shift key was depressed during a key event.
1509
 
        </dd>
1510
 
    <dt><code>e.ctrlKey</code></dt>
1511
 
        <dd>
1512
 
            <code>true</code> if the control key was depressed during a key event.
1513
 
        </dd>
1514
 
    <dt><code>e.altKey</code></dt>
1515
 
        <dd>
1516
 
            <code>true</code> if the alt/option key was depressed during a key event.
1517
 
        </dd>
1518
 
    <dt><code>e.metaKey</code></dt>
1519
 
        <dd>
1520
 
            <code>true</code> if the "Windows" key on PCs or command key on Macs was
1521
 
            depressed during a key event.
1522
 
        </dd>
1523
 
</dl>
1524
 
 
1525
 
<h4 id="mouse-event-properties">Mouse event properties</h4>
1526
 
    <dt><code>e.button</code></dt>
1527
 
        <dd>
1528
 
            For <code>mouseup</code> events (<em>NOT <code>click</code> events</em>), indicates
1529
 
            which mouse button is pressed.<br>
1530
 
            <code>1</code> = left click, <code>2</code> = middle click, <code>3</code> = right click.
1531
 
        </dd>
1532
 
    <dt><code>e.which</code></dt>
1533
 
        <dd>
1534
 
            Alias for e.button.
1535
 
        </dd>
1536
 
 
1537
 
    <dt><code>e.pageX</code></dt>
1538
 
        <dd>
1539
 
            The horizontal coordinate of the event relative to whole document.
1540
 
        </dd>
1541
 
    <dt><code>e.pageY</code></dt>
1542
 
        <dd>
1543
 
            The vertical coordinate of the event relative to whole document.
1544
 
        </dd>
1545
 
    <dt><code>e.clientX</code></dt>
1546
 
        <dd>
1547
 
            The horizontal coordinate of the event relative to viewport,
1548
 
            regardless of scrolling.
1549
 
        </dd>
1550
 
    <dt><code>e.clientY</code></dt>
1551
 
        <dd>
1552
 
            The vertical coordinate of the event relative to viewport,
1553
 
            regardless of scrolling.
1554
 
        </dd>
1555
 
 
1556
 
    <dt>[<code>e.wheelDelta</code>]</dt>
1557
 
        <dd>
1558
 
            For <code>mousewheel</code> or <code>DOMMouseScroll</code> events, the pixel distance of
1559
 
            the scroll.
1560
 
        </dd>
1561
 
</dl>
1562
 
 
1563
 
<h4 id="touch-event-properties">Touch event properties</h4>
1564
 
<dl>
1565
 
    <dt>[<code>e.touches</code>]</dt>
1566
 
        <dd>
1567
 
            <p>
1568
 
                An array of <code>Touch</code> objects, where each <code>Touch</code> object represents a finger 
1569
 
                currently touching the surface (regardless of the target of the current event). 
1570
 
                For example, if you have two fingers on the surface, this array would have two 
1571
 
                <code>Touch</code> objects, one for each finger.
1572
 
            </p>
1573
 
            
1574
 
            <p>
1575
 
                The common set of properties currently on a <code>Touch</code> object, which can be 
1576
 
                relied up across environments, are <code>target</code>, <code>clientX</code>, <code>clientY</code>, <code>pageX</code>, 
1577
 
                <code>pageY</code>, <code>screenX</code>, <code>screenY</code> and <code>identifier</code>.
1578
 
            </p>    
1579
 
        </dd>
1580
 
    <dt>[<code>e.targetTouches</code>]</dt>
1581
 
        <dd>
1582
 
            <p>
1583
 
                An array of <code>Touch</code> objects for every point of contact that is touching the 
1584
 
                surface, and started on the element that is the target of the current event.
1585
 
            </p>
1586
 
        </dd>
1587
 
    <dt>[<code>e.changedTouches</code>]</dt>
1588
 
        <dd>
1589
 
            <p>
1590
 
                An array of <code>Touch</code> objects representing all touches that changed in this event.
1591
 
            </p>
1592
 
                
1593
 
            <p>
1594
 
               This property is most useful in <code>touchEnd</code> events, to identify the set of touches 
1595
 
               which were removed from the surface, which resulted in the firing of the event. 
1596
 
            </p>
1597
 
        </dd>
1598
 
</dl>
1599
 
 
1600
 
<h4 id="gesture-event-properties-currently-ios-specific">Gesture event properties (currently iOS specific)</h4>
1601
 
<p>These properties are unique to Webkit on iOS currently, and are provided on the event facade when listening for the iOS <code>gesturestart</code>, <code>gesturechange</code> and <code>gestureend</code> multi-touch events.</p>
1602
 
<dl>
1603
 
    <dt>[<code>e.scale</code>]</dt>
1604
 
        <dd>
1605
 
            See Apple's documentation for <a href="http://developer.apple.com/library/safari/documentation/UserExperience/Reference/GestureEventClassReference/GestureEvent/GestureEvent.html#//apple_ref/javascript/instp/GestureEvent/scale">scale</a>. 
1606
 
        </dd>
1607
 
    <dt>[<code>e.rotation</code>]</dt>
1608
 
        <dd>
1609
 
            See Apple's documentation for <a href="http://developer.apple.com/library/safari/documentation/UserExperience/Reference/GestureEventClassReference/GestureEvent/GestureEvent.html#//apple_ref/javascript/instp/GestureEvent/rotation">rotation</a>.
1610
 
        </dd>
1611
 
</dl>
1612
 
 
1613
 
<p>See the <a href="http://www.w3.org/TR/touch-events/">W3C Touch Events Specification</a>, derived from the Webkit model, for more details.</p>
1614
 
 
1615
 
<p>Synthetic events may add or modify event facade properties.  These should be included in the documentation for the specific synthetic event.</p>
1616
 
 
1617
 
<p>For more details, check out the <a
1618
 
href="https://developer.mozilla.org/en/DOM/event#Properties">MDC
1619
 
documentation</a>.</p>
1620
 
</div>
1621
 
        </div>
1622
 
 
1623
 
        <div id="sidebar" class="yui3-u">
1624
 
            
1625
 
                <div id="toc" class="sidebox">
1626
 
                    <div class="hd">
1627
 
                        <h2 class="no-toc">Table of Contents</h2>
1628
 
                    </div>
1629
 
 
1630
 
                    <div class="bd">
1631
 
                        <ul class="toc">
1632
 
<li>
1633
 
<a href="#getting-started">Getting Started</a>
1634
 
</li>
1635
 
<li>
1636
 
<a href="#the-basics">The Basics</a>
1637
 
<ul class="toc">
1638
 
<li>
1639
 
<a href="#listening-for-events">Listening for events</a>
1640
 
</li>
1641
 
<li>
1642
 
<a href="#the-callback-and-the-event-object">The Callback and the Event Object</a>
1643
 
</li>
1644
 
<li>
1645
 
<a href="#epreventdefault-and-estoppropagation"><code>e.preventDefault()</code> and <code>e.stopPropagation()</code></a>
1646
 
</li>
1647
 
<li>
1648
 
<a href="#detaching-subscriptions">Detaching subscriptions</a>
1649
 
</li>
1650
 
</ul>
1651
 
</li>
1652
 
<li>
1653
 
<a href="#modules">What to <code>use()</code></a>
1654
 
</li>
1655
 
<li>
1656
 
<a href="#delegation">Event Delegation</a>
1657
 
</li>
1658
 
<li>
1659
 
<a href="#more">More Event API Goodness</a>
1660
 
<ul class="toc">
1661
 
<li>
1662
 
<a href="#y-on">Subscribe from <code>Y</code></a>
1663
 
</li>
1664
 
<li>
1665
 
<a href="#once">One time subscriptions</a>
1666
 
</li>
1667
 
<li>
1668
 
<a href="#grouping-subscriptions">Grouping subscriptions</a>
1669
 
</li>
1670
 
<li>
1671
 
<a href="#extended-signature">Binding <code>this</code> and additional callback arguments</a>
1672
 
</li>
1673
 
<li>
1674
 
<a href="#detach-methods">More ways to clean up subscriptions</a>
1675
 
</li>
1676
 
</ul>
1677
 
</li>
1678
 
<li>
1679
 
<a href="#simulate">Simulate browser events</a>
1680
 
</li>
1681
 
<li>
1682
 
<a href="#synthetic-events">Synthetic Events</a>
1683
 
<ul class="toc">
1684
 
<li>
1685
 
<a href="#creating-dom-events">Creating DOM events</a>
1686
 
</li>
1687
 
</ul>
1688
 
</li>
1689
 
<li>
1690
 
<a href="#troubleshootingfaq">Troubleshooting/FAQ</a>
1691
 
<ul class="toc">
1692
 
<li>
1693
 
<a href="#function-reference">My callback is executing at the wrong time. What's going on?</a>
1694
 
</li>
1695
 
<li>
1696
 
<a href="#wrong-this">I'm getting an error in my callback that "<code>(some object) has no method (someMethodOnMyObject)</code>". What am I missing?</a>
1697
 
</li>
1698
 
<li>
1699
 
<a href="#which-events">What events can I subscribe to?</a>
1700
 
</li>
1701
 
<li>
1702
 
<a href="#why-on-no-chain">Why isn't on() chainable?</a>
1703
 
</li>
1704
 
<li>
1705
 
<a href="#y-on-vs-node-on">Why would I use <code>Y.on()</code> or <code>Y.delegate()</code> instead of <code>node.on()</code> and <code>node.delegate()</code>?</a>
1706
 
</li>
1707
 
<li>
1708
 
<a href="#after"><code>EventTarget</code> also provides an <code>after()</code> method. How does that work for DOM events?</a>
1709
 
</li>
1710
 
<li>
1711
 
<a href="#nodelist-this">When I subscribe to an event from a NodeList, <code>this</code> is the NodeList, not the individual Node.  What's up with that?</a>
1712
 
</li>
1713
 
<li>
1714
 
<a href="#nodelist-delegate">Where is <code>nodelist.delegate()</code>?</a>
1715
 
</li>
1716
 
</ul>
1717
 
</li>
1718
 
<li>
1719
 
<a href="#event-whitelist">Appendix A: Whitelisted DOM events</a>
1720
 
<ul class="toc">
1721
 
<li>
1722
 
<a href="#adding-to-the-dom-event-whitelist">Adding to the DOM event whitelist</a>
1723
 
</li>
1724
 
</ul>
1725
 
</li>
1726
 
<li>
1727
 
<a href="#facade-properties">Appendix B: EventFacade properties and methods</a>
1728
 
<ul class="toc">
1729
 
<li>
1730
 
<a href="#methods">Methods</a>
1731
 
</li>
1732
 
<li>
1733
 
<a href="#basics">Basics</a>
1734
 
</li>
1735
 
<li>
1736
 
<a href="#keyboard-event-properties">Keyboard event properties</a>
1737
 
</li>
1738
 
<li>
1739
 
<a href="#mouse-event-properties">Mouse event properties</a>
1740
 
</li>
1741
 
<li>
1742
 
<a href="#touch-event-properties">Touch event properties</a>
1743
 
</li>
1744
 
<li>
1745
 
<a href="#gesture-event-properties-currently-ios-specific">Gesture event properties (currently iOS specific)</a>
1746
 
</li>
1747
 
</ul>
1748
 
</li>
1749
 
</ul>
1750
 
                    </div>
1751
 
                </div>
1752
 
            
1753
 
 
1754
 
            
1755
 
                <div class="sidebox">
1756
 
                    <div class="hd">
1757
 
                        <h2 class="no-toc">Examples</h2>
1758
 
                    </div>
1759
 
 
1760
 
                    <div class="bd">
1761
 
                        <ul class="examples">
1762
 
                            
1763
 
                                
1764
 
                                    <li data-description="Use the Event Utility to attach simple DOM event handlers.">
1765
 
                                        <a href="basic-example.html">Simple DOM Events</a>
1766
 
                                    </li>
1767
 
                                
1768
 
                            
1769
 
                                
1770
 
                                    <li data-description="Using the synthetic event API to create a DOM event that fires in response to arrow keys being pressed.">
1771
 
                                        <a href="synth-example.html">Creating an Arrow Event for DOM Subscription</a>
1772
 
                                    </li>
1773
 
                                
1774
 
                            
1775
 
                                
1776
 
                                    <li data-description="Supporting cross-device swipe gestures, using the event-move gesture events">
1777
 
                                        <a href="swipe-example.html">Supporting A Swipe Left Gesture</a>
1778
 
                                    </li>
1779
 
                                
1780
 
                            
1781
 
                                
1782
 
                            
1783
 
                                
1784
 
                            
1785
 
                                
1786
 
                            
1787
 
                                
1788
 
                            
1789
 
                                
1790
 
                            
1791
 
                        </ul>
1792
 
                    </div>
1793
 
                </div>
1794
 
            
1795
 
 
1796
 
            
1797
 
                <div class="sidebox">
1798
 
                    <div class="hd">
1799
 
                        <h2 class="no-toc">Examples That Use This Component</h2>
1800
 
                    </div>
1801
 
 
1802
 
                    <div class="bd">
1803
 
                        <ul class="examples">
1804
 
                            
1805
 
                                
1806
 
                            
1807
 
                                
1808
 
                            
1809
 
                                
1810
 
                            
1811
 
                                
1812
 
                                    <li data-description="Shows how to extend the base widget class, to create your own Widgets.">
1813
 
                                        <a href="../widget/widget-extend.html">Extending the Base Widget Class</a>
1814
 
                                    </li>
1815
 
                                
1816
 
                            
1817
 
                                
1818
 
                                    <li data-description="Creating an accessible menu button using the Focus Manager Node Plugin, Event&#x27;s delegation support and mouseenter event, along with the Overlay widget and Node&#x27;s support for the WAI-ARIA Roles and States.">
1819
 
                                        <a href="../node-focusmanager/node-focusmanager-3.html">Accessible Menu Button</a>
1820
 
                                    </li>
1821
 
                                
1822
 
                            
1823
 
                                
1824
 
                                    <li data-description="Use IO to request data over HTTP.">
1825
 
                                        <a href="../io/get.html">HTTP GET to request data</a>
1826
 
                                    </li>
1827
 
                                
1828
 
                            
1829
 
                                
1830
 
                                    <li data-description="Example Photo Browser application.">
1831
 
                                        <a href="../dd/photo-browser.html">Photo Browser</a>
1832
 
                                    </li>
1833
 
                                
1834
 
                            
1835
 
                                
1836
 
                                    <li data-description="Portal style example using Drag &amp; Drop Event Bubbling and Animation.">
1837
 
                                        <a href="../dd/portal-drag.html">Portal Style Example</a>
1838
 
                                    </li>
1839
 
                                
1840
 
                            
1841
 
                        </ul>
1842
 
                    </div>
1843
 
                </div>
1844
 
            
1845
 
        </div>
1846
 
    </div>
1847
 
</div>
1848
 
 
1849
 
<script src="../assets/vendor/prettify/prettify-min.js"></script>
1850
 
<script>prettyPrint();</script>
1851
 
 
1852
 
</body>
1853
 
</html>