Subvent
Create event subscriptions in DOM. Manage them with update, unmount and mount methods.
Abstracts DOM's addEventListener, and removeEventListener methods into a subscription object.
Installation
In node projects:
npm install subvent --save
import {Subvent} from 'subvent'In browsers:
<head>
<script src="https://unpkg.com/subvent@1.1.0/dist/iife/subvent.js"></script>
</head>Usage
Get the DOM nodes first:
const el1 = document.getElementById('element-1');
const el2 = // ...
const el3 = // ...
const el4 = // ...Define the event subscription
const evtSub1 = new Subvent(el1, 'click', () => {...});- creates an instance of Subvent
- the instance represents an event subscription
The shorthand on function is also available:
const evtSub2 = on(el2, 'click', () => {...});If preferred, use an object to pass parameters:
const evtSub3 = on({node: el3, name: 'click', handler: () => {...}});Manage the subscription
Unmount it:
evtSub1.unmount();
evtSub1.isMounted; // falseMount it:
evtSub1.mount()
evtSub1.isMounted; // trueUpdate it:
evtSub2.update({name: 'dblclick',})- takes care of mounting and unmounting for us
- only changes the specifed arguments, retaining the old variables.
Duplicate it:
const evtSub4 = evtSub3.duplicate({node: el4});- uses Subvent's instance as a template for creating a new instance
- instance being duplicated provides fallback values for undefined parameters
Online Playgrounds
Try it out on CodePen, or CodeSandbox
Read a blog post about the library
Subvent: Managing event subscriptions in DOM
Documentation
This library provides two variables: Subvent (which is a constructor function), and it's shorthand on (which is a factory function that returns instance of Subvent).
Subvent
Subvent is a constructor function that auto-subscribes to a DOM node on instantiation.
Syntax
// traditional arguments:
new Subvent(node, name, handler [, options, defaults, thisArg]);
// object argument:
new Subvent({node, name, handler [, options, defaults: object, thisArg]});-
node- any DOM node that implements EventTarget interface -
name- string (corresponds to addEventListener'stypeparameter) -
handler- a function, or an object (corresponds to addEventListener'slistenerparameter) -
options- An object (corresponds to addEventListener'soptionsparamter) -
defaults- an object containing properties to be used as default fallback values for parameters. AnotherSubventinstance can be used asdefaultsand technically become a template for otherSubventinstances. -
thisArg- an object that is applied to handler as it's execution context, defaults tonode
Return value:
instance of Subvent
Properties
-
Subvent.isMounted- boolean indicating subscription's mount state -
Subvent.node- maps tonodeparameter (see above) -
Subvent.name- maps tonameparameter (see above) -
Subvent.options- maps tooptionparameter (see above) -
Subvent.thisArg- an object that is applied tohandleras it's execution context, defaults tonode
Methods
-
Subvent.prototype.update()- redefines the subscription with new parameters overwriting the old properties, those not overwritten, retain the old value. It handles unmounting and mounting so You don't have to. It accepts the same parameter syntax as it's contructor (Subvent), except the fact that all arguments are optional (those not passed, retain the old value) -
Subvent.prototype.unmount()- callsremoveEventListener(this.name, this._handler_, this.options) -
Subvent.prototype.mount()- callsaddEventListener(this.name, this._handler_, this.options) -
Subvent.handler- maps tohandlerparameter (see above) -
Subvent._handler- ifhandleris a function,_handlerwraps it, and ensures thehandleris called withthisArgvalueapplyed to it -
Subvent.prototype.duplicate- creates a new instance providing it's own properties as fallback values for undefined parameters
on
on is a so called "factory function" because it returns an instance, in this case an Subvent instance. The function also has the same syntax as the Subvent. Consider it a shorthand for Subvent syntax.
Syntax
on() has the same parameter syntax as the Subvent
Return value
instance of Subvent
Definition
function on() {
return new Eventity(arguments)
}Two ways to instantiate Subvent
Just to conclude:
// both of these statements do the same thing: return an Subvent instance
on({node: titleEl, name: 'click', handler: clickHandler})
new Subvent({node: titleEl, name: 'click', handler: clickHandler})Creating a custom Subvent shorthand
// a custom shorthand function, with a not so short name, but you get the point
function customShorthand() {
return new Subvent(arguments)
}
customShorthand({node: titleEl, name: 'click', handler: clickHandler})Community
Everyone is welcome to report any potential issue, or share an idea for a new feature. Colaborations are also welcome, but rather difficult at the moment, since I haven't established build procedure yet.
Anyone is welcome to contact me at filip.biterski@gmail.com