Handle Events in the Browser
Manages events listeners in the browser. A lightweight library for
adding, removing and getting event listeners to DOM Elements.
Content
Getting started
To include this library into your package manager withnpm or yarn
```shell
with npm
$ npm install handle-events --save
with yarn
$ yarn add handle-events
```
☗ Back to Index
Including the library
handle-events can be included directly from a CDN in your site:
```html
```
In the above case, the library will be included as global object
in the browser under the name of jsu (JavaScript-Utils),
wherein, if that namespace exists, it will be extended, otherwise
a new jsu object will be created.
As this library is built as UMD (Universal Module Definition), it
can be included from module loaders such as CommonJS, ES2015 Imports
or AMD RequireJS.
CommonJS
```javascript var jsu = require('handle-events'); ```ES2015 Imports
```javascript import jsu from 'handle-events'; ```AMD
```javascript // using RequireJS requirejs.config({ paths: {// remove the extension .js'handle-events': '<PATH>/handle-events.min'API
addEventListener(node, eventns, listener, capture)
Returnsvoid
```javascript
addEventListener(node: Element, eventns: String, listener: Function, capture: Boolean) : void
```
Attaches an event-handler to a DOM element. You can set a namespace to
the event by appending a dot . to the event name.
It receives the following arguments:
- node
Element: DOM Element to which the event handler is attached
- eventns
String: name of the event (with .namespace) to register
- listener
Function: the function which receives the event notification
- capture
Boolean: if the event is activated at the beginning (defaultfalse)
triggered ${e.type}.tooltip);
jsu.addEventListener(title, 'mouseover.tooltip', onMouseOver);
// add an anonymous event handler (without namespace)
jsu.addEventListener(title, 'click', (e) => {
console.log(triggered ${e.type});
});
```
Events can be activated at two occasions: At the beginning ("capture") by
setting capture = true, and at the end ("bubble") by default.
Events are executed in the order of how they're defined.
Say, you define 4 event listeners:
```javascript
jsu.addEventListener(document.body, "click.a1", (e) => alert(1));
jsu.addEventListener(document.body, "click.a2", (e) => alert(2), true);
jsu.addEventListener(document.body, "click.a3", (e) => alert(3), false);
jsu.addEventListener(document.body, "click.a4", (e) => alert(4), true);
```
The alert boxes will pop up in this order:
2: defined first, usingcapture = true
4: defined second, usingcapture = true
1: first handler defined without settingcapture
3: second handler defined withcapture = false
delegate(node, eventns, selector, listener, capture)
Returnsvoid
```javascript
delegate(node: Element, eventns: String, selector: String, listener: Function, capture: Boolean) : void
```
Attaches a listener to a DOM Element but delegates the event-listener
to the DOM Elements beneath that matches with the selector provided.
It receives the following arguments:
- node
Element: DOM Element to which the event handler is attached
- eventns
String: name of the event (with .namespace) to register
- selector
String: CSS selector for those elements that will propagate the event
- listener
Function: the function which receives the event notification
- capture
Boolean: if the event is activated at the beginning (defaultfalse)
capture = true, and at the end ("bubble") by default.
Events are executed in the order of how they're defined.
```javascript
jsu.delegate(document.body, "click.test", "h3", (e) => alert(1));
jsu.delegate(document.body, "click.test", "h3", (e) => alert(2), true);
jsu.delegate(document.body, "click.test", "h3", (e) => alert(3), false);
jsu.delegate(document.body, "click.test", "h3", (e) => alert(4), true);
```
For a better understanding of capture-events and event-bubbling,
read the following link: https://stackoverflow.com/a/10654134/2247494,
also you can see a demo here: http://jsfiddle.net/sc5Xa/198/
☗ Back to API
removeEventListener(node, eventns, listener)
Returnsvoid
```javascript
removeEventListener(node: Element, eventns: String, listener: Function) : void
removeEventListener(node: Element, eventns: String) : void
removeEventListener(node: Element) : void
```
Removes an event-handler from a DOM element. You can set a namespace to
the event by appending a dot . to the event name, or even you can pass
only a namespace that will match with all event types.
It receives the following arguments:
- node
Element: DOM element where the event handler is removed.
- eventns
String: (optional) name of the event (with .namespace) to remove
- listener
Function: (optional) the function which receives the event notification
getEventListeners(node, eventns)
ReturnsObject
```javascript
getEventListeners(node: Element, eventns: String) : Object
getEventListeners(node: Element) : Object
```
Gets all event-handlers from a DOM element. Each event handler attached by
addEventListener is tracked
by an internal store, which keeps track of the event type and the namespace
linked to a DOM Element.
It receives the following arguments:
- node
Element: DOM element to get the event listeners.
- eventns
String: (optional) name of the event or namespace.
{delegated: undefined,handler: function(e){},namespace: "tooltip",selector: undefined,useCapture: false,}{delegated: undefined,handler: function(e){},namespace: undefined, // no namespaceselector: undefined,useCapture: false,},{delegated: undefined,handler: function(e){},namespace: "language",selector: undefined,useCapture: false,}handleEvents(node)
ReturnsObject
```javascript
handleEvents(node: Element) : Object
```
This factory-method is a facade that simplifies the tasks for
attaching and
removing event listeners.
It implements a fluent interface that allows the chaining of methods
(as jQuery does). It receives an argument that is the DOM Element to
which you will attach or remove event-handlers.
The methods exposed are:
- off()
Function: facade of removeEventListener.
(eventns, listener)
- on()
Function: facade of addEventListener.
(eventns, listener, capture)
- delegate()
Function: facade of delegate.
(eventns, selector, listener, capture)
```javascript
const evtHandler = (e) => console.log(triggered ${e.type});
var code = document.getElementById('code');
jsu.handleEvents(code)
.off('click')
.off('.notify')
.on('mouseout.notify', evtHandler)
.delegate('click.code', 'pre', evtHandler);
```
☗ Back to API
---
Versioning
This projects adopts the Semantic Versioning (SemVer) guidelines: ```text .. ``` Given a version number MAJOR.MINOR.PATCH, increment the:- MAJOR version when you make incompatible API changes.
- MINOR version when you add functionality in a backwards-compatible manner.
- PATCH version when you make backwards-compatible bug fixes.
Issues
To report an issue and keep traceability of bug-fixes, please report to:- https://github.com/jherax/handle-events/issues
