Bellhop
Bellhop is a simple event-based communication layer between the page DOM and an iframe. It doesn't require any additional dependencies. Super easy to use and setup.
Installation
npm install bellhop-iframe
Importing Bellhop
The Bellhop module contains support for ES6 modules, CommonJS and browser global definitions. To import with ES6,
import { Bellhop } from 'bellhop-iframe';
To import with CommonJS, refer instead to the UMD build
const Bellhop = require('bellhop-iframe/dist/bellhop-umd.js');
You can also import the UMD version by using import
import { Bellhop } from 'bellhop-iframe/dist/bellhop-umd.js'
Lastly, the UMD module can also be directly included on an HTML page. This will declare Bellhop and attach it directly
to window
<script src="node_modules/bellhop-iframe/dist/bellhop-umd.js"></script>
Basic Usage
Here's a very simple example to get started. We have two pages index.html
and child.html
. This is the minimum you need to get them talking to each other.
Contents of index.html
<iframe src="child.html" id="page" width="200" height="200"></iframe>
<script>
const bellhop = new Bellhop();
bellhop.connect(document.getElementById("page"));
bellhop.on('init', function(event){
});
bellhop.send('user', {
"name" : "Dave Smith",
"age" : 16,
"city" : "Boston"
});
</script>
Contents of child.html
<script>
const bellhop = new Bellhop();
bellhop.connect();
bellhop.send('init');
bellhop.on('user', function(event){
const user = event.data;
});
</script>
Available Methods
new Bellhop
The constructor creates a new Bellhop
instance, taking an optional unique identifier for this instance. If no id is provided, a random one is selected
connect
Connects a Bellhop
instance to an iframe, or it's containing window. For instance, given a Bellhop
instance bellhop
:
bellhop.connect();
will connect a child iframe to it's parent, allowing it to emit messages out of the iframe. However,
var iframe = document.querySelector('iframe');
bellhop.connect(iframe);
allows a containing page to connect with an interior iframe and emit message into the iframe.
destroy
disconnect
removes any listener for events from another frame, and stops listening for messages altogether
off
Removes an event listener previously added by the .on()
method, or removes a given callback method from a listener. When deleting a callback, the function passed in is required to be the original function passed into the .on()
method.
bellhop.off(‘init’);
bellhop.off(‘init’, callback)
send
Sends a named message to another iframe:
bellhop.send('newHighscore', { value: 100 });
fetch
and respond
Convenience methods for automating response of values between the interior and exterior of frames. For instance:
var iframe = document.querySelector('iframe');
var bellhop = new Bellhop(iframe);
bellhop.connect();
bellhop.respond('config', { difficulty: 'hard', theme: 'dark' });
var bellhop = new Bellhop();
bellhop.connect();
bellhop.fetch('config', function(result) {
console.log(result);
});
Additionally, object passed to respond() can be a function, whose result will be returned in the callback of the fetch function.
var functionExample = function(){
return "result of functionExample";
};
bellhop.respond('function', functionExample);
bellhop.fetch('function', function(result) {
console.log(result.data);
});
Furthermore, respond() accepts a plain object, string, or number. If a function is passed, it will be called and the function's return-value sent. If a promise is passed in or returned from a function that was passed in, that promise will be await-ed before it's value returned.
For example, the following all return "data"
to bellhop.fetch()
bellhop.respond('example', "data");
let promiseData = new Promise(function(resolve, reject) {
resolve("data")
});
bellhop.respond('example', promiseData)
var functionExample = function(){
return "data";
};
bellhop.respond('example', functionExample);
var functionPromiseExample = function(){
return new Promise(function(resolve, reject) {
resolve("data")
});
};
bellhop.respond('example', functionPromiseExample);
trigger
Triggers any event handlers for a given event type optionally passing data to other areas in the app that are listening for this event
bellhop.trigger('eventType', {data: 'example'});
Debug Mode
Bellhop has a debug mode which enables additional logging when an instance sends or receives
a message. It can be enabled by simply setting the debug
flag to true
:
bellhop.debug = true;
By default (above method) it will print a message outlining whether the bellhop instance was a
child or parent, whether the message was sent or received, and the contents of the message. If you require additional or custom logging you can also pass a function as the flag.
const log = () => {console.log('Hello World!');}
bellhop.debug = log;
If you pass a function to debug three parameters* are passed to help fill out the log statements if required:
const log = ({isChild, received, message}) => {
console.log(isChild);
console.log(received);
console.log(message);
}
*Note: the names must be identical, but you are able to omit any or all if they're not required.
target
Property for retrieving the iframe element through which this Bellhop
instance is communicating:
var iframe = document.querySelector('iframe');
var bellhop = new Bellhop(iframe);
console.log(bellhop.target === iframe.contentWindow);
License
Copyright (c) 2021 Springroll
Released under the MIT License.