[html5] r6421 - [e] (0) An intro section on avoiding common pitfalls with scripts. File bugs if [...]

whatwg at whatwg.org whatwg at whatwg.org
Thu Aug 11 14:42:44 PDT 2011


Author: ianh
Date: 2011-08-11 14:42:43 -0700 (Thu, 11 Aug 2011)
New Revision: 6421

Modified:
   complete.html
   index
   source
Log:
[e] (0) An intro section on avoiding common pitfalls with scripts. File bugs if you have ideas of other things to mention here.
Fixing http://www.w3.org/Bugs/Public/show_bug.cgi?id=12664

Modified: complete.html
===================================================================
--- complete.html	2011-08-11 21:12:41 UTC (rev 6420)
+++ complete.html	2011-08-11 21:42:43 UTC (rev 6421)
@@ -298,7 +298,8 @@
      <li><a href=#typographic-conventions><span class=secno>1.8.2 </span>Typographic conventions</a></ol></li>
    <li><a href=#a-quick-introduction-to-html><span class=secno>1.9 </span>A quick introduction to HTML</a>
     <ol>
-     <li><a href=#writing-secure-applications-with-html><span class=secno>1.9.1 </span>Writing secure applications with HTML</a></ol></li>
+     <li><a href=#writing-secure-applications-with-html><span class=secno>1.9.1 </span>Writing secure applications with HTML</a></li>
+     <li><a href=#common-pitfalls-to-avoid-when-using-the-scripting-apis><span class=secno>1.9.2 </span>Common pitfalls to avoid when using the scripting APIs</a></ol></li>
    <li><a href=#conformance-requirements-for-authors><span class=secno>1.10 </span>Conformance requirements for authors</a>
     <ol>
      <li><a href=#presentational-markup><span class=secno>1.10.1 </span>Presentational markup</a></li>
@@ -2305,10 +2306,73 @@
 
    </dd>
 
-  </dl><h3 id=conformance-requirements-for-authors><span class=secno>1.10 </span>Conformance requirements for authors</h3>
+  </dl><h4 id=common-pitfalls-to-avoid-when-using-the-scripting-apis><span class=secno>1.9.2 </span>Common pitfalls to avoid when using the scripting APIs</h4>
 
   <p><i>This section is non-normative.</i></p>
 
+  <p>Scripts in HTML have "run-to-completion" semantics, meaning that
+  the browser will generally run the script uninterrupted before doing
+  anything else, such as firing further events or continuing to parse
+  the document.</p>
+
+  <p>On the other hand, parsing of HTML files happens asynchronously
+  and incrementally, meaning that the parser can pause at any point to
+  let scripts run. This is generally a good thing, but it does mean
+  that authors need to be careful to avoid hooking event handlers
+  after the events could have possibly fired.</p>
+
+  <p>There are two techniques for doing this reliably: use <a href=#event-handler-content-attributes>event
+  handler content attributes</a>, or create the element and add the
+  event handlers in the same script. The latter is safe because, as
+  mentioned earlier, scripts are run to completion before further
+  events can fire.</p>
+
+  <div class=example>
+
+   <p>One way this could manifest itself is with <code><a href=#the-img-element>img</a></code>
+   elements and the <code title=event-load>load</code> event. The
+   event could fire as soon as the element has been parsed, especially
+   if the image has already been cached (which is common).</p>
+
+   <p>Here, the author uses the <code title=handler-onload><a href=#handler-onload>onload</a></code> handler on an <code><a href=#the-img-element>img</a></code>
+   element to catch the <code title=event-load>load</code> event:</p>
+
+   <pre><img src="games.png" alt="Games" onload="gamesLogoHasLoaded(event)"></pre>
+
+   <p>If the element is being added by script, then so long as the
+   event handlers are added in the same script, the event will still
+   not be missed:</p>
+
+   <pre><script>
+ var img = new Image();
+ img.src = 'games.png';
+ img.alt = 'Games';
+ img.onload = gamesLogoHasLoaded;
+ // img.addEventListener('load', gamesLogoHasLoaded, false); // would work also
+</script></pre>
+
+   <p>However, if the author first created the <code><a href=#the-img-element>img</a></code>
+   element and then in a separate script added the event listeners,
+   there's a chance that the <code title=event-load>load</code>
+   event would be fired in between, leading it to be missed:</p>
+
+   <pre class=bad><!-- Do not use this style, it has a race condition! -->
+ <img id="games" src="games.png" alt="Games">
+ <!-- the 'load' event might fire here while the parser is taking a
+      break, in which case you will not see it! -->
+ <script>
+  var img = document.getElementById('games');
+  img.onload = gamesLogoHasLoaded; // might never fire!
+ </script></pre>
+
+  </div>
+
+
+
+  <h3 id=conformance-requirements-for-authors><span class=secno>1.10 </span>Conformance requirements for authors</h3>
+
+  <p><i>This section is non-normative.</i></p>
+
   <p>Unlike previous versions of the HTML specification, this
   specification defines in some detail the required processing for
   invalid documents as well as valid documents.</p> <!-- This has led

Modified: index
===================================================================
--- index	2011-08-11 21:12:41 UTC (rev 6420)
+++ index	2011-08-11 21:42:43 UTC (rev 6421)
@@ -298,7 +298,8 @@
      <li><a href=#typographic-conventions><span class=secno>1.8.2 </span>Typographic conventions</a></ol></li>
    <li><a href=#a-quick-introduction-to-html><span class=secno>1.9 </span>A quick introduction to HTML</a>
     <ol>
-     <li><a href=#writing-secure-applications-with-html><span class=secno>1.9.1 </span>Writing secure applications with HTML</a></ol></li>
+     <li><a href=#writing-secure-applications-with-html><span class=secno>1.9.1 </span>Writing secure applications with HTML</a></li>
+     <li><a href=#common-pitfalls-to-avoid-when-using-the-scripting-apis><span class=secno>1.9.2 </span>Common pitfalls to avoid when using the scripting APIs</a></ol></li>
    <li><a href=#conformance-requirements-for-authors><span class=secno>1.10 </span>Conformance requirements for authors</a>
     <ol>
      <li><a href=#presentational-markup><span class=secno>1.10.1 </span>Presentational markup</a></li>
@@ -2202,10 +2203,73 @@
 
    </dd>
 
-  </dl><h3 id=conformance-requirements-for-authors><span class=secno>1.10 </span>Conformance requirements for authors</h3>
+  </dl><h4 id=common-pitfalls-to-avoid-when-using-the-scripting-apis><span class=secno>1.9.2 </span>Common pitfalls to avoid when using the scripting APIs</h4>
 
   <p><i>This section is non-normative.</i></p>
 
+  <p>Scripts in HTML have "run-to-completion" semantics, meaning that
+  the browser will generally run the script uninterrupted before doing
+  anything else, such as firing further events or continuing to parse
+  the document.</p>
+
+  <p>On the other hand, parsing of HTML files happens asynchronously
+  and incrementally, meaning that the parser can pause at any point to
+  let scripts run. This is generally a good thing, but it does mean
+  that authors need to be careful to avoid hooking event handlers
+  after the events could have possibly fired.</p>
+
+  <p>There are two techniques for doing this reliably: use <a href=#event-handler-content-attributes>event
+  handler content attributes</a>, or create the element and add the
+  event handlers in the same script. The latter is safe because, as
+  mentioned earlier, scripts are run to completion before further
+  events can fire.</p>
+
+  <div class=example>
+
+   <p>One way this could manifest itself is with <code><a href=#the-img-element>img</a></code>
+   elements and the <code title=event-load>load</code> event. The
+   event could fire as soon as the element has been parsed, especially
+   if the image has already been cached (which is common).</p>
+
+   <p>Here, the author uses the <code title=handler-onload><a href=#handler-onload>onload</a></code> handler on an <code><a href=#the-img-element>img</a></code>
+   element to catch the <code title=event-load>load</code> event:</p>
+
+   <pre><img src="games.png" alt="Games" onload="gamesLogoHasLoaded(event)"></pre>
+
+   <p>If the element is being added by script, then so long as the
+   event handlers are added in the same script, the event will still
+   not be missed:</p>
+
+   <pre><script>
+ var img = new Image();
+ img.src = 'games.png';
+ img.alt = 'Games';
+ img.onload = gamesLogoHasLoaded;
+ // img.addEventListener('load', gamesLogoHasLoaded, false); // would work also
+</script></pre>
+
+   <p>However, if the author first created the <code><a href=#the-img-element>img</a></code>
+   element and then in a separate script added the event listeners,
+   there's a chance that the <code title=event-load>load</code>
+   event would be fired in between, leading it to be missed:</p>
+
+   <pre class=bad><!-- Do not use this style, it has a race condition! -->
+ <img id="games" src="games.png" alt="Games">
+ <!-- the 'load' event might fire here while the parser is taking a
+      break, in which case you will not see it! -->
+ <script>
+  var img = document.getElementById('games');
+  img.onload = gamesLogoHasLoaded; // might never fire!
+ </script></pre>
+
+  </div>
+
+
+
+  <h3 id=conformance-requirements-for-authors><span class=secno>1.10 </span>Conformance requirements for authors</h3>
+
+  <p><i>This section is non-normative.</i></p>
+
   <p>Unlike previous versions of the HTML specification, this
   specification defines in some detail the required processing for
   invalid documents as well as valid documents.</p> <!-- This has led

Modified: source
===================================================================
--- source	2011-08-11 21:12:41 UTC (rev 6420)
+++ source	2011-08-11 21:42:43 UTC (rev 6421)
@@ -1098,6 +1098,71 @@
   </dl>
 
 
+
+  <h4>Common pitfalls to avoid when using the scripting APIs</h4>
+
+  <!--END dev-html--><p><i>This section is non-normative.</i></p><!--START dev-html-->
+
+  <p>Scripts in HTML have "run-to-completion" semantics, meaning that
+  the browser will generally run the script uninterrupted before doing
+  anything else, such as firing further events or continuing to parse
+  the document.</p>
+
+  <p>On the other hand, parsing of HTML files happens asynchronously
+  and incrementally, meaning that the parser can pause at any point to
+  let scripts run. This is generally a good thing, but it does mean
+  that authors need to be careful to avoid hooking event handlers
+  after the events could have possibly fired.</p>
+
+  <p>There are two techniques for doing this reliably: use <span>event
+  handler content attributes</span>, or create the element and add the
+  event handlers in the same script. The latter is safe because, as
+  mentioned earlier, scripts are run to completion before further
+  events can fire.</p>
+
+  <div class="example">
+
+   <p>One way this could manifest itself is with <code>img</code>
+   elements and the <code title="event-load">load</code> event. The
+   event could fire as soon as the element has been parsed, especially
+   if the image has already been cached (which is common).</p>
+
+   <p>Here, the author uses the <code
+   title="handler-onload">onload</code> handler on an <code>img</code>
+   element to catch the <code title="event-load">load</code> event:</p>
+
+   <pre><img src="games.png" alt="Games" onload="gamesLogoHasLoaded(event)"></pre>
+
+   <p>If the element is being added by script, then so long as the
+   event handlers are added in the same script, the event will still
+   not be missed:</p>
+
+   <pre><script>
+ var img = new Image();
+ img.src = 'games.png';
+ img.alt = 'Games';
+ img.onload = gamesLogoHasLoaded;
+ // img.addEventListener('load', gamesLogoHasLoaded, false); // would work also
+</script></pre>
+
+   <p>However, if the author first created the <code>img</code>
+   element and then in a separate script added the event listeners,
+   there's a chance that the <code title="event-load">load</code>
+   event would be fired in between, leading it to be missed:</p>
+
+   <pre class="bad"><!-- Do not use this style, it has a race condition! -->
+ <img id="games" src="games.png" alt="Games">
+ <!-- the 'load' event might fire here while the parser is taking a
+      break, in which case you will not see it! -->
+ <script>
+  var img = document.getElementById('games');
+  img.onload = gamesLogoHasLoaded; // might never fire!
+ </script></pre>
+
+  </div>
+
+
+
   <h3>Conformance requirements for authors</h3>
 
   <!--END dev-html--><p><i>This section is non-normative.</i></p><!--START dev-html-->




More information about the Commit-Watchers mailing list