[html5] r5217 - [e] (0) Mention that postMessage() won't work when the target hasn't loaded yet.

[whatwg at whatwg.org]

Author: ianh
Date: 2010-07-28 15:19:44 -0700 (Wed, 28 Jul 2010)
New Revision: 5217

Modified:
   complete.html
   index
   source
Log:
[e] (0) Mention that postMessage() won't work when the target hasn't loaded yet.

Modified: complete.html
===================================================================
--- complete.html	2010-07-28 22:07:41 UTC (rev 5216)
+++ complete.html	2010-07-28 22:19:44 UTC (rev 5217)
@@ -75356,8 +75356,20 @@
 
    </dd>
 
-  </dl><div class=impl>
+  </dl><p class=note>When posting a message to a <code><a href=#window>Window</a></code> of a
+  <a href=#browsing-context>browsing context</a> that has just been navigated to a new
+  <code><a href=#document>Document</a></code> is likely to result in the message not
+  receiving its intended recipient: the scripts in the target
+  <a href=#browsing-context>browsing context</a> have to have had time to set up
+  listeners for the messages. Thus, for instance, in situations where
+  a message is to be sent to the <code><a href=#window>Window</a></code> of newly created
+  child <code><a href=#the-iframe-element>iframe</a></code>, authors are advised to have the child
+  <code><a href=#document>Document</a></code> post a message to their parent announcing
+  their readiness to receive messages, and for the parent to wait for
+  this message before beginning posting messages.</p>
 
+  <div class=impl>
+
   <p>When a script invokes the <dfn id=dom-window-postmessage title=dom-window-postMessage><code>postMessage(<var title="">message</var>, <var title="">targetOrigin</var>, <var title="">ports</var>)</code></dfn> method (with two or three
   arguments) on a <code><a href=#window>Window</a></code> object, the user agent must
   follow these steps:
@@ -94703,6 +94715,7 @@
   Devdatta,
   Dimitri Glazkov,
   Dimitry Golubovsky,
+  Dirk Pranke,
   Divya Manian,
   dolphinling,
   Dominique Hazaël-Massieux,

Modified: index
===================================================================
--- index	2010-07-28 22:07:41 UTC (rev 5216)
+++ index	2010-07-28 22:19:44 UTC (rev 5217)
@@ -69123,8 +69123,20 @@
 
    </dd>
 
-  </dl><div class=impl>
+  </dl><p class=note>When posting a message to a <code><a href=#window>Window</a></code> of a
+  <a href=#browsing-context>browsing context</a> that has just been navigated to a new
+  <code><a href=#document>Document</a></code> is likely to result in the message not
+  receiving its intended recipient: the scripts in the target
+  <a href=#browsing-context>browsing context</a> have to have had time to set up
+  listeners for the messages. Thus, for instance, in situations where
+  a message is to be sent to the <code><a href=#window>Window</a></code> of newly created
+  child <code><a href=#the-iframe-element>iframe</a></code>, authors are advised to have the child
+  <code><a href=#document>Document</a></code> post a message to their parent announcing
+  their readiness to receive messages, and for the parent to wait for
+  this message before beginning posting messages.</p>
 
+  <div class=impl>
+
   <p>When a script invokes the <dfn id=dom-window-postmessage title=dom-window-postMessage><code>postMessage(<var title="">message</var>, <var title="">targetOrigin</var>, <var title="">ports</var>)</code></dfn> method (with two or three
   arguments) on a <code><a href=#window>Window</a></code> object, the user agent must
   follow these steps:
@@ -87895,6 +87907,7 @@
   Devdatta,
   Dimitri Glazkov,
   Dimitry Golubovsky,
+  Dirk Pranke,
   Divya Manian,
   dolphinling,
   Dominique Hazaël-Massieux,

Modified: source
===================================================================
--- source	2010-07-28 22:07:41 UTC (rev 5216)
+++ source	2010-07-28 22:19:44 UTC (rev 5217)
@@ -84874,6 +84874,18 @@
 
   </dl>
 
+  <p class="note">When posting a message to a <code>Window</code> of a
+  <span>browsing context</span> that has just been navigated to a new
+  <code>Document</code> is likely to result in the message not
+  receiving its intended recipient: the scripts in the target
+  <span>browsing context</span> have to have had time to set up
+  listeners for the messages. Thus, for instance, in situations where
+  a message is to be sent to the <code>Window</code> of newly created
+  child <code>iframe</code>, authors are advised to have the child
+  <code>Document</code> post a message to their parent announcing
+  their readiness to receive messages, and for the parent to wait for
+  this message before beginning posting messages.</p>
+
   <div class="impl">
 
   <p>When a script invokes the <dfn
@@ -108697,6 +108709,7 @@
   Devdatta,
   Dimitri Glazkov,
   Dimitry Golubovsky,
+  Dirk Pranke,
   Divya Manian,
   dolphinling,
   Dominique Hazaël-Massieux,