postmessage-polyfill

window postmessage plugin
=========================

Modern browsers now support cross-window/cross-domain/cross-origin messaging
through window.postMessage.

postmessage is a simple wrapper for window.postMessage and the window message
event, for those who wish to use this feature in a more jQuery-like way.

postmessage falls back to window location hash polling for browsers that do
not support window.postMessage (i.e., IE7).

postmessage allows messaging back and forth using JSON where
window.postMessage only allows simple string-based messages.

postmessage also allows for complete request/response roundtrips using
success/error callbacks modeled after jQuery.ajax.

postmessage is tested on Safari 4, WebKit (Nightlies), Chrome 4, Firefox 3,
IE8, IE7 and Opera 10.10.

API
===

pm(options)
-----------
Send postmessage.

options:Map (Required)
A set of key/value pairs that configure the postmessage:

target:Window (Required)
The target window to send the postmessage.

type:String (Required)
The postmessage type. The postmessage will be
dispatched to handler(s) bound to postmessages of this
type.

data:Object (Required)
The postmessage data to be sent.

success:Function (Optional)
A function to be called if the postmessage succeeds.
The function gets passed the object returned by the
postmessage handler.

error:Function (Optional)
A function to be called if the postmessage fails. The
function gets passed the object thrown (Exception) by
the postmessage handler.

origin:String (Optional)
The target origin for the postmessage to be
dispatched, either as the literal string "*"
(indicating no preference) or as a URI. The
postmessage will only be dispatched if the scheme,
hostname and port match the target origin.
Default is "*".

url:String (Optional)
Required if window.postMessage is not available or
using location hash. The current url of the target
window you are sending the postmessage to. This is
required for setting the location hash of the target
window since you may not have access to reading the
target window.location.

hash:Boolean (Optional)
You can force passing postmessages via the target
window location hash by setting this to true.

pm.bind(type, fn, [origin], [hash])
-----------------------------------
Bind postmessage handler on the current window.

type:String (Required)
The postmessage type to bind to.

fn:Function (Required)
The postmessage handler. A function to execute each time the
postmessage type is received. The function gets passed the
postmessage data.

origin:String (Optional)
A URI specifying the origin of the postmessage. If specified,
the postmessage handler will only be executed if the
postmessage is received from the same origin matching the
scheme, hostname and port. Otherwise, the postmessage sender
will be notified through it's error callback of the origin
mismatch:

{
"message": "postmessage origin mismatch",
"origin": [
"http://www.abc.com",
"http://www.xyz.com"
]
}

You can set this globally. However, the origin specified in
the bind method will take precedence.

pm.origin = "http://www.xyz.com";

hash:Boolean (Optional)
You can force location hash polling to check for postmessages
by setting this to true. This is required only if you are
(forcefully) passing postmessages via the location hash.

pm.unbind([type], [fn])
-----------------------
Remove a previously-attached postmessage handler from the current
window. If type is not specified, all postmessage handlers will be
removed.

type:String (Optional)
The postmessage type to unbind from. If only the type is
specified all handlers of this type will be removed.

fn:Function (Optional)
The function that is to be no longer executed.

For examples and more:
======================
http://postmessage.freebaseapps.com