@dr/event-hub
v1.0.1
Published
Broadcast events across frames
Downloads
1,353
Maintainers
Keywords
Readme
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/
).