frame-channels v0.0.65

frame-channels

pub/sub channels between browser iframes

Usage

Open a channel to communicate with an iframe

var channel = frameChannels.create('my-channel', {
  // iframe selector or window object
  target: '#my-iframe',
  // (optional) restrict message origin
  originFilter: /^http\:\/\/domain\.com\//,
  // (optional) timeout when waiting for a message response
  responseTimeout: 30000,
  // (optional) let the iframe control it's positioning with messages
  allowPositionControl: true
  // (optional) indicate how to create the iframe if it doesn't exists
  iframe: {
    id: 'my-iframe',
    url: 'http://domain.com/path',
    setup: function(element) {
      channel.iframe.size(180, 50);
      channel.iframe.dock('bottom-right');
      // iframe is invisible by default
      channel.iframe.show();
    }
  }
});

// send a message to the iframe
// ready() ensures the iframe is built and
// someone inside the iframe is listening (called channel.subscribe)
channel.iframe.ready().then(function(){
  channel.push({ hello: 'world' });
  channel.subscribe(function(msg){
    console.log('got', msg);
  });
});

Inside the iframe, open a channel with parent window

var channelA = frameChannels.create('my-channel', {
  target: window.parent
});
channel.push({ hello: 'parent' });
channel.subscribe(function(msg){
  console.log('parent sent', msg);
});

// set iframe position in parent
channel.push({ dock: 'bottom right', size: {
  width: '180px',
  height: '50px'
}});
channel.push({ maximize: true });
channel.push({ hide: true });
channel.push({ show: true });
channel.push({ restore: true });

using Request/Response pattern:

channel.push({
  question: 'areYouOk?',
  respond: true
}).then(function(response) {
  if (response.ok) {
    console.log('great');
  }
});

// or simply
channel.request({
  question: 'areYouOk?'
}).then(function(response) {
  if (response.ok) {
    console.log('great');
  }
});

channel.request('location').then(function(response) {
  console.log(response.city);
});

Note: channel.request() is just an alias to push that will set message.respond=true.

channel.subscribe(function(msg, respond){
  if (msg.question === 'areYouOk?' && respond) {
    respond({ ok: true });
  }
  if (msg.value === 'location' && respond) {
    respond({ city: 'Lima' });
  }
});