[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