frameTalk

frameTalk.js provides a simple way to use window.postMessage for iFrame communication. After loading, frameTalk will add event listener to the window it is loaded. You have to load frameTalk.js script in all windows or iFrames you want to use it. frameTalk.js works without any dependencies, but if jQuery is found, you can use promises, and the handshake method asynchronously frameTalk.js needs window.JSON to run, and it will log the issue on the console if JSON is not found.

Ultra fast usage reference:

// ask data with a promise from parent to this iFrame. Id of this iFrame must be declared
frameTalk.sendPromise(window.top, "_IframeID", "someObject.someMethod", [argument1, argument2]).then(doOnSuccess, doOnFail);

// example without using promises
frameTalk.sendMessage(window.top, "someObject.someMethod", [argument1, argument2]);

// handshake is optional to use but it makes sure that postMessage wil find its target
// ensure connection from "_Iframe" iframe element and then ask for some data from parent
    frameTalk.handshake(window.top, "_Iframe").then(
        function(connectionOK) {            
			if (connectionOK === true) {
				// run the window.top.saveDepartmentData function with some params
				frameTalk.sendMessage(window.top, "saveDepartmentData", ["sales", "John Doe"]);
			} else {
				// handshake failed
			}            
        },
        function(error) { 
			// handshake failed, possibly no frameTalk to listen to handshake there
		}
    )

frameTalk object is the only public object that frameTalk.js exposes. It has following public methods and properties:

frameTalk.debugging

**description:** Sets or gets the debugging setting. Default is true to help you connect the iFrames. It logs all frameTalk actions in browser console.

frameTalk.debugging = true;

frameTalk.sendMessage (where, theFunction, theParams)

**description:** This method uses window.postMessage to send the message.

examples:

// from child to parent
frameTalk.sendMessage( window.top, "doRunFn", [1,2,3,'four'] );
// from parent to child
frameTalk.sendMessage( iframeDOMobject, "doRunFn", 154 );
frameTalk.sendMessage( "iFrameID", "someObject.someFn", paramsArray );
frameTalk.sendMessage( $("#iFrameID")[0], "someObject.someFn", paramsArray );

parameters:

• where: (type: DOM object OR string of the id of the iFrame) : the iFrame or window to talk to
• theFunction: (type: string) : the listener's function's name you want to run
• theParams: (type: array or string/number for single values) : the params of the listener's function's.

returns: Nothing. Will log on the console any error

Note: there is a fourth parameter, the promiseInd which is the handshake promise Index and it is not to be used. That is way any parameters for the function to be called should be in an array object.

frameTalk.sendPromise (where, fromId, theFunction, theParams)

**description:** This method uses window.postMessage to ask the promise.

examples:

// from child to parent
frameTalk.sendPromise(window.top, "myFrameID", "spyreqs.rest.getWebLists", []).then(doOnSuccess, doOnFail);
// from parent to child
frameTalk.sendPromise( iframeDOMobject, "@@top@@", "doRunFn", 154 ).then(doOnSuccess, doOnFail);
frameTalk.sendPromise( "iFrameID", "@@top@@", "someObject.someFn", paramsArray ).then(doOnSuccess, doOnFail);
frameTalk.sendPromise( $("#iFrameID")[0], "@@top@@", "someObject.someFn", paramsArray ).then(doOnSuccess, doOnFail);

parameters:

• where: (type: DOM object OR string of the id of the iFrame) : the iFrame or window to talk to
• fromId: (type: string) : the id of the iFrame that promise was asked from. Please use "@@top@@" for window.top
• theFunction: (type: string) : the listener's function's name you want to run
• theParams: (type: array or string/number for single values) : the params of the listener's function's.

returns: a promise (jQuery promise)

frameTalk.handshake (toWindow, fromId)

**description:** This method tries to ensure communication between this window and the destination window. Please note it is not obligatory to use it before send data. You can always try communicate without ever calling handshake, but you will not be sure that postMessage will find its target.

example: Handshake from top window to iframe

  var dest = window.document.getElementById('child1');
  
	// use with promise: (when jQuery is present)
	frameTalk.handshake(dest).then(
		function(result) { alert("success:" + result); },
		function(error) { alert('handshake failed. ' +  error ); }
	); 

	// use without promise. This will log the result on browser console (opens with F12)
	frameTalk.handshake(dest);

example: Handshake from iframe with Id="kid" to top window

	var dest = window.top;
	// use with promise: (when jQuery is present)  
	frameTalk.handshake(dest, "kid").then(
		function(result) { alert("success:" + result); },
		function(error) { alert('handshake failed. ' +  error ); }
	); 

	// use without promise. Will log the result on console
	frameTalk.handshake(dest, "kid");

parameters:

• toWindow: (type: DOM object) : the iFrame or window to handshake with
• fromId: (type: string) : the id of the iFrame that handshake was started from

returns: A promise or nothing, depending on syntax

frameTalk.getId

**description:** Returns the random 4 digit id number created from frameTalk auto init.

var myUniqueId = frameTalk.getId();

frameTalk.failTimeLimit

**description:** Default value is 5000 ms. It is the time limit until it stops trying for a handshake. If loading iFrames takes more than 5 seconds, you can change this limit.

frameTalk.failTimeLimit = 15000;

frameTalk.init

**description:** This method adds the proper event listener to the window, depending on browser standards. It is auto called once the js is loaded. If called again, it makes sure it will not add another listener. Once it is called, it puts a property to the window:

returns: The method call returns true / false