The event-outside module adds a suite of
events based on activity occuring outside the subscribed
elements. For example, the "clickoutside" event will fire only if a click
occurred on an element other than the Node subscribed or one of
its descendants.
The module also adds a Y.Event.defineOutside(...) method to create additional outside events.
This module was contributed by Brett Stimmerman, inspired by Ben Alman's Outside Events jQuery plugin.
Not me. Those other elements
It's a common UX pattern to close popups or trigger save or cancel actions when users do something in another area of a web page. This family of events makes setting up that behavior easy.
node.on('clickoutside', function () {
this.hide('fadeOut');
});
survey.on('keyupoutside', heyYoureNotDoneYet);
// hide the overlay if the page focus moves somewhere outside the overlay's
// content area.
overlay.get('boundingBox').on('focusoutside', overlay.hide, overlay);
How they work
When an outside event subscription is made on an element, the actual
subscription created is a document level subscription for the corresponding
DOM event. When a triggering event occurs on the page and bubbles up to the
document, its e.target is compared to the outside event subscriber. If the
event originated from an element outside the subscriber, the outside event
subscribers are executed.
An originating target is considered outside the subscriber if it is not the subscriber itself or any of the subscriber's descendants.
*outside
The naming convention for outside events is <event>outside.
The module creates the following events by default:
-
mousedownoutsidemouseupoutsidemouseoveroutsidemouseoutoutsidemousemoveoutside
-
clickoutsidedblclickoutsidekeydownoutsidekeyupoutsidekeypressoutside
-
focusoutsidebluroutsidechangeoutsideselectoutsidesubmitoutside
Create more outside events
Use the module's Y.Event.defineOutside( triggeringEvent, [alternateName] ) method to create more outside
events.
// Create a `touchstartoutside` event
Y.Event.defineOutside('touchstart');
// Create an outside event for another synthetic event and give it
// a different name.
Y.Event.defineOutside('tripleclick', 'omgletmeout');
// would have been tripleclickoutside
gooeymess.on('omgletmeout', okYouCanGo);
Caveats
Outside events require DOM events to bubble to the document so the following caveats apply to their use:
-
Separate subscriptions for the triggering event added to any element
below the
documentwill execute before the outside event. -
If a subcriber from #1 calls
e.stopPropagation(), the outside event won't fire. - "outside" is determined by DOM hierarchy, not visual placement of an element, so if a child element of the outside subscriber is placed elsewhere on the page, clicking on that child will not trigger the outside event.
-
Some DOM events do not bubble, and some (e.g.
submitandreset) bubble only in certain browsers. Unless a workaround synthetic event such asevent-focusis in place, outside versions of these events won't fire.