README

Simple Custom Event

Simple and easy to use custom event implementation with optional EventTarget element.

Features

Easy installation and usage
EventTarget is not required
Internet Explorer 9+ is supported (polyfill included)

Installation

via Yarn

yarn add simple-custom-event

via NPM

npm install simple-custom-event

via CDN

<script src="//unpkg.com/simple-custom-event@1.0.1"></script>

Usage

Sample of usage where we are creating MY_CUSTOM_EVENT event and triggering it with some optional data.

javascript (ES6+)

after Yarn/NPM installation

import SimpleCustomEvent from 'simple-custom-event'

const myEvents = new SimpleCustomEvent()

myEvents.on('MY_CUSTOM_EVENT', (data) => {
    console.log(data.detail)
})

myEvents.trigger('MY_CUSTOM_EVENT', {myOptionalData: 'eg some string'})

typescript

after Yarn/NPM installation

import SimpleCustomEvent from 'simple-custom-event'

const myEvents = new SimpleCustomEvent()

myEvents.on('MY_CUSTOM_EVENT', (data: CustomEvent) => {
    console.log(data.detail)
})

myEvents.trigger('MY_CUSTOM_EVENT', {myOptionalData: 'eg some string'})

javascript (ES5+)

with CDN

<!doctype html>
<html lang="en">
<head>
    <title>Simple Custom Event</title>
</head>
<body>
<script src="//unpkg.com/simple-custom-event@1.0.1"></script>
<script>
    var myEvents = new SimpleCustomEvent()
    
    myEvents.on('MY_CUSTOM_EVENT', function(data) {
        console.log(data.detail)
    })
    
    myEvents.trigger('MY_CUSTOM_EVENT', {myOptionalData: 'eg some string'})
</script>
</body>
</html>

Multi instances

Events simplifies the communication between components of application. Decouples event senders and receivers. Below simple example with multi instances of SimpleCustomEvent class:

file-1.js (ES6):

import SimpleCustomEvent from 'simple-custom-event'

const myEvtListener = new SimpleCustomEvent()
myEvtListener.on('MY_CUSTOM_EVENT', () => {
    // do something...
})

file-2.js (ES6):

import SimpleCustomEvent from 'simple-custom-event'

const myEvtEmiter = new SimpleCustomEvent()
myEvtEmiter.trigger('MY_CUSTOM_EVENT')

Methods

All available, public methods of SimpleCustomEvent class:

constructor([target])
Initializes an object.
- target
  Type: EventTarget
  DOM interface implemented by objects that can receive events and may have listeners for them.
  Default: document
.trigger(eventName[, detail])
Initializes and dispatches an custom Event, invoking the affected Listeners.
- eventName
  Type: string
  Custom event name.
- detail
  Type: any
  Any data passed when triggering the event.
.on(eventName, callback)
Sets up a function that will be called whenever the specified event is triggered.
- eventName
  Type: string
  Custom event name to listen for.
- callback
  Type: EventListenerOrEventListenerObject
  Callback function accepts a parameter: Event object describing the event which has occurred.
.off(eventName)
Removes an event listener previously registered with .on().
- eventName
  Type: string
  Custom event name for which to remove an event listener.

Contributing

Can you improve this simple project? Feel free to join it! Source code is TypeScript.

# project setup
yarn install

# compiles for development
yarn dev
# or
yarn dev:watch

# run unit tests
yarn test

License

Code released under the MIT license.

Usage no npm install needed!