Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/trentmwillis/ember-singularity
Unified event handling in Ember
https://github.com/trentmwillis/ember-singularity
dom-events dom-listeners ember ember-addon
Last synced: 14 days ago
JSON representation
Unified event handling in Ember
- Host: GitHub
- URL: https://github.com/trentmwillis/ember-singularity
- Owner: trentmwillis
- License: mit
- Created: 2015-08-07T21:42:25.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2022-12-13T20:36:31.000Z (about 2 years ago)
- Last Synced: 2025-01-09T08:32:57.698Z (18 days ago)
- Topics: dom-events, dom-listeners, ember, ember-addon
- Language: JavaScript
- Size: 4.61 MB
- Stars: 35
- Watchers: 5
- Forks: 11
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Ember Singularity
[](https://badge.fury.io/js/ember-singularity)
[](https://github.com/trentmwillis/ember-singularity/actions/)
Ember Singularity integrates a [Unified Event Handler](https://github.com/trentmwillis/ember-singularity/blob/master/app/services/unified-event-handler.js)
service to help control DOM event listeners by taking normal DOM events and
binding them to Ember Events that are triggered by a singular DOM listener.
In other words, this means that instead of having multiple listeners for a
single DOM event, you have one listener for a single DOM event that then
triggers multiple callbacks via Ember events.
Why do this? There are two primary motivations:
1. **Centralize control of DOM listeners**: this has numerous benefits. Primary
would be that it reduces the risk of memory leaks and allows optimization of
the number of handlers being used. It allows an easy choke point for
throttling "spammy" events. Essentially greater and easier control over
DOM events not already handled by Ember.
2. **Leverage Ember's event system**: this helps ensure events that cause
modifications to application state or the DOM get batched into the Ember
run-loop. Helping reduce churn (especially in cases such as scrolling) is a
huge win when trying to make performant applications.
## Usage
The available interface for the `UnifiedEventHandler` is pretty simple and only
contains 3 available methods. That said, it is recommended that you abstract
away any usage of the service via mixins or base-level components; this helps
ensure 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. The
`target` and `eventName` are expected to be of type `string` and `callback` is a
function. The `callback` will receive the original event. Here's an example:
```js
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 the
same as were used to register the handler. Here's an example:
```js
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. As
of version 1.1.0, after you register a handler it's Ember event will be of the
form `.`. This probably won't be used often, but is
available for flexibility in testing, debugging, and extending functionality.
Here's a final example of the total API:
```js
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);
})
});
```