[e] (0) Mention that postMessage() won't work when the target hasn't …

…loaded yet. git-svn-id: http://svn.whatwg.org/webapps@5217 340c8d12-0b0e-0410-8428-c7bf67bfef74
whatwg · Jul 28, 2010 · b81bd2b · b81bd2b
1 parent b0563b3
commit b81bd2b
Show file tree

Hide file tree

Showing 3 changed files with 41 additions and 2 deletions.
diff --git a/complete.html b/complete.html
@@ -75356,7 +75356,19 @@ <h4 id=posting-messages><span class=secno>10.4.3 </span>Posting messages</h4>
 
    </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
@@ -94703,6 +94715,7 @@ <h3 class="no-num">Reflecting IDL attributes</h3>
   Devdatta,
   Dimitri Glazkov,
   Dimitry Golubovsky,
+  Dirk Pranke,
   Divya Manian,
   dolphinling,
   Dominique Haza&euml;l-Massieux,

diff --git a/index b/index
@@ -69123,7 +69123,19 @@ function receiver(e) {
 
    </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
@@ -87895,6 +87907,7 @@ interface <a href=#htmldocument>HTMLDocument</a> {
   Devdatta,
   Dimitri Glazkov,
   Dimitry Golubovsky,
+  Dirk Pranke,
   Divya Manian,
   dolphinling,
   Dominique Haza&euml;l-Massieux,

diff --git a/source b/source
@@ -84874,6 +84874,18 @@ function receiver(e) {
 
   </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 @@ interface <span>HTMLDocument</span> {
   Devdatta,
   Dimitri Glazkov,
   Dimitry Golubovsky,
+  Dirk Pranke,
   Divya Manian,
   dolphinling,
   Dominique Haza&euml;l-Massieux,