Outside Events for YUI 3

21 April 2010

Outside Events is a spankin’ new YUI 3 Gallery module that allows elements to subscribe to DOM events that occur outside of them. An event occurs outside the subscriber if the target it is not the subscriber itself, or any of the subscriber’s ancestors. Many common outside events are pre-defined and ready to use, and defining new outside events is a cinch.

Outside Events is tiny weighing in at 475 bytes minified and gzipped. It’s also hosted on the same CDN as YUI 3, so including it in your projects is simple and fast.

YUI({
  // Last Gallery Build of this module
  gallery: 'gallery-2010.04.21-21-51'
}).use('gallery-outside-events', function(Y) {
  // Outside events are ready to go!
});

Subscribe to outside events just like any other DOM event. Here is the pre-defined clickoutside event in action.

Y.one('#dialog').on('clickoutside', function (e) {
  this.addClass('hidden');
});

Let’s say you’ve defined a sweet new swipe event with the YUI 3 Synthetic DOM Event API. Defining swipeoutside is easy.

Y.Event.defineOutside('swipe');

New outside events are named <event>outside by default. You can optionally give new outside events a custom name.

Y.Event.defineOutside('swipe', 'outerswipe');
Y.one('#foo').on('outerswipe', ... );

Outside event handlers receive the originating DOM event object as an argument.

Y.one('#foo').on('keyupoutside', function (e) {
  var tag  = e.target.get('tagName'),
      text = 'A keyup event occured on a ' + tag + ' element ' +
             'outside of #foo';

  console.log(text);
});

To learn more about Outside Events and view the list of pre-defined outside events, have a look at the YUI Library page and the README, which goes into detail about a few general caveats and specific known issues with IE 6, 7 and 8 you should be aware of.