synths.mustache revision 2e7441169df0fcc324f2d44947beba7d237f5a37
8648721e29bb657dd5c5ff20f03e86fe50628ce6Tripp<div class="intro">
8648721e29bb657dd5c5ff20f03e86fe50628ce6Tripp <p>Synthetic events are usually named abstractions that bind to existing
8648721e29bb657dd5c5ff20f03e86fe50628ce6Tripp DOM events to monitor user actions for specific patterns. However, at
8648721e29bb657dd5c5ff20f03e86fe50628ce6Tripp heart they are no more than a set of callbacks executed in response to
a75ebc38c1de401b679953a9b87bd323f0f48d02Tripp various triggering methods in the DOM event system.</p>
8648721e29bb657dd5c5ff20f03e86fe50628ce6Tripp <p>You can do all sorts of things with synthetic events, including:</p>
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp redefine native DOM events that behave inconsistently across
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp browsers (e.g. <a href="focus.html">`focus` and `blur`</a>)
8648721e29bb657dd5c5ff20f03e86fe50628ce6Tripp provide abstract events that attach to different DOM events based on
8209f3939e32e0e5bde64192267fdaf9db6f4fbcTripp the environment (e.g. <a href="touch.html#move">`gesturemovestart`
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp and family</a>)
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp create events with different subscription signatures (e.g.
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp <a href="hover.html">`hover`</a> or
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp <a href="touch.html#move">`gesturemovestart`</a>)
823ddbefd8e5a9793fd80368647b6572a93f06e9Tripp create configurable events that only execute subscribers when
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp criteria passed during subscription are met (e.g.
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp <a href="touch.html#flick">`flick`</a> or
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp <a href="key.html">`key`</a>)
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp create events that encapsulate common UX patterns (e.g.
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp <a href="outside.html">`clickoutside`</a>)
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp create fun little easter eggs (e.g. <a
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp href="http://yuilibrary.com/gallery/show/event-konami">`konami`</a>)
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp <li>and more...</li>
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp<h2>The hooks</h2>
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp<p>Synthetic events hook into the subscription binding and unbinding methods. Specifically:</p>
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp <li>`node.on("eventName", ...)`, `Y.on("eventName", ...)`, <a href="index.html#one-time-subscriptions">and family</a></li>
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp <li>`node.delegate("eventName", ...)` or `Y.delegate("eventName", ...)`</li>
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp <li>`node.detach(...)` or `subscription.detach()`</li>
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp<p>With the exception of a separate `detachDelegate()` method, the names used when defining synthetic events are the same as these basic methods.</p>
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTrippY.Event.define("tripleclick", {
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp on: function (node, subscription, notifier) {
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp // called in response to individual subscriptions
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp delegate: function (node, subscription, notifier, filter) {
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp // called in response to delegate subscriptions
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp detach: function (node, subscription, notifier) {
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp // called when individual subscriptions are detached in any way
823ddbefd8e5a9793fd80368647b6572a93f06e9Tripp detachDelegate: function (node, subscription, notifier) {
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp // called when delegate subscriptions are detached in any way
562568c870b1109f8b462727a15d214d71d892afTripp<h2>Subscriptions and Notifiers</h2>
562568c870b1109f8b462727a15d214d71d892afTripp<p>In addition to the subscribing Node, each method receives a
562568c870b1109f8b462727a15d214d71d892afTripp<em>subscription</em> and a <em>notifier</em>. Use the <em>subscription</em>
4a55a0fcc3d0a6cc7557769aea54169614ffbf71Trippto store event handles or other data that may be needed by another method. Use
823ddbefd8e5a9793fd80368647b6572a93f06e9Trippthe <em>notifier</em> to signal that subscribed callbacks should be
823ddbefd8e5a9793fd80368647b6572a93f06e9Trippexecuted.</p>
ee60e5568372ba636aa7eac094d936deadf1ef83TrippY.Event.define("tripleclick", {
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp on: function (node, subscription, notifier) {
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp var count = 0;
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp subscription._handle = node.on("click", function (e) {
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp if (++count === 3) {
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp // Call notifier.fire(e) to execute subscribers.
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp // Pass the triggering event facade to fire()
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp detach: function (node, subscription, notifier) {
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp delegate: function (node, subscription, notifier, filter) { ... },
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp detachDelegate: function (node, subscription, notifier) { ... }
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp<p>Subscribers to the synthetic event should receive a `DOMEventFacade`. The
ee60e5568372ba636aa7eac094d936deadf1ef83Trippeasiest way to provide one is to pass the triggering DOM event's facade to
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp`notifier.fire(e)`. The facade's `e.type` will be updated to the name of the
4a44e886072efd2f75d7eca199ba3327a3cdeedaTrippsynth. You will also have the opportunity to add extra data to the event
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTrippbefore dispatching to the subscription callbacks.</p>
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTrippY.Event.define('multiclick', {
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp on: function (node, sub, notifier) {
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp var count = 0,
4a55a0fcc3d0a6cc7557769aea54169614ffbf71Tripp sub._handle = node.on('click', function (e) {
4a55a0fcc3d0a6cc7557769aea54169614ffbf71Tripp if (timer) {
4a55a0fcc3d0a6cc7557769aea54169614ffbf71Tripp timer = Y.later(200, null, function () {
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp notifier.fire(e); // subscribers will get e with e.clicks
8648721e29bb657dd5c5ff20f03e86fe50628ce6Tripp<h2>Delegation support</h2>
8209f3939e32e0e5bde64192267fdaf9db6f4fbcTripp<p>The `delegate` function implementation takes an extra argument, the `filter` that was passed <code>node.delegate(type, callback, <em>HERE</em>)</code>. It's your responsibility to make sense of this filter for your event.</p>
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp<p>Typically, it is just passed along to a `node.delegate(...)` call against another event, deferring the filtration to the core `delegate()` method.</p>
82d0cf8c731b23f6a2fbb31e3e696e629444363eTrippY.Event.define("tripleclick", {
82d0cf8c731b23f6a2fbb31e3e696e629444363eTripp on: function (node, subscription, notifier) { ... },
82d0cf8c731b23f6a2fbb31e3e696e629444363eTripp detach: function (node, subscription, notifier) { ... },
82d0cf8c731b23f6a2fbb31e3e696e629444363eTripp delegate: function (node, subscription, notifier, filter) {
82d0cf8c731b23f6a2fbb31e3e696e629444363eTripp var activeNode = null,
cc21b565833307c2b0b06deb4e3ab22c2a94be3eTripp subscription._handle = node.delegate("click", function (e) {
cc21b565833307c2b0b06deb4e3ab22c2a94be3eTripp if (timer) {
cc21b565833307c2b0b06deb4e3ab22c2a94be3eTripp if (this !== activeNode) {
82d0cf8c731b23f6a2fbb31e3e696e629444363eTripp activeNode = this;
8209f3939e32e0e5bde64192267fdaf9db6f4fbcTripp if (++count === 3) {
8209f3939e32e0e5bde64192267fdaf9db6f4fbcTripp // Call notifier.fire(e) just as with `on`
8209f3939e32e0e5bde64192267fdaf9db6f4fbcTripp timer = Y.later(300, null, function () {
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp }, filter);
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp detachDelegate: function (node, subscription, notifier) {
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp<h2>Extra arguments</h2>
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp<p>Supply a `processArgs` method in the event definition to accept additional
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripparguments. If this method is supplied, it</p>
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp <strong>MUST</strong> remove the extra arguments from the arg array
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp that is passed in, and
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp <strong>SHOULD</strong> return the extra data relevant to the
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp subscription.
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp<p>The same `processArgs` method is used by both `on` and `delegate`. A second
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTrippargument to `processArgs` indicates that the subscription is being made through
82d0cf8c731b23f6a2fbb31e3e696e629444363eTripp`delegate`. Because `node.on(...)` and `node.delegate(...)` signatures differ,
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTrippit is easiest to expect custom arguments starting from at index 3 of the
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTrippsubscription arguments array.</p>
8648721e29bb657dd5c5ff20f03e86fe50628ce6TrippY.Event.define('multiclick', {
8648721e29bb657dd5c5ff20f03e86fe50628ce6Tripp processArgs: function (args, isDelegate) {
8648721e29bb657dd5c5ff20f03e86fe50628ce6Tripp // The args list will look like this coming in:
8648721e29bb657dd5c5ff20f03e86fe50628ce6Tripp // [ type, callback, node, (extras...), [filter], thisObj, arg0...argN ]
8648721e29bb657dd5c5ff20f03e86fe50628ce6Tripp var extras = args[3];
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp // The args array going out MUST look like this:
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp // [ type, callback, node, [filter], thisObj, arg0...argN ]
11174dd4aa7b6152555e21e3e0a5a511e058415bTripp // this will be assigned to subscription._extras;
11174dd4aa7b6152555e21e3e0a5a511e058415bTripp return extras;
11174dd4aa7b6152555e21e3e0a5a511e058415bTripp on: function (node, sub, notifier) {
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp var clicks = 0,
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp // data returned from processArgs is available at sub._extras
11174dd4aa7b6152555e21e3e0a5a511e058415bTripp sub._handle = node.on('click', function (e) {
11174dd4aa7b6152555e21e3e0a5a511e058415bTripp if (timer) {
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp if (++clicks === max) {
8209f3939e32e0e5bde64192267fdaf9db6f4fbcTripp timer = Y.later(200, null, function () {
11174dd4aa7b6152555e21e3e0a5a511e058415bTripp if (clicks > min) {
11174dd4aa7b6152555e21e3e0a5a511e058415bTripp// Usage would look like this (extra config object as third arg)
11174dd4aa7b6152555e21e3e0a5a511e058415bTripp minClicks: 5,
11174dd4aa7b6152555e21e3e0a5a511e058415bTripp maxClicks: 8
11174dd4aa7b6152555e21e3e0a5a511e058415bTripp// extra args are supplied before the delegate filter
8209f3939e32e0e5bde64192267fdaf9db6f4fbcTrippcontainer.delegate('multiclick', doSomething, {
11174dd4aa7b6152555e21e3e0a5a511e058415bTripp minClicks: 3,
8209f3939e32e0e5bde64192267fdaf9db6f4fbcTripp maxClicks: 55
11174dd4aa7b6152555e21e3e0a5a511e058415bTripp}, '.clickable');
11174dd4aa7b6152555e21e3e0a5a511e058415bTripp<h2>Tips and Tricks</h2>
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp<h4>Alias `delegate` to `on` and `detachDelegate` to `detach`</h4>
e393eced613f9b4a5fb6bdd461d0e0bf5064d5ecTripp<h4>Don't store state in `node.setData(...)` for `delegate`</h4>