event-hub

Broadcast events across frames

event-hub transparently sends scoped events from handlers to the top frame down to handlers in any frame that includes the module.

How it works

top frame            frame                            frame
┌───────────────────┐┌───────────────────────────────┐┌─────────────────┐
│                   ││                               ││                 │
│   ┌───────────┐   ││   ┌─────────┐   ┌─────────┐   ││   ┌─────────┐   │
│   │ event hub │   ││   │ handler │   │ handler │   ││   │ handler │   │
│   └─────┬─────┘   ││   └────┬────┘   └────┬────┘   ││   └────┬────┘   │
│         │         ││        │             │        ││        │        │
│         │     subscribe     │             │        ││        │        │
│         │◄~~~~~~~~~~~~~~~~~~│             │        ││        │        │
│         │         ││        │             │        ││        │        │
│         │         ││ subscribe            │        ││        │        │
│         │◄~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~│        ││        │        │
│         │         ││        │             │        ││        │        │
│         │         ││        │  subscribe  │        ││        │        │
│         │◄~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~│        │
│         │         ││        │             │        ││        │        │
│         │         ││        │             │        ││        │        │
│         │    fire event     │             │        ││        │        │
│         │◄──────────────────O             │        ││        │        │
│         │         ││        │             │        ││        │        │
│         │       event       │             │        ││        │        │
│         │────────────────►  X             │        ││        │        │
│         │         ││        │             │        ││        │        │
│         │         ││   event              │        ││        │        │
│         │────────────────────────────────►│        ││        │        │
│         │         ││        │             │        ││        │        │
│         │         ││        │    event    │        ││        │        │
│         │───────────────────────────────────────────────────►│        │
│         │         ││        │             │        ││        │        │
│   ┌─────┴─────┐   ││   ┌────┴────┐   ┌────┴────┐   ││   ┌────┴────┐   │
│   │ event hub │   ││   │ handler │   │ handler │   ││   │ handler │   │
│   └───────────┘   ││   └─────────┘   └─────────┘   ││   └─────────┘   │
│                   ││                               ││                 │
└───────────────────┘└───────────────────────────────┘└─────────────────┘

─► External event
◄~ Internal event

If the top frame has an EventHub instance it will orchestrate delegation of events. All that is required is to include the module in the frame.

Any event sent from a handler (created via createHandler), in any frame, is redelegated by the EventHub instance to any other handlers.

Each handler has its own unique internal id, that is passed on with the event in order to prevent it from firing the on the originating handler.

If the top frame does not have an EventHub instance - handlers in subframes won't be able to broadcast events beoynd their own frame - but still be broadcast within it.

Install

npm install @dr/event-hub

Usage

import createHandler, { MEDIA_PAUSE } from '@dr/event-hub';

let state = 'paused';

// Handle incoming events via handler.
const handler = createHandler((type) => {
  if (type === MEDIA_PAUSE) {
    state = 'paused';
  }
});

playButton.onclick = () => {
  if (state === 'paused') {
    state = 'playing';
    // Send events via handler.
    handler.send(MEDIA_PAUSE);
  } else {
    state = 'paused';
  }
}

API

createHandler

A function to create a handler for sending and receiving events.

Arguments

• callback (function) - Optional. A callback function to receive events. Has the following arguments:
  • type (string) - The type of the event, eg. MEDIA_PAUSE.
  • options (object) - Optional.
  • options.id (string|undefined) - Optional. Additional data for the given event.
  • options.data (any) - Optional. Additional data for the given event.

Returns

An EventHubHandler instance.

EventHubHandler

A class to listen to and send scoped events. It automatically filters out events sent from itself to avoid confusion.

Methods

send

A method to send events.

Arguments

• type (string) - The type of the event, eg. MEDIA_PAUSE.
• data (any) - Optional. Additional data for the given event.

remove

A method to remove the event listener if the handler is no longer needed.

eventTypes

Predefined event types:

• MEDIA_PAUSE (string) - Signals that other playing media elements should pause.

Demo

To run the demo clone the repo and then run it locally:

npm run demo

The demo runs 4 servers on different ports to simulate cross domain scenarios with regards to framesets. It shows how the state of some "play/pause" widgets react to eachother via events. Go to http://localhost:1234/demo/

Development

The repo is developed as an ESM module (source in esm/) with a minimal build step to support CommonJS (output to cjs/).