post-event

v0.4.0

Published

2 years ago

A Cross-Domain Event Handler javascript library. Pure Vanilla JS, no dependencies.

Downloads

0High
0Medium
0Low

julianxhokaxhiu

PostEvent

A Cross-Domain Event Handler javascript library. Pure Vanilla JS, no dependencies.

Introduction

This library was born with a simple goal in mind: provide a simple way to handle events, without the effort to code multiple times special code in case we are in a Cross-Domain situation.

Say hello to PostEvent.

Feature set

Cross-Domain

Event handling by default is not possible when an iFrame is not sharing the same origin URL, or the headers are not set to allow Cross-Domain communication.

This library therefore is using postMessage API to enable communication, preserving the same capability of a generic event handling.

Method chain

If you prefer, you can chain methods, in a jQuery-like way-ish. This is an example of method chain:

var pe = new PostEvent();

pe
.on( 'myCustomEvent', function (params){
  console.log( params.foo ); // bar
})
.trigger( 'myCustomEvent', { foo: 'bar' } );

Single channel across multiple instances

You can instanciate as much times as you want the library. By default it is always using the same window.parent entrypoint. This allows you to write simple code, without the need to handle special cases.

var pe1 = new PostEvent(),
    pe2 = new PostEvent();

pe1
.on('sayHello', function (params){
  console.log( 'Hello ' + ( params.name || 'World' ) ); // Hello User
});

p2.trigger('sayHello', { name: 'User' });

UMD Ready

You can use this library in the environment you prefer, thanks to the UMD bundling provided by WebPack.

More info here: https://github.com/umdjs/umd

Install

In order to use this library, you can just include the latest release in your browser like this

<!DOCTYPE html>
<html>
	<head>
		...
	</head>
	<body>
		...
		<script src="dist/PostEvent.js"></script>
		<script>
			var pe = new PostEvent();

			// console.log( pe );
		</script>
	</body>
</html>

or if you prefer as a module

// $ npm i post-event

import PostEvent from 'post-event'

let pe = new PostEvent();
// console.log( pe );

Initialization

When you instanciate the library, you can pass some configuration options, if you prefer:

debug: if true it will print some warnings, if the library is misused.
namespace: if defined, it will be used to filter messages type. Useful if you want to use multiple instances, with different channels. By default is this class name ( PostEvent )

This is an example of custom initialization:

var pe = new PostEvent({
  debug: true,
  namespace: 'MyCustomNamespace'
});

API

This library is made of two simple APIs:

trigger( name, params )

This API mimics $.trigger() from jQuery. The function accepts two arguments:

name: the event name you want to trigger.
params: the payload that you want to send.

This is an example usage:

var pe = new PostEvent();

pe.trigger( 'myCustomEvent', { foo: 'bar' } );

on( name, callback )

This API mimics $.on() from jQuery, but it's even more simplier. The function accepts two arguments:

name: the event name you want to subscribe.
callback: the callback function to call, when the event is detected. params object will be given as an argument, or contextual this object. Both can be null if no parameters were given during trigger.

This is an example of usage:

var pe = new PostEvent();

// Example 1
// No arguments, only this
pe.on( 'myCustomEvent', function (){
  console.log( this.foo ); // bar
});

// Example 2
// One argument, we don't use this
pe.on( 'myCustomEvent', function (params){
  console.log( params.foo ); // bar
});

// Example 3
// One argument, we use also this
pe.on( 'myCustomEvent', function (params){
  console.log( this.foo ); // bar
  console.log( params.foo ); // bar
});

License

See LICENSE