ManageIframe:Manual:Frame Messaging

From Learn About the Ext JavaScript Library

Jump to: navigation, search

1 Cross-Frame Messaging with ManagedIframe
2 Message Structure
3 Embedded page message API
4 Sending Cross-frame Messages

Cross-Frame Messaging with ManagedIframe

ManagedIframe implements a custom sendMessage method to facilitate communication between the frames host page (or another frame) and its embedded window context similar to that of HTML5/WhatWG/Firefox 3 [postMessage:http://developer.mozilla.org/en/docs/DOM:window.postMessage]. It, however, does NOT support cross-domain frame communication with this implementation. It does permit handling of complex data types (strings, arrays, object) across all Ext-supported browsers when the frame is updated/loaded from a same-origin domain.

Message Structure

The sendMessage method packages the message payload into a message object with the following structure: (No additional javascript libraries are required for the embedded frame)


message:{   
    data: {mixed}            //the message payload
 ,domain: {string}           //the senders document domain or value specified by the sender to assist in identification
    ,tag: {mixed, optional}  //a resource/process tag associated with the message
 ,source: {object}           //the global window object of the sender
    ,uri: {string}           //the documentURI of the sender
}

Embedded page message API

If sufficient domain privilege exists when the frame is loaded, three methods are introduced into the frames' global window object by ManagedIFrame:

embedded:window:sendMessage

Sends a message to the ManagedIFrame object in the window context of the parent page.

Syntax:

 sendMessage(  message [, tag] [, origin ] );

Parameter Description:

message - (mixed) the message content to be sent.
tag - (string, optional) additional tag reference for domain identification.
origin - (string, optional) defaults the senders document.domain.

embedded:window:onhostmessage

Message subscription function for the embedded document. Multiple messagehandlers may be defined.

Syntax:

 onhostmessage(  handler [,scope [,single [,tag ]]] );

Parameter Description:

handler - (function) the handler function to be invoked upon receipt of a message.
scope - (object) the scope used when the handler is fired (defaults to frames window object)
single - (boolean, optional) if true, indicates the defined handler will only be called once, and destroyed after use.
tag - (string, optional) if specified, only messages tagged with the specified value will be delivered to the handler. An unspecified value signifies that only messages without a tag value will be delivered to the handler.

Note: Returning false in an onhostmessage handler stops downstream handlers (with matching tags) from executing.

embedded:window:unhostmessage

Removes a message handler previously defined by the :onhostmessage function. Syntax:

 unhostmessage(  handler );

Parameter Description:

handler - (function) the original handler function to be invoked upon receipt of a message.

Sending Cross-frame Messages

To establish the necessary interface with an inline frame:

Create a new ManagedIframe instance, setting an event listener for handling incoming messages from the frame.

Example:


var MIF = new Ext.ux.ManagedIFrame({
      autoCreate       : {id:'frame1',width:600,height:400}
     ,src              : 'embedPage1.html'
     ,disableMessaging :false
     ,listeners  :
         //only subscribe to 'startup' tagged messages 
         {'message:startup' :function(srcFrame, message){
                    alert(message.uri + ' says:\n'+ message.data);
                    srcFrame.sendMessage('Acknowledged!', 'startup'); //to 'startup' tag subscribers
                   },
          domready: function(frame){
                 if(frame.domWritable()){
                     frame.execScript('init()');
                  }
               }
          }
 });

-- embedPage1.html --


<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <title>Frame Messaging with ManagedIFrame</title>
   <script type="text/javascript">
       var receiveHandler  = function(message){
            document.getElementById('logger').innerHTML += '<br/>Host page reply: '+message.data;
            return false;
       };
       var init = function(){ 
         onhostmessage(receiveHandler,window,false,'startup');  //subscribe to parent 'startup' messages.
         sendMessage("I'm awake !","startup");
       };
   </script>
</head>
<body>
   <div id="logger">Loaded !</div>
</body>
</html>

Review the messaging.html example included in the demoPack.zip distribution for an example of basic and multi-frame relay of messages.

Retrieved from "http://extjs.com/learn/ManageIframe:Manual:Frame_Messaging"