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 with npm
or yarn
# with npm $ npm install handle-events --save # with yarn $ yarn add handle-events
Including the library
handle-events
can be included directly from a CDN in your site:
<!-- from unpkg.com --> <!-- or from rawgit.com -->
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
var jsu = ;
ES2015 Imports
;
AMD
// using RequireJSrequirejs;;
See an example with RequireJS here: http://jsfiddle.net/FdKTn/78/
API
addEventListener(node, eventns, listener, capture)
Returns void
: 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
)
Each event handler attached is tracked by an internal store, which keeps track of the event type and the namespace linked to a DOM Element. You can access that store through the API getEventListeners.
var title = document; // add a named event handler with namespace (recommended)const onMouseOver = console;jsu; // add an anonymous event handler (without namespace)jsu;
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:
jsu;jsu;jsu;jsu;
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
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/
delegate(node, eventns, selector, listener, capture)
Returns void
: 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
)
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.
jsu;jsu;jsu;jsu;
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/
removeEventListener(node, eventns, listener)
Returns void
: void : void : 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
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. You can access that store through the API getEventListeners.
var title = document; jsu; // remove all listeners by eventjsu; // remove all listeners by namespacejsu; // remove all listeners by event + namespacejsu; // remove all listeners by handlerjsu; // remove all event handlers
getEventListeners(node, eventns)
Returns Object
: Object : 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.
var title = document; jsu; // get all event listenersjsu; // get all listeners by eventjsu; // get all listeners by namespacejsu; // get listeners by event + namespace
The object returned contains the event type as key, and its value is an array of objects with the event handler and the namespace.
mouseover: // Array(1) delegated: undefined {} namespace: "tooltip" selector: undefined useCapture: false click: // Array(2) delegated: undefined {} namespace: undefined // no namespace selector: undefined useCapture: false delegated: undefined {} namespace: "language" selector: undefined useCapture: false
handleEvents(node)
Returns Object
: 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. It receives the following arguments:(eventns, listener)
- on()
Function
: facade of addEventListener. It receives the following arguments:(eventns, listener, capture)
- delegate()
Function
: facade of delegate. It receives the following arguments:(eventns, selector, listener, capture)
const evtHandler = console;var code = document; jsu ;
Versioning
This projects adopts the Semantic Versioning (SemVer) guidelines:
<MAJOR>.<MINOR>.<PATCH>
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:
License
This project has been released under the ISC license. This license applies ONLY to the source of this repository and does not extend to any other distribution, or any other 3rd party libraries used in a repository. See LICENSE file for more information.