Version 3.17.2

Outside Events

Jump to Table of Contents

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:

    • mousedownoutside
    • mouseupoutside
    • mouseoveroutside
    • mouseoutoutside
    • mousemoveoutside
    • clickoutside
    • dblclickoutside
    • keydownoutside
    • keyupoutside
    • keypressoutside
    • focusoutside
    • bluroutside
    • changeoutside
    • selectoutside
    • submitoutside

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:

  1. Separate subscriptions for the triggering event added to any element below the document will execute before the outside event.
  2. If a subcriber from #1 calls e.stopPropagation(), the outside event won't fire.
  3. "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.
  4. Some DOM events do not bubble, and some (e.g. submit and reset) bubble only in certain browsers. Unless a workaround synthetic event such as event-focus is in place, outside versions of these events won't fire.