This example will illustrate how to use the synthetic event creation
API. We'll create an arrow event that fires in response
to the user pressing the arrow keys (up, down, left, right) and adds a
direction property to the generated event.
Subscribing to this new event will look like this:
node.on("arrow", onArrowHandler);
Support will also be added for delegation, allowing a single subscriber from a node higher up the DOM tree, to listen for the new event emanating from its descendant elements.
containerNode.delegate("arrow", onArrowHandler, ".robot");
Step 1. to the arrow event.
Step 2. Click on a robot and move it around with the arrow keys.
on, fire, and detach
The three interesting moments in the lifecycle of a DOM event subscription are
- The event is subscribed to
- The event is fired
- The event is unsubscribed from
Create a new synthetic DOM event with `Y.Event.define( name,
config )`. Define the implementation logic for the
on and detach moments in the configuration.
Typically the condition triggering the event firing is set up in the
on phase.
Y.Event.define("arrow", {
on: function (node, sub, notifier) {
// what happens when a subscription is made
// if (condition) {
notifier.fire(); // subscribers executed
// }
},
detach: function (node, sub, notifier) {
// what happens when a subscription is removed
}
});
In the case of arrow handling, the trigger is simply a key event with a
keyCode between 37 and 40. There are a few browser quirks with arrow
handling that warrant listening to keydown for some browsers and
keypress for others, so we'll take care of that transparently for arrow
subscribers.
Y.Event.define("hover", {
on: function (node, sub, notifier) {
var directions = {
37: 'left',
38: 'up',
39: 'right',
40: 'down'
};
// Webkit and IE repeat keydown when you hold down arrow keys.
// Opera links keypress to page scroll; others keydown.
// Firefox prevents page scroll via preventDefault() on either
// keydown or keypress.
// Bummer to sniff, but can't test the repeating behavior, and a
// feature test for the scrolling would more than double the code size.
var eventName = (Y.UA.webkit || Y.UA.ie) ? 'keydown' : 'keypress';
// To make detaching the associated DOM event easy, store the detach
// handle from the DOM subscription on the synthethic subscription
// object.
sub._detacher = node.on(eventName, function (e) {
// Only notify subscribers if one of the arrow keys was pressed
if (directions[e.keyCode]) {
// Add the extra property
e.direction = directions[e.keyCode];
// Firing the notifier event executes the arrow subscribers
// Pass along the key event, which will be renamed "arrow"
notifier.fire(e);
}
});
},
detach: function (node, sub, notifier) {
// Detach the key event subscription using the stored detach handle
sub._detacher.detach();
}
} );
Add Delegation Support
Since the arrow event is simply a filtered keydown or keypress event,
no special handling needs to be done for delegate subscriptions. We will
extract the key event handler and use it for both on("arrow", ...) and
delegate("arrow", ...) subscriptions.
Y.Event.define("arrow", {
// Webkit and IE repeat keydown when you hold down arrow keys.
// Opera links keypress to page scroll; others keydown.
// Firefox prevents page scroll via preventDefault() on either
// keydown or keypress.
_event: (Y.UA.webkit || Y.UA.ie) ? 'keydown' : 'keypress',
_keys: {
'37': 'left',
'38': 'up',
'39': 'right',
'40': 'down'
},
_keyHandler: function (e, notifier) {
if (this._keys[e.keyCode]) {
e.direction = this._keys[e.keyCode];
notifier.fire(e);
}
},
on: function (node, sub, notifier) {
// Use the extended subscription signature to set the 'this' object
// in the callback and pass the notifier as a second parameter to
// _keyHandler
sub._detacher = node.on(this._event, this._keyHandler,
this, notifier);
},
detach: function (node, sub, notifier) {
sub._detacher.detach();
},
// Note the delegate handler receives a fourth parameter, the filter
// passed (e.g.) container.delegate('click', callback, '.HERE');
// The filter could be either a string or a function.
delegate: function (node, sub, notifier, filter) {
sub._delegateDetacher = node.delegate(this._event, this._keyHandler,
filter, this, notifier);
},
// Delegate uses a separate detach function to facilitate undoing more
// complex wiring created in the delegate logic above. Not needed here.
detachDelegate: function (node, sub, notifier) {
sub._delegateDetacher.detach();
}
});
Use it
Subscribe to the new event or detach the event as you would any other DOM event.
function move(e) {
// to prevent page scrolling
e.preventDefault();
// See full code listing to show the data set up
var xy = this.getData();
switch (e.direction) {
case 'up': xy.y -= 10; break;
case 'down': xy.y += 10; break;
case 'left': xy.x -= 10; break;
case 'right': xy.x += 10; break;
}
this.transition({
top : (xy.y + 'px'),
left: (xy.x + 'px'),
duration: .2
});
}
// Subscribe using node.on("arrow", ...);
Y.one("#A").on("arrow", move),
Y.one("#B").on("arrow", move)
// OR using container.delegate("arrow", ...);
subs = Y.one('#demo').delegate('arrow', move, '.robot');
Bonus Step: to the Gallery!
Synthetic events are perfect candidates for Gallery modules. There are a number already hosted there, and there are plenty of UI interaction patterns that would benefit from being encapsulated in synthetic events.
The arrow event in this example is also
in the gallery,
but with additional functionality. Check out
its source
to see what you can do with synthetic events.
Full Code Listing
<div id="demo">
<p>Step 1. <button type="button" id="attach" tabindex="1">subscribe</button> to the <code>arrow</code> event.<br>
<input type="checkbox" id="delegate" value="1" tabindex="1">
<label for="delegate">Use a delegated subscription</label></p>
<p>Step 2. Click on a robot and move it around with the arrow keys.</p>
<div id="homebase">
<div id="A" class="robot" tabindex="2"></div>
<div id="B" class="robot" tabindex="3"></div>
</div>
<button type="button" id="detach" tabindex="4">Detach subscriptions</button>
</div>
<script>
YUI().use('node', 'event-synthetic', 'transition', function (Y) {
Y.Event.define("arrow", {
// Webkit and IE repeat keydown when you hold down arrow keys.
// Opera links keypress to page scroll; others keydown.
// Firefox prevents page scroll via preventDefault() on either
// keydown or keypress.
_event: (Y.UA.webkit || Y.UA.ie) ? 'keydown' : 'keypress',
_keys: {
'37': 'left',
'38': 'up',
'39': 'right',
'40': 'down'
},
_keyHandler: function (e, notifier) {
if (this._keys[e.keyCode]) {
e.direction = this._keys[e.keyCode];
notifier.fire(e);
}
},
on: function (node, sub, notifier) {
sub._detacher = node.on(this._event, this._keyHandler,
this, notifier);
},
detach: function (node, sub, notifier) {
sub._detacher.detach();
},
delegate: function (node, sub, notifier, filter) {
sub._delegateDetacher = node.delegate(this._event, this._keyHandler,
filter, this, notifier);
},
detachDelegate: function (node, sub, notifier) {
sub._delegateDetacher.detach();
}
});
var robotA = Y.one('#A'),
robotB = Y.one('#B'),
subs;
robotA.setData('x', parseInt(robotA.getStyle('left'), 10));
robotA.setData('y', parseInt(robotA.getStyle('top'), 10));
robotB.setData('x', parseInt(robotB.getStyle('left'), 10));
robotB.setData('y', parseInt(robotB.getStyle('top'), 10));
function move(e) {
// to prevent page scrolling
e.preventDefault();
var xy = this.getData();
switch (e.direction) {
case 'up': xy.y -= 10; break;
case 'down': xy.y += 10; break;
case 'left': xy.x -= 10; break;
case 'right': xy.x += 10; break;
}
this.transition({
top : (xy.y + 'px'),
left: (xy.x + 'px'),
duration: .2
});
}
function detachSubs() {
if (subs) {
subs.detach();
subs = null;
}
}
Y.one("#attach").on("click", function (e) {
detachSubs();
if (Y.one("#delegate").get('checked')) {
subs = Y.one('#demo').delegate('arrow', move, '.robot');
} else {
subs = new Y.EventHandle([
robotA.on("arrow", move),
robotB.on("arrow", move)
]);
}
});
Y.one("#detach").on("click", detachSubs);
});
</script>