grimen / postmessage Goto Github PK

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