Skip to content

Latest commit

 

History

History
358 lines (264 loc) · 11.4 KB

README.md

File metadata and controls

358 lines (264 loc) · 11.4 KB
Raw

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

  1. Getting started
  2. Including the library
  3. API

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

☗ Back to Index

Including the library

handle-events can be included directly from a CDN in your site:

<!-- from unpkg.com -->
<script src="https://unpkg.com/handle-events/dist/handle-events.js"></script>

<!-- or from rawgit.com -->
<script src="https://cdn.jsdelivr.net/gh/jherax/[email protected]/dist/handle-events.js"></script>

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 = require('handle-events');

ES2015 Imports

import jsu from 'handle-events';

AMD

// using RequireJS
requirejs.config({
  paths: {
    // remove the extension .js
    'handle-events': '<PATH>/handle-events',
  },
});
require(['handle-events'], function(jsu) {
  console.log(jsu);
});

See an example with RequireJS here: http://jsfiddle.net/FdKTn/78/

☗ Back to Index

API

addEventListener(node, eventns, listener, capture)

Returns void

addEventListener(node: Element, eventns: String, listener: Function, capture: Boolean) : void

Attaches an event-listener 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 listener 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 (default false)

Each event listener 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.getElementById('title');

// add a named event listener with namespace (recommended)
const onMouseOver = e => console.log(`triggered ${e.type}.tooltip`);
jsu.addEventListener(title, 'mouseover.tooltip', onMouseOver);

// add an anonymous event listener (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:

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, using capture = true
  • 4: defined second, using capture = true
  • 1: first handler defined without setting capture
  • 3: second handler defined with capture = 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/

☗ Back to API

delegate(node, eventns, selector, listener, capture)

Returns void

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 listener 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 (default false)

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.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)

Returns void

removeEventListener(node: Element, eventns: String, listener: Function) : void
removeEventListener(node: Element, eventns: String) : void
removeEventListener(node: Element) : void

Removes an event-listener 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 listener 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 listener 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.getElementById('title');

jsu.removeEventListener(title, 'click'); // remove all listeners by event
jsu.removeEventListener(title, '.tooltip'); // remove all listeners by namespace
jsu.removeEventListener(title, 'mouseover.tooltip'); // remove all listeners by event + namespace
jsu.removeEventListener(title, null, onMouseOver); // remove all listeners by handler
jsu.removeEventListener(title); // remove all event handlers

☗ Back to API

getEventListeners(node, eventns)

Returns Object

getEventListeners(node: Element, eventns: String) : Object
getEventListeners(node: Element) : Object

Gets all event-listeners from a DOM element. Each event listener 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.getElementById('title');

jsu.getEventListeners(title); // get all event listeners
jsu.getEventListeners(title, 'click'); // get all listeners by event
jsu.getEventListeners(title, '.tooltip'); // get all listeners by namespace
jsu.getEventListeners(title, 'mouseover.tooltip'); // 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,
      handler: function(e){},
      namespace: "tooltip",
      selector: undefined,
      useCapture: false,
    }
  ],
  click: [ // Array(2)
    {
      delegated: undefined,
      handler: function(e){},
      namespace: undefined, // no namespace
      selector: undefined,
      useCapture: false,
    },
    {
      delegated: undefined,
      handler: function(e){},
      namespace: "language",
      selector: undefined,
      useCapture: false,
    }
  ]
}

☗ Back to API

handleEvents(node)

Returns Object

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. 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 = 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:

<MAJOR>.<MINOR>.<PATCH>

Given a version number MAJOR.MINOR.PATCH, increment the:

  1. MAJOR version when you make incompatible API changes.
  2. MINOR version when you add functionality in a backwards-compatible manner.
  3. 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.