iframe-api
Bidirectional API communication between parent window and iframe
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
- the payload includes iframe's serialized object
- external website gets the
api
object and makes a callapi.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.
- if
-
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
Author: Gleb Bahmutov © 2015
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
Copyright (c) 2015 Gleb Bahmutov
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.