html5/spec Overview.html,1.5125,1.5126

Update of /sources/public/html5/spec
In directory hutz:/tmp/cvs-serv17176

Modified Files:
	Overview.html 
Log Message:
An intro section on avoiding common pitfalls with scripts. File bugs if you have ideas of other things to mention here. (whatwg r6421)

Index: Overview.html
===================================================================
RCS file: /sources/public/html5/spec/Overview.html,v
retrieving revision 1.5125
retrieving revision 1.5126
diff -u -d -r1.5125 -r1.5126
--- Overview.html	11 Aug 2011 21:12:54 -0000	1.5125
+++ Overview.html	11 Aug 2011 21:42:56 -0000	1.5126
@@ -495,7 +495,8 @@
      <li><a href="#typographic-conventions"><span class="secno">1.7.2 </span>Typographic conventions</a></ol></li>
    <li><a href="#a-quick-introduction-to-html"><span class="secno">1.8 </span>A quick introduction to HTML</a>
     <ol>
-     <li><a href="#writing-secure-applications-with-html"><span class="secno">1.8.1 </span>Writing secure applications with HTML</a></ol></li>
+     <li><a href="#writing-secure-applications-with-html"><span class="secno">1.8.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.8.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.9 </span>Conformance requirements for authors</a>
     <ol>
      <li><a href="#presentational-markup"><span class="secno">1.9.1 </span>Presentational markup</a></li>
@@ -1833,7 +1834,56 @@
 
    </dd>
 
-  </dl><h3 id="conformance-requirements-for-authors"><span class="secno">1.9 </span>Conformance requirements for authors</h3><p><i>This section is non-normative.</i><p>Unlike previous versions of the HTML specification, this
+  </dl><h4 id="common-pitfalls-to-avoid-when-using-the-scripting-apis"><span class="secno">1.8.2 </span>Common pitfalls to avoid when using the scripting APIs</h4><p><i>This section is non-normative.</i><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>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>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.<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>&lt;img src="games.png" alt="Games" onload="gamesLogoHasLoaded(event)"&gt;</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>&lt;script&gt;
+ var img = new Image();
+ img.src = 'games.png';
+ img.alt = 'Games';
+ img.onload = gamesLogoHasLoaded;
+ // img.addEventListener('load', gamesLogoHasLoaded, false); // would work also
+&lt;/script&gt;</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">&lt;!-- Do not use this style, it has a race condition! --&gt;
+ &lt;img id="games" src="games.png" alt="Games"&gt;
+ &lt;!-- the 'load' event might fire here while the parser is taking a
+      break, in which case you will not see it! --&gt;
+ &lt;script&gt;
+  var img = document.getElementById('games');
+  img.onload = gamesLogoHasLoaded; // might never fire!
+ &lt;/script&gt;</pre>
+
+  </div><h3 id="conformance-requirements-for-authors"><span class="secno">1.9 </span>Conformance requirements for authors</h3><p><i>This section is non-normative.</i><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><p>However, even though the processing of invalid content is in most
   cases well-defined, conformance requirements for documents are still

Received on Thursday, 11 August 2011 21:43:02 UTC