bahmutov / iframe-api Goto Github PK

View Code? Open in Web Editor NEW

36.0 6.0 11.0 325 KB

Bidirectional method calls API between external and iframed code.

Home Page: http://glebbahmutov.com/iframe-api/

JavaScript 72.35% HTML 27.65%

iframe-api's Introduction

iframe-api

Bidirectional API communication between parent window and iframe

Demo

Available on NPM and bower under name iframe-api.

Example

external website (index.html)

<script src="iframe-api/dist/iframe-api.js"></script>
<script>

/*
The iframe-api.js does an isIframed() check
to see if it is the parent or the child frame
and then decides it's functionality.

In most environments, the external index.html
is the top-level document, but in edge-cases
where the index.html is itself iframed by another
parent document, we want to explicitly specify that
this is the parent frame for the iframeApi
*/
//window.iFrameApiParent = true;

var myMethods = {
  foo: function (arg) {
    console.log('myMethods.foo called wtih argument', arg);
  },
  version: '0.1.0' // primitive values are also allowed
};
iframeApi(myMethods).then(function (api) {
  api.bar(); // or whatever methods iframed website exposes
}, function (err) {
  console.error('Could not get iframe api', err);
});
</script>
<iframe src="iframed.html"></iframe>

iframed website (iframed.html)

<script src="iframe-api/dist/iframe-api.js"></script>
<script>
var api = {
  bar: function (message) {
    console.log('iframed called from external', message);
  }
};
iframeApi(api).then(function (externalApi) {
  externalApi.foo('hello world!');
});
</script>

event sequence

iframe element loads iframed.html
iframed website loads script built from src/iframe-api.js
iframed website executed iframeApi that posts a message to the parent
- the payload includes iframe's serialized object api
external website gets the api object and makes a call api.bar()
iframed website makes call to the external website using externalApi.foo method.

The websites communicate by calling methods on the returned api object, underneath the we use window.postMessage. The iframed website initiates the contact because it knows when it has been loaded and ready to communicate.

API

Single function iframeApi(myApiObject, options) returns a promise with resolved api object.

myApiObject
- can be undefined or null to avoid passing anything to the other side
- if empty object, the other side will receive empty object
- can have methods and properties

api object example

var myApi = {
  foo: function () {
    this.bar();
  },
  bar: function () {
    console.log('hello', this.name)
  },
  name: 'world'
};

options - optional object with the following properties
- debug | verbose prints console messages during handshake
- md5
  - if true this side will compute md5 checksum of the received source and compare to declared before reviving api object.
  - if a string, takes it as the md5 checksum to be compared against computed.

options example

// do not recreate received api, unless its MD5 matches given string
var options = {
  debug: false,
  md5: '845998b5f8907e585c31874ec5cc79a0'
};

Calling remote methods

You can pass arguments to remove API. Each method call returns a promise object

iframeApi(...).then(function (remoteApi) {
  remoteApi.foo('a', 'b', 'c').then(function (result) {
    console.log('remoteApi.foo(a, b, c) returned', result);
  });
});

Small print

License: MIT - do anything with the code, but don't blame me if it does not work.

Spread the word: tweet, star on github, etc.

Support: if you find any problems with this module, email / tweet / open issue on Github

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

iframe-api's People

Contributors

Stargazers

Watchers

Forkers

tranphuoctien d-anikin fnnzzz dagjomar rockarena amrynsky oztek22 mufukuri joosenavarro gualtierim subhrakdas

iframe-api's Issues

Return promise from an API method with result

we cannot return sync value, need to return a promise that can be resolved

Send MD5 with external API to the iframe

Pass options to the other side

Pass initial deep clone to the other side (from external website to iframe for example).
Useful to request specific version for example.

Refactor log-to into separate repo

Useful front end component - mirror console.log calls into separate div, entirely JavaScript

Running a parent-child iframe configuration inside another iframe does not work

This is a crazy edge-use-case, but still a valid technical question, I guess.

So, I have a working setup using two html-files - one for the parent.html and one for the iframed child iframed.html, using the iframeApi, and it is working as it should.

Now, however, I wish to put one or more of these "parent.html" into a big html file.
The use case is, that is the "parent.html" is a working "widget" type of application, and I want to show off multiple different versions of "parent.html" with different configurations.

So - I want an embeds multiple iframes of the "parent.html" but this does not work, because the "iframe-api.js" checks to see if itself is iframed, and if so thinks it is the "child iframe" and thus waits for a "parent document" to present itself.

The main culprit is this simple function

function isIframed() {
  return parent !== window;
}

Adding a simple custom override check fixes my problem, because I can specify a global variable in the actual "parent.html", such as window.iFrameApiParent=true;

function isIframed() {
  return parent !== window && !window.iFrameApiParent;
}

Allow sending a function across the boundary to be executed

Only if the other side allows it.

function connected(api) {
  api.evaluate(function () {
    console.log('hi on the other side');
  });
}

If the other side does not allow, do not add evaluate method to the API

async api methods

Make sure if api method returns a promise, it is resolved and the result is sent to the other side

publish on bower

Make explicit handshake call

Instead of iframe sending api right away, make handshake call first.
Pass options object.

Remove code duplication

between external api and internal api js

Add grunt watch

continuous build on file changes

Collapse iframe and external code into one

They do essentially the same thing. Can combine into one.

Instead of simple api object allow function that returns an object given options from the other side

To allow returning different api by version, allow function

iframeApi(myApi).then(...);
function myApi(clientOptions) {
  switch (clientOptions.version) {
    case '0.1.0':
      return { foo: ...}
    break;
    case '0.2.0':
      return { bar: ...}
    break;
  }
}

When remove methods fails (throws an error), reject the promise on the other side

Add options to iframeApi method

For example to validate md5 of the code before evaluating it

setup semantic-release

add badge

Use self-addressed

For promise-based postMessage calls use https://github.com/bahmutov/self-addressed

Integrate this awesome api with angularJS app.

I would like to use this api with an anugalrjs app that control the iframe. Is there any restricts?
Can you give me some starting point?
thanks

Transmit non-method api properties

for example version

Clean up or how to use this more than one time per application

How do remove the postMessage() listener so an existing listener can be terminated?

I have the next to stop communicating between the iframe, because the iframe will be loaded with different content/application to be communicated with. I am unsure of how to do that?

Promise-returning API for initial call?

It would be nice to return a promise for initial call and return values.

Swagger support?

HI,

Have you thought about adding Swagger support for this?

Design the API using http://swagger.io/
Build host and iframe client libraries using yet_not_existing_swagger_iframe_api_builder

If client calls iframeAPI method 'bar'

iframeApi.bar('something').then(function(){
});

then adding your code in to that inside iframe could be

// inside iframe
iframeAPI.on('bar', function(promise?Event, arg1) {
console.log(arg1)
});

This is only idea and haven't thought about this in deeper. This would allow you to write the API using swagger spec and it would generate the client js and your logic would be attached using promise.then() and event .on('myAPIfunc', funcition)

Use with different iframe in one page

What is right way to use this one with different iframe in one page.
Explane:
I have one page and two iframe. My main page should send message for first frame and if it relation latter send something to another frame.

I cant find out how separate iframe answer and api.

Kind regard.

wrap window onmessage, not overwrite it

callback interface for iframe

similar to external api

iframeApi(myCommands, function (err, externalApi) {});

Demo not working in Fireox

Hi This looks really good. Just thought I would point out that your demo site showing the handshakes etc works in Chrome but not Firefox. Is that a limitation of library or just an HTML gotcha in the Firefox html? This is currently making me think twice about using it....

all best
and keep up the good work,
ian