[html5] r1399 - /

whatwg at whatwg.org whatwg at whatwg.org
Fri Apr 4 17:07:36 PDT 2008


Author: ianh
Date: 2008-04-04 17:07:36 -0700 (Fri, 04 Apr 2008)
New Revision: 1399

Modified:
   index
   source
Log:
[] (0) A mechanism for embedding custom non-visible data in an HTML document for scripting purposes

Modified: index
===================================================================
--- index	2008-04-01 07:26:32 UTC (rev 1398)
+++ index	2008-04-05 00:07:36 UTC (rev 1399)
@@ -24,7 +24,7 @@
 
    <h1 id=html-5>HTML 5</h1>
 
-   <h2 class="no-num no-toc" id=working>Working Draft — 1 April 2008</h2>
+   <h2 class="no-num no-toc" id=working>Working Draft — 5 April 2008</h2>
 
    <p>You can take part in this work. <a
     href="http://www.whatwg.org/mailing-list">Join the working group's
@@ -231,7 +231,10 @@
        <li><a href="#domtokenlist"><span class=secno>2.3.2
         </span>DOMTokenList</a>
 
-       <li><a href="#dom-feature"><span class=secno>2.3.3 </span>DOM feature
+       <li><a href="#domstringmap"><span class=secno>2.3.3
+        </span>DOMStringMap</a>
+
+       <li><a href="#dom-feature"><span class=secno>2.3.4 </span>DOM feature
         strings</a>
       </ul>
 
@@ -374,6 +377,9 @@
 
        <li><a href="#the-irrelevant"><span class=secno>3.4.6 </span>The
         <code>irrelevant</code> attribute</a>
+
+       <li><a href="#embedding"><span class=secno>3.4.7 </span>Embedding
+        custom non-visible data</a>
       </ul>
 
      <li><a href="#interaction"><span class=secno>3.5 </span>Interaction</a>
@@ -2839,6 +2845,7 @@
            attribute DOMString <a href="#dir0" title=dom-dir>dir</a>;
            attribute <span>DOMString</span> <a href="#classname" title=dom-className>className</a>;
   readonly attribute <a href="#domtokenlist0">DOMTokenList</a> <a href="#classlist" title=dom-classList>classList</a>;
+  readonly attribute <a href="#domstringmap0">DOMStringMap</a> <a href="#dataset" title=dom-dataSet>dataSet</a>;
 
   // <a href="#interaction0">interaction</a>
            attribute boolean <a href="#irrelevant0" title=dom-irrelevant>irrelevant</a>;
@@ -3437,8 +3444,44 @@
    href="#domtokenlist0">DOMTokenList</a></code> interface must stringify to
    the object's underlying string representation.
 
-  <h4 id=dom-feature><span class=secno>2.3.3 </span>DOM feature strings</h4>
+  <h4 id=domstringmap><span class=secno>2.3.3 </span>DOMStringMap</h4>
 
+  <p>The <code><a href="#domstringmap0">DOMStringMap</a></code> interface
+   represents a set of name-value pairs. When a <code><a
+   href="#domstringmap0">DOMStringMap</a></code> object is instanced, it is
+   associated with three algorithms, one for getting values from names, one
+   for setting names to certain values, and one for deleting names.
+
+  <p class=big-issue>The names of the methods on this interface are temporary
+   and will be fixed when the "Language Bindings for DOM Specifications" spec
+   is ready to handle this case.
+
+  <pre class=idl>interface <dfn id=domstringmap0>DOMStringMap</dfn> {
+  DOMString <a href="#getname" title="dom-stringmap-[[Get]]">[[Get]]</a>(in DOMString name);
+  void <a href="#putname" title="dom-stringmap-[[Put]]">[[Put]]</a>(in DOMString name, in DOMString value);
+  bool <a href="#delete" title="dom-stringmap-[[Delete]]">[[Delete]]</a>(in DOMString name);
+};</pre>
+
+  <p>The <dfn id=getname title="dom-stringmap-[[Get]]"><code>[[Get]](<var
+   title="">name</var>)</code></dfn> method must call the algorithm for
+   getting values from names, passing <var title="">name</var> as the name,
+   and must return the corresponding value, or null if <var
+   title="">name</var> has no corresponding value.
+
+  <p>The <dfn id=putname title="dom-stringmap-[[Put]]"><code>[[Put]](<var
+   title="">name</var>, <var title="">value</var>)</code></dfn> method must
+   call the algorithm for setting names to certain values, passing <var
+   title="">name</var> as the name and <var title="">value</var> as the
+   value.
+
+  <p>The <dfn id=delete
+   title="dom-stringmap-[[Delete]]"><code>[[Delete]](<var
+   title="">name</var>)</code></dfn> method must call the algorithm for
+   deleting names, passing <var title="">name</var> as the name, and must
+   return true.
+
+  <h4 id=dom-feature><span class=secno>2.3.4 </span>DOM feature strings</h4>
+
   <p>DOM3 Core defines mechanisms for checking for interface support, and for
    obtaining implementations of interfaces, using <a
    href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#DOMFeatures">feature
@@ -6426,6 +6469,10 @@
    <dd><code title=handler-onunload><a href="#onunload">onunload</a></code>
   </dl>
 
+  <p>Finally, any attribute starting with the string "<code
+   title="attr-data-*"><a href="#data-">data-</a></code>" may be specified on
+   any <span>HTML element</span>, to store custom data specific to the page.
+
   <h4 id=the-id><span class=secno>3.4.1 </span>The <dfn id=id
    title=attr-id><code>id</code></dfn> attribute</h4>
 
@@ -6676,6 +6723,99 @@
    title=dom-irrelevant><code>irrelevant</code></dfn> DOM attribute must <a
    href="#reflect">reflect</a> the content attribute of the same name.
 
+  <h4 id=embedding><span class=secno>3.4.7 </span><dfn
+   id=embedding0>Embedding custom non-visible data</dfn></h4>
+
+  <p>Every <a href="#html-elements" title="HTML elements">HTML element</a>
+   may have any number of attributes starting with the string "<dfn id=data-
+   title="attr-data-*"><code>data-</code></dfn>" specified, with any value.
+
+  <p>These are intended to store custom data private to the page or
+   application, for which there are no more appropriate attributes or
+   elements.
+
+  <p>The <dfn id=dataset title=dom-dataSet><code>dataSet</code></dfn> DOM
+   attribute provides convenient accessors for all the <code
+   title="attr-data-*"><a href="#data-">data-*</a></code> attributes on an
+   element. On getting, the <code title=dom-dataSet><a
+   href="#dataset">dataSet</a></code> DOM attribute must return a <code><a
+   href="#domstringmap0">DOMStringMap</a></code> object, associated with the
+   following three algorithms, which expose these attributes on their
+   element:
+
+  <dl>
+   <dt>The algorithm for getting values from names
+
+   <dd>
+    <ol>
+     <li>Let <var title="">name</var> be the concatenation of the string
+      <code title="">data-</code> and the name passed to the algorithm.
+
+     <li>If the element does not have an attribute with the name <var
+      title="">name</var>, then the name has no corresponding value, abort.
+
+     <li>Otherwise, return the value of the attribute with the name <var
+      title="">name</var>.
+    </ol>
+
+   <dt>The algorithm for setting names to certain values
+
+   <dd>
+    <ol>
+     <li>Let <var title="">name</var> be the concatenation of the string
+      <code title="">data-</code> and the name passed to the algorithm.
+
+     <li>Let <var title="">value</var> be the value passed to the algorithm.
+
+     <li>Set the value of the attribute with the name <var
+      title="">name</var>, to the value <var title="">value</var>, replacing
+      any previous value if the attribute already existed. If <code
+      title="">setAttribute()</code> would have raised an exception when
+      setting an attribute with the name <var title="">name</var>, then this
+      must raise the same exception.
+    </ol>
+
+   <dt>The algorithm for deleting names
+
+   <dd>
+    <ol>
+     <li>Let <var title="">name</var> be the concatenation of the string
+      <code title="">data-</code> and the name passed to the algorithm.
+
+     <li>Remove the attribute with the name <var title="">name</var>, if such
+      an attribute exists. Do nothing otherwise.
+    </ol>
+  </dl>
+
+  <div class=example>
+   <p>If a Web page wanted an element to represent a space ship, e.g. as part
+    of a game, it would have to use the <code class=attr-class>class</code>
+    attribute along with <code title="attr-data-*"><a
+    href="#data-">data-*</a></code> attributes:</p>
+
+   <pre>
+<div class="spaceship" data-id="92432"
+     data-weapons="laser 2" data-shields="50%"
+     data-x="30" data-y="10" data-z="90">
+ <button class="fire"
+         onclick="spaceships[this.parentNode.dataSet.id].fire()">
+  Fire
+ </button>
+</div>
+</pre>
+  </div>
+
+  <p>Authors should carefully design such extensions so that when the
+   attributes are ignored and any associated CSS dropped, the page is still
+   usable.
+
+  <p>User agents must not derive any implementation behaviour from these
+   attributes or values. Specifications intended for user agents must not
+   define these attributes to have any meaningful values.
+
+  <p class=big-issue>So here we're saying that microformats shouldn't use
+   this... is that what we want?
+
   <h3 id=interaction><span class=secno>3.5 </span><dfn
    id=interaction0>Interaction</dfn></h3>
   <!--
@@ -36151,7 +36291,7 @@
    <dd><strong>Value:</strong> Always the string "<code
     title="">false</code>".
 
-   <dt><dfn id=delete title=command-delete><code>delete</code></dfn>
+   <dt><dfn id=delete0 title=command-delete><code>delete</code></dfn>
 
    <dd><strong>Action:</strong> The user agent must act as if the user had
     performed <a href="#contenteditable-delete">a backspace operation</a>.

Modified: source
===================================================================
--- source	2008-04-01 07:26:32 UTC (rev 1398)
+++ source	2008-04-05 00:07:36 UTC (rev 1399)
@@ -1188,6 +1188,7 @@
            attribute DOMString <span title="dom-dir">dir</span>;
            attribute <span>DOMString</span> <span title="dom-className">className</span>;
   readonly attribute <span>DOMTokenList</span> <span title="dom-classList">classList</span>;
+  readonly attribute <span>DOMStringMap</span> <span title="dom-dataSet">dataSet</span>;
 
   // <span>interaction</span>
            attribute boolean <span title="dom-irrelevant">irrelevant</span>;
@@ -1808,6 +1809,42 @@
   underlying string representation.</p>
 
 
+  <h4>DOMStringMap</h4>
+
+  <p>The <code>DOMStringMap</code> interface represents a set of
+  name-value pairs. When a <code>DOMStringMap</code> object is
+  instanced, it is associated with three algorithms, one for getting
+  values from names, one for setting names to certain values, and one
+  for deleting names.</p>
+
+  <p class="big-issue">The names of the methods on this interface are
+  temporary and will be fixed when the "Language Bindings for DOM
+  Specifications" spec is ready to handle this case.</p>
+
+  <pre class="idl">interface <dfn>DOMStringMap</dfn> {
+  DOMString <span title="dom-stringmap-[[Get]]">[[Get]]</span>(in DOMString name);
+  void <span title="dom-stringmap-[[Put]]">[[Put]]</span>(in DOMString name, in DOMString value);
+  bool <span title="dom-stringmap-[[Delete]]">[[Delete]]</span>(in DOMString name);
+};</pre>
+
+  <p>The <dfn title="dom-stringmap-[[Get]]"><code>[[Get]](<var
+  title="">name</var>)</code></dfn> method must call the algorithm for
+  getting values from names, passing <var title="">name</var> as the
+  name, and must return the corresponding value, or null if <var
+  title="">name</var> has no corresponding value.</p>
+
+  <p>The <dfn title="dom-stringmap-[[Put]]"><code>[[Put]](<var
+  title="">name</var>, <var title="">value</var>)</code></dfn> method
+  must call the algorithm for setting names to certain values, passing
+  <var title="">name</var> as the name and <var title="">value</var>
+  as the value.</p>
+
+  <p>The <dfn title="dom-stringmap-[[Delete]]"><code>[[Delete]](<var
+  title="">name</var>)</code></dfn> method must call the algorithm for
+  deleting names, passing <var title="">name</var> as the name, and
+  must return true.</p>
+
+
   <h4>DOM feature strings</h4>
 
   <p>DOM3 Core defines mechanisms for checking for interface support,
@@ -4908,7 +4945,11 @@
    <dd><code title="handler-onunload">onunload</code></dd>
   </dl>
 
+  <p>Finally, any attribute starting with the string "<code
+  title="attr-data-*">data-</code>" may be specified on any <span>HTML
+  element</span>, to store custom data specific to the page.</p>
 
+
   <h4>The <dfn title="attr-id"><code>id</code></dfn> attribute</h4>
 
   <p>The <code title="attr-id">id</code> attribute represents its
@@ -5161,6 +5202,118 @@
   same name.</p>
 
 
+  <h4><dfn>Embedding custom non-visible data</dfn></h4>
+
+  <p>Every <span title="HTML elements">HTML element</span> may have
+  any number of attributes starting with the string "<dfn
+  title="attr-data-*"><code>data-</code></dfn>" specified, with any
+  value.</p>
+
+  <p>These are intended to store custom data private to the page or
+  application, for which there are no more appropriate attributes or
+  elements.</p>
+
+  <p>The <dfn title="dom-dataSet"><code>dataSet</code></dfn> DOM
+  attribute provides convenient accessors for all the <code
+  title="attr-data-*">data-*</code> attributes on an element.  On
+  getting, the <code title="dom-dataSet">dataSet</code> DOM attribute
+  must return a <code>DOMStringMap</code> object, associated with the
+  following three algorithms, which expose these attributes on their
+  element:</p>
+
+  <dl>
+
+   <dt>The algorithm for getting values from names</dt>
+
+   <dd>
+    <ol>
+
+     <li>Let <var title="">name</var> be the concatenation of the
+     string <code title="">data-</code> and the name passed to the
+     algorithm.</li>
+
+     <li>If the element does not have an attribute with the name <var
+     title="">name</var>, then the name has no corresponding value,
+     abort.</li>
+
+     <li>Otherwise, return the value of the attribute with the name
+     <var title="">name</var>.</li>
+
+    </ol>
+   </dd>
+
+   <dt>The algorithm for setting names to certain values</dt>
+
+   <dd>
+    <ol>
+
+     <li>Let <var title="">name</var> be the concatenation of the
+     string <code title="">data-</code> and the name passed to the
+     algorithm.</li>
+
+     <li>Let <var title="">value</var> be the value passed to the
+     algorithm.</li>
+
+     <li>Set the value of the attribute with the name <var
+     title="">name</var>, to the value <var title="">value</var>,
+     replacing any previous value if the attribute already existed. If
+     <code title="">setAttribute()</code> would have raised an
+     exception when setting an attribute with the name <var
+     title="">name</var>, then this must raise the same
+     exception.</li>
+
+    </ol>
+   </dd>
+
+   <dt>The algorithm for deleting names</dt>
+
+   <dd>
+    <ol>
+
+     <li>Let <var title="">name</var> be the concatenation of the
+     string <code title="">data-</code> and the name passed to the
+     algorithm.</li>
+
+     <li>Remove the attribute with the name <var title="">name</var>,
+     if such an attribute exists. Do nothing otherwise.</li>
+
+    </ol>
+   </dd>
+
+  </dl>
+
+  <div class="example">
+
+   <p>If a Web page wanted an element to represent a space ship,
+   e.g. as part of a game, it would have to use the <code
+   class="attr-class">class</code> attribute along with <code
+   title="attr-data-*">data-*</code> attributes:</p>
+
+   <pre>
+<div class="spaceship" data-id="92432"
+     data-weapons="laser 2" data-shields="50%"
+     data-x="30" data-y="10" data-z="90">
+ <button class="fire"
+         onclick="spaceships[this.parentNode.dataSet.id].fire()">
+  Fire
+ </button>
+</div>
+</pre>
+
+  </div>
+
+  <p>Authors should carefully design such extensions so that when the
+  attributes are ignored and any associated CSS dropped, the page is
+  still usable.</p>
+
+  <p>User agents must not derive any implementation behaviour from
+  these attributes or values. Specifications intended for user agents
+  must not define these attributes to have any meaningful values.</p>
+
+  <p class="big-issue">So here we're saying that microformats
+  shouldn't use this... is that what we want?</p>
+
+
   <h3><dfn>Interaction</dfn></h3>
 
 <!--




More information about the Commit-Watchers mailing list