Create event subscriptions in DOM. Manage them with update, unmount and mount methods.
Abstracts DOM's addEventListener, and removeEventListener methods into a subscription object.
npm install --save subvent
import {Subvent} from 'subvent'
// or use the shorthand:
import {on} from 'subvent'<head>
<script src="https://unpkg.com/subvent@latest/dist/iife/subvent.js"></script>
</head>Get the DOM nodes first:
const el1 = document.getElementById('element-1');
const el2 = // ...
const el3 = // ...
const el4 = // ...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: () => {...}});Unmount it:
evtSub1.unmount();
evtSub1.isMounted; // false- removes the event listener from the DOM node
Mount it:
evtSub1.mount()
evtSub1.isMounted; // true- adds the event listener to the DOM node
Update 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
Try it out on CodePen, or CodeSandbox
Subvent: Managing event subscriptions in DOM
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 is a constructor function that auto-subscribes to a DOM node on instantiation.
// 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 interfacename- 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
Subvent.isMounted- boolean indicating subscription's mount stateSubvent.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
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 itSubvent.prototype.duplicate- creates a new instance providing it's own properties as fallback values for undefined parameters
on is a so called "factory function" because it returns an instance, in this case a Subvent instance. The function also has the same syntax as the Subvent(). Consider it a shorthand for Subvent() syntax.
on() has the same parameter syntax as the Subvent
Return value
instance of Subvent
function on() {
return new Subvent(arguments)
}Just to conclude:
// both of these statements do the same thing: return the Subvent instance
on({node: titleEl, name: 'click', handler: clickHandler})
new Subvent({node: titleEl, name: 'click', handler: clickHandler})If you don't like the on() shorthand, create your own custom shorthand factory function:
// 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})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 [email protected]