Ember Singularity

Ember Singularity integrates a Unified Event Handlerservice to help control DOM event listeners by taking normal DOM events andbinding them to Ember Events that are triggered by a singular DOM listener.

In other words, this means that instead of having multiple listeners for asingle DOM event, you have one listener for a single DOM event that thentriggers multiple callbacks via Ember events.

Why do this? There are two primary motivations:

1. Centralize control of DOM listeners: this has numerous benefits. Primarywould be that it reduces the risk of memory leaks and allows optimization ofthe number of handlers being used. It allows an easy choke point forthrottling "spammy" events. Essentially greater and easier control overDOM events not already handled by Ember.
2. Leverage Ember's event system: this helps ensure events that causemodifications to application state or the DOM get batched into the Emberrun-loop. Helping reduce churn (especially in cases such as scrolling) is ahuge win when trying to make performant applications.

Usage

The available interface for the UnifiedEventHandler is pretty simple and onlycontains 3 available methods. That said, it is recommended that you abstractaway any usage of the service via mixins or base-level components; this helpsensure the benefits described in the above motivations.

register(target, eventName, callback)

This registers a callback to be tied to a specific target and event type. Thetarget and eventName are expected to be of type string and callback is afunction. The callback will receive the original event. Here's an example:

let ScrollMixin = Ember.Mixin.extend({
  unifiedEventHandler: Ember.inject.service(),

  _registerScrollCallback: Ember.on('init', function() {
    this.get('unifiedEventHandler').register('window', 'scroll', (event) => {
      console.log('scrolled!');
      console.log(event);
    });
  })
});

unregister(target, eventName, callback)

This is the exact opposite of register() and expects the arguments to be thesame as were used to register the handler. Here's an example:

let ScrollMixin = Ember.Mixin.extend({
  unifiedEventHandler: Ember.inject.service(),

  scroll() { console.log('scrolled!'); },

  _registerScrollCallback: Ember.on('init', function() {
    this.get('unifiedEventHandler').register('window', 'scroll', this.scroll);
  }),

  _unregisterScrollCallback: Ember.on('willDestroy', function() {
    this.get('unifiedEventHandler').unregister('window', 'scroll', this.scroll);
  })
});

triggerEvent(eventName)

This allows you to trigger the Ember event that your callback got bound to. Asof version 1.1.0, after you register a handler it's Ember event will be of theform <event-name>.<target>. This probably won't be used often, but isavailable for flexibility in testing, debugging, and extending functionality.Here's a final example of the total API:

let ScrollMixin = Ember.Mixin.extend({
  unifiedEventHandler: Ember.inject.service(),

  scroll() { console.log('scrolled!'); },

  triggerScroll() {
    this.get('unifiedEventHandler').triggerEvent('window.scroll');
  },

  _registerScrollCallback: Ember.on('init', function() {
    this.get('unifiedEventHandler').register('window', 'scroll', this.scroll);
  }),

  _unregisterScrollCallback: Ember.on('willDestroy', function() {
    this.get('unifiedEventHandler').unregister('window', 'scroll', this.scroll);
  })
});