--- a/html/DOM3-Events.html Wed Nov 13 03:55:34 2013 +0800
+++ b/html/DOM3-Events.html Wed Nov 13 04:08:56 2013 +0800
@@ -9148,62 +9148,94 @@
<section id="extending-events-intro">
<h2>Introduction</h2>
- <p>This specification defines several interfaces and many events, however, this is not an exhaustive set of events for all purposes. To allow content
- authors and implementers to add desired functionality, this specification provides two mechanisms for extend this set of interfaces and events without creating
- conflicts: <a href="#extending-events-Custom_Events">custom events</a> and <a href="#extending-events-Impl_Extensions">implementation-specific extensions</a>.</p>
- </section>
+
+ <p>This specification defines several interfaces and many events, however, this is not
+ an exhaustive set of events for all purposes.
+ To allow content authors and implementers to add desired functionality, this specification
+ provides two mechanisms for extend this set of interfaces and events without creating conflicts:
+ <a href="#extending-events-Custom_Events">custom events</a>
+ and <a href="#extending-events-Impl_Extensions">implementation-specific extensions</a>.
+ </p>
+ </section> <!-- extending-events-intro -->
<section id="extending-events-Custom_Events">
<h2>Custom Events</h2>
- <p>A script author MAY wish to define an application in terms of functional components, with event types that are meaningful to the application architecture. The
- content author can use the <a href="#interface-CustomEvent"><code>CustomEvent</code></a> interface to create their own events appropriate to the level of abstraction
- they are using.</p>
+
+ <p>A script author MAY wish to define an application in terms of functional components, with event
+ types that are meaningful to the application architecture.
+ The content author can use the <a href="#interface-CustomEvent"><code>CustomEvent</code></a> interface
+ to create their own events appropriate to the level of abstraction they are using.
+ </p>
<div class="example">
<div class="example-title"></div>
- <p>A content author might have created an application which features a dynamically generated bar chart. This bar chart is meant to be updated
- every 5 minutes, or when a feed shows new information, or when the user refreshes it manually by clicking a button. There are several handlers that have to be
- called when the chart needs to be updated: the application has to fetch the most recent data, show an icon to the user that the event is being updated, and rebuild
- the chart. To manage this, the content author can choose to create a custom <q>updateChart</q> event, which is fired whenever one of the trigger conditions is
- met:</p>
- <pre><code>
+ <p>A content author might have created an application which features a dynamically generated bar chart.
+ This bar chart is meant to be updated every 5 minutes, or when a feed shows new information, or
+ when the user refreshes it manually by clicking a button.
+ There are several handlers that have to be called when the chart needs to be updated:
+ the application has to fetch the most recent data, show an icon to the user that the event is being
+ updated, and rebuild the chart.
+ To manage this, the content author can choose to create a custom <q>updateChart</q> event,
+ which is fired whenever one of the trigger conditions is met:
+ </p>
+<pre><code>
var chartData = ...;
var evt = document.createEvent("CustomEvent");
evt.initCustomEvent( "updateChart", true, false, { data: chartData });
document.documentElement.dispatchEvent(evt);
</code></pre>
</div>
- </section>
+ </section> <!-- extending-events-Custom_Events -->
<section id="extending-events-Impl_Extensions">
<h2>Implementation-Specific Extensions</h2>
- <p>While a new event is being designed and prototyped, or when an event is intended for implementation-specific functionality, it is desirable to distinguish it from
- standardized events. Implementors SHOULD prefix event types specific to their implementations with a short string to distinguish it from the same event in other
- implementations and from standardized events. This is similar to the <a href="http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords" title="CSS 2.1: Syntax and basic data types">
- vendor-specific keyword prefixes</a> in CSS, though without the dashes (<code>"-"</code>) used in CSS, since that can cause problems when used as an attribute
- name in Javascript.</p>
+
+ <p>While a new event is being designed and prototyped, or when an event is intended for implementation-specific
+ functionality, it is desirable to distinguish it from standardized events.
+ Implementors SHOULD prefix event types specific to their implementations with a short string to distinguish
+ it from the same event in other implementations and from standardized events.
+ This is similar to the
+ <a href="http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords" title="CSS 2.1: Syntax and basic data types">vendor-specific keyword prefixes</a>
+ in CSS, though without the dashes (<code>"-"</code>) used in CSS, since that can cause problems when used
+ as an attribute name in Javascript.
+ </p>
<div class="example">
<div class="example-title"></div>
- <p>A particular browser vendor, <q>FooCorp</q>, might wish to introduce a new event, <code class="eventtype">jump</code>. This vendor implements
- <code class="eventtype">fooJump</code> in their browser, using their vendor-specific prefix, <code>'foo'</code>. Early adopters start experimenting with the event,
- using <code>someElement.addEventListener("fooJump", doJump, false )</code>, and provide feedback to FooCorp, who change the behavior of <code class="eventtype">fooJump</code>
- accordingly.</p>
-
- <p>After some time, another vendor, <q>BarOrg</q>, decides they also want the functionality, but implement it slightly differently, so they use their own vendor-specific
- prefix, <code>"bar"</code> in their event type name, <code class="eventtype">barJump</code>. Content authors experimenting with this version of the
- <code class="eventtype">jump</code> event type register events with BarOrg's event type name. Content authors who wish to write code that accounts for both browsers
- can either register each event type separately with specific handlers, or use the same handler and switch on the name of the event type. Thus, early experiments in different
- codebases do not conflict, and the early adopter is able to write easily-maintained code for multiple implementations.</p>
-
- <p>Eventually, as the feature matures, the behavior of both browsers stabilize and might converge due to content author and user feedback or through formal standardization.
- As this stabilization occurs, and risk of conflicts decrease, content authors can remove the forked code, and use the <code class="eventtype">jump</code> event type name (even
- before it is formally standardized) using the same event handler and the more generic registration method <code>someElement.addEventListener( "jump", doJump, false)</code>.</p>
+ <p>A particular browser vendor, <q>FooCorp</q>, might wish to introduce a new event, <code class="eventtype">jump</code>.
+ This vendor implements <code class="eventtype">fooJump</code> in their browser, using their
+ vendor-specific prefix: <code>'foo'</code>.
+ Early adopters start experimenting with the event, using
+ <code>someElement.addEventListener("fooJump", doJump, false )</code>,
+ and provide feedback to FooCorp, who change the behavior of <code class="eventtype">fooJump</code> accordingly.
+ </p>
+
+ <p>After some time, another vendor, <q>BarOrg</q>, decides they also want the functionality, but implement
+ it slightly differently, so they use their own vendor-specific prefix, <code>"bar"</code> in their
+ event type name: <code class="eventtype">barJump</code>.
+ Content authors experimenting with this version of the <code class="eventtype">jump</code> event type
+ register events with BarOrg's event type name.
+ Content authors who wish to write code that accounts for both browsers can either register each event type
+ separately with specific handlers, or use the same handler and switch on the name of the event type.
+ Thus, early experiments in different codebases do not conflict, and the early adopter is able to write
+ easily-maintained code for multiple implementations.
+ </p>
+
+ <p>Eventually, as the feature matures, the behavior of both browsers stabilizes and might converge due to
+ content author and user feedback or through formal standardization.
+ As this stabilization occurs, and risk of conflicts decrease, content authors can remove the forked code,
+ and use the <code class="eventtype">jump</code> event type name (even before it is formally standardized)
+ using the same event handler and the more generic registration method
+ <code>someElement.addEventListener( "jump", doJump, false)</code>.
+ </p>
</div>
<section id="extending-events-prefixes">
<h3>Known Implementation-Specific Prefixes</h3>
- <p>At the time of writing, the following event-type name prefixes are known to exist:</p>
+
+ <p>At the time of writing, the following event-type name prefixes are known to exist:
+ </p>
+
<table border="1" cellpadding="2" cellspacing="0" summary="Known event-type name prefixes">
<thead>
<tr>
@@ -9230,8 +9262,8 @@
</tr>
</tbody>
</table>
- </section>
- </section>
+ </section> <!-- extending-events-prefixes -->
+ </section> <!-- extending-events-Impl_Extensions -->
</section> <!-- extending-events -->
<!-- Appendix E: Security Considerations ========================================================-->