TalkIn is an interface providing safe and easy unidirectional cross-document communication.
Make sure you have configured and built TalkIn.
Load TalkIn:
<script src="path/to/talkin-parent.min.js"></script>Register an endpoint to be called:
LI.TalkIn.register('alertMessage', function(data) {
alert(data.message);
});Load TalkIn:
<script src="path/to/talkin-child.min.js"></script>Call the endpoint registered in the parent:
LI.TalkIn.send('alertMessage', {
message: 'Salsa Shark'
});Because it is:
-
Flexible
- Send messages without providing a target origin.
- Recieve messages from infinitely nested iframes.
- Intelligently selects the best method for communication.
-
Safe
- Employs postMessage best practices (origin whitelisting and explicit targetOrigins).
- Messages are digested in whitelisted endpoints.
- Hardened to combat XSS threats.
-
Quick
- Minimal execution time and lazily-loaded components.
- Less than 3K minified (talkin-parent.js).
- Simple to learn and use.
Due to it's origin flexibility, TalkIn is especially suited for modules and widgets that appear across sites containing multiple subdomains and protocols:
- Rich ads
- AJAX dialogs (login boxes, upload forms, etc.)
- Pretty much anything that may not have specific parent origin knowledge.
TalkIn is designed to work in a wide variety of browsers, old and new. It is performance optimised for modern browsers that support postMessage (http://caniuse.com/x-doc-messaging), but the fallback will work in browsers all the way back to IE6.
-
Ensure you have Node and Grunt installed, clone the repository, and then
npm installto fetch the dependencies. -
Edit
config/config.yamlwith your environment's information before building. See the comments in the config file; specifically, you'll need to:
- Add origins to the whitelist.
- Update paths to necessary legacy support files (which you'll need to copy to your server).
-
Run
gruntto build. This will output files to the/distdirectory. (There are a few different versions, each suited for a specific use case.) -
To view the demos, run
grunt serverand navigate to http://localhost:9090/.
The following versions of TalkIn are built by running grunt:
talkin-parent.js: For use in the parent document. Excludes the 'send' API.talkin-child.js: For use in the child document. Excludes the 'register' API.talkin-debug.js: Includes all APIs and logs output out to console. Perfect for troubleshooting.talkin-demo.js: A version of talkin-debug.js excluding origin whitelisting. Legacy support is configured for the included demo server environment.talkin-parent.min.js: An uglified version oftalkin-parent.js.talkin-child.min.js: An uglified version oftalkin-child.js.
LI.Talkin.register(methodName, endpoint)Registers an endpoint to be invoked by the child document. The endpoint can either be a function or an object that exposes functions, which is useful for organizing a collection of similar methods.
methodName {String}: The name of the function or object (the latter acting as a namespace for attached methods).
endpoint {Function || Object}: The function or object methods exposed to be invoked.
// Registering a function (basic):
LI.TalkIn.register('processNumber', function(data) {
doSomethingWith(data.number);
});
// Registering an object (advanced):
// Note that only functions directly attached to the object can be invoked
// by TalkIn, effectively allowing for only a single namespace.
// (E.G. 'pizza.eat')
LI.TalkIn.register('list', (function() {
var list = document.getElementById('my-list');
return {
update: function(data) {
updateItem(list, data.itemId);
},
destroy: function(data) {
destroyItem(list, data.itemId);
}
};
}()));LI.TalkIn.send(endpointOrData, data)Transports a data object from the child to an endpoint registered in the parent document. There are two ways to invoke send: Passing an endpoint and data as separate arguments or passing a single object mapping endpoints to data (see last example below). The latter method is useful when two unrelated endpoints should be invoked immediately (on page load for instance) and should always be used in this case to maintain IE7 support. (If you invoke send twice in a row, IE7 users will find that the first send request will be overwritten by the second.)
endpointOrData {String || Object}: The registered endpoint you wish to invoke OR an object containing endpoints and the data you wish to deliver to each. Note that dot notation is used for methods on a registered object (see example below).
data {Object}: A JSON structure passed to the method.
// Invoke a function (basic):
LI.TalkIn.send('processNumber', {
number: 42
});
// Invoke a method on an object (advanced):
// Note that only functions one namespace deep are allowed.
LI.TalkIn.send('list.update', {
itemId: 'list-item-7'
});
// Invoke multiple endpoints with corresponding data:
LI.TalkIn.send({
'processNumber': {
number: 42
},
'list.update': {
itemId: 'list-item-7'
}
});LI.TalkIn.getQueryParams()A helper function that grabs the window's query string and convert it into a friendly object. This also grabs DoubleClick params, which are semicolon-separated key-value pairs that appear before the location search.
None.
{Object} containing a key-value map of all the query and DoubleClick params.
LI.TalkIn.addListener(el, evt, fn)Adds an event listener to an element. Used internally, addListener is exposed as a convenience method in environments where libraries like jQuery are unavailable.
el {Object}: The element the listener will be attached to.
evt {String}: The event type to listen for.
fn {Function}: The function to be called when the event fires.
LI.TalkIn.removeListener(el, evt, fn)Removes an event listener from an element. Used internally, removeListener is exposed as a convenience method in environments where libraries like jQuery are unavailable.
el {Object}: The element to remove the listener from.
evt {String}: The event type to remove.
fn {Function}: The function to remove.