[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