Skip to content

Commit

Permalink
Merge DOMStringMap into the data-* section
Browse files Browse the repository at this point in the history 
Previously DOMStringMap had an overly-generic architecture, meant to
serve both the microdata API and data-* attributes. Since the microdata
API is now removed, and since this is a horrible interface which nobody
should ever use in the future, we can safely un-genericize it and merge
it into the section on data-* attributes.

In the process, made some minor updates to the algorithms to increase
precision, and cross-linked the XML Name production in a few other
places in the document.
  • Loading branch information
@domenic @annevk
domenic authored and annevk committed May 25, 2016
1 parent 9b4394f commit 177b8a5
Showing 1 changed file with 133 additions and 160 deletions.
293 changes: 133 additions & 160 deletions source
View file
Expand Up @@ -2120,9 +2120,9 @@ a.setAttribute('href', 'http://example.com/'); // change the content attribute d
type <code>button</code>, meaning they have the local name "<code data-x="">button</code>" and
(implicitly as defined above) the <span>HTML namespace</span>.</p>

<p>Attribute names are said to be <dfn>XML-compatible</dfn> if they match the <a
href="https://www.w3.org/TR/xml/#NT-Name"><code data-x="">Name</code></a> production defined in XML
and they contain no U+003A COLON characters (:). <ref spec=XML></p>
<p>Attribute names are said to be <dfn>XML-compatible</dfn> if they match the <code
data-x="xml-Name">Name</code> production defined in XML and they contain no U+003A COLON
characters (:). <ref spec=XML></p>

<p>The term <dfn>XML MIME type</dfn> is used to refer to the <span data-x="MIME type">MIME
types</span> <code>text/xml</code>, <code>application/xml</code>, and any <span>MIME type</span>
Expand Down Expand Up @@ -2670,6 +2670,10 @@ a.setAttribute('href', 'http://example.com/'); // change the content attribute d
data-x="attr-xml-space">xml:space</code></dfn> in the <span>XML namespace</span> is defined by
the XML specification. <ref spec=XML></p>

<p>The <dfn data-x-href="https://www.w3.org/TR/xml/#NT-Name"><code
data-x="xml-Name">Name</code></dfn> production is defined in the XML specification. <ref
spec=XML></p>

<p>This specification also references the <dfn data-noexport=""
data-x-href="https://www.w3.org/TR/xml-stylesheet/#the-xml-stylesheet-processing-instruction"><code>&lt;?xml-stylesheet?></code></dfn>
processing instruction, defined in the <cite>Associating Style Sheets with XML documents</cite>
Expand Down Expand Up @@ -7940,80 +7944,6 @@ http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E..
</div>


<!--TOPIC:DOM APIs-->
<h4>The <code>DOMStringMap</code> interface</h4>

<p>The <code>DOMStringMap</code> interface represents a set of name-value pairs. It exposes these
using the scripting language's native mechanisms for property access.</p>

<div w-nodev>

<p>When a <code>DOMStringMap</code> object is instantiated, it is associated with three
algorithms, one for <dfn>getting the list of name-value pairs</dfn>, one for <dfn>setting names to
certain values</dfn> (given a <var>name</var> and <var>value</var>), and one for <dfn>deleting
names</dfn> (given a <var>name</var>).</p>

<pre class="idl">[OverrideBuiltins]
interface <dfn>DOMStringMap</dfn> {
<a href="#dom-domstringmap-nameditem">getter</a> DOMString (DOMString name);
[<span>CEReactions</span>] <a href="#dom-domstringmap-setitem">setter</a> void (DOMString name, DOMString value);
[<span>CEReactions</span>] <a href="#dom-domstringmap-removeitem">deleter</a> void (DOMString name);
};</pre>

<p>The <span>supported property names</span> on a <code>DOMStringMap</code> object at any instant
are the names of each pair returned from the algorithm for <span>getting the list of name-value
pairs</span> at that instant, in the order returned.</p>

<p id="dom-domstringmap-nameditem">To <span>determine the value of a named property</span>
<var>name</var> for a <code>DOMStringMap</code>, the user agent must return the value component of
the name-value pair whose name component is <var>name</var> in the list returned by the algorithm
for <span>getting the list of name-value pairs</span>.</p>

<p id="dom-domstringmap-setitem">To <span>set the value of a new named property</span> or
<span>set the value of an existing named property</span> for a <code>DOMStringMap</code>, given a
property name <var>name</var> and a new value <var>value</var>, the <code>DOMStringMap</code>'s
algorithm for <span>setting names to certain values</span> must be run, passing <var>name</var>
and <var>value</var>.</p>

<p id="dom-domstringmap-removeitem">To <span>delete an existing named property</span>
<var>name</var> for a <code>DOMStringMap</code>, the <code>DOMStringMap</code>'s algorithm for
<span>deleting names</span> must be run, passing <var>name</var> as the name.</p>

</div>

<div class="example">

<p>The <code data-x="dom-dataset">dataset</code> attribute on elements exposes the <code
data-x="attr-data-*">data-*</code> attributes on the element.</p>

<p>Given the following fragment and elements with similar constructions:</p>

<pre>&lt;img class="tower" id="tower5" data-<!---->x="12" data-y="5"
data-ai="robotarget" data-hp="46" data-ability="flames"
src="towers/rocket.png" alt="Rocket Tower"></pre>

<p>...one could imagine a function <code
data-x="">splashDamage()</code> that takes some arguments, the first
of which is the element to process:</p>

<pre>function splashDamage(node, x, y, damage) {
if (node.classList.contains('tower') && // checking the 'class' attribute
node.dataset.x == x && // reading the 'data-x' attribute
node.dataset.y == y) { // reading the 'data-y' attribute
var hp = parseInt(node.dataset.hp); // reading the 'data-hp' attribute
hp = hp - damage;
if (hp &lt; 0) {
hp = 0;
node.dataset.ai = 'dead'; // setting the 'data-ai' attribute
delete node.dataset.ability; // removing the 'data-ability' attribute
}
node.dataset.hp = hp; // setting the 'data-hp' attribute
}
}</pre>

</div>


<div w-nodev>

<h4>Garbage collection</h4>
Expand Down Expand Up @@ -11654,6 +11584,36 @@ translate="no">HTML&lt;/span> markup.&lt;/p></pre>
<p>Every <span data-x="HTML elements">HTML element</span> may have any number of <span
data-x="custom data attribute">custom data attributes</span> specified, with any value.</p>

<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>

<div w-nodev>

<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>

</div>

<p>JavaScript libraries may use the <span data-x="custom data attribute">custom data
attributes</span>, as they are considered to be part of the page on which they are used. Authors
of libraries that are reused by many authors are encouraged to include their name in the attribute
names, to reduce the risk of clashes. Where it makes sense, library authors are also encouraged to
make the exact name used in the attribute names customizable, so that libraries whose authors
unknowingly picked the same name can be used on the same page, and so that multiple versions of a
particular library can be used on the same page even when those versions are not mutually
compatible.</p>

<div class="example">

<p>For example, a library called "DoQuery" could use attribute names like <code
data-x="">data-doquery-range</code>, and a library called "jJo" could use attributes names like
<code data-x="">data-jjo-range</code>. The jJo library could also provide an API to set which
prefix to use (e.g. <code data-x="">J.setDataPrefix('j2')</code>, making the attributes have names
like <code data-x="">data-j2-range</code>).</p>

</div>

<hr>

<dl class="domintro">
Expand All @@ -11676,91 +11636,105 @@ translate="no">HTML&lt;/span> markup.&lt;/p></pre>
<p>The <dfn><code data-x="dom-dataset">dataset</code></dfn> IDL attribute provides convenient
accessors for all the <code data-x="attr-data-*">data-*</code> attributes on an element. On
getting, the <code data-x="dom-dataset">dataset</code> IDL attribute must return a
<code>DOMStringMap</code> object, associated with the following algorithms, which expose these
attributes on their element:</p>
<code>DOMStringMap</code> whose associated element is this element.</p>

<dl>

<dt>The algorithm for <span>getting the list of name-value pairs</span></dt>
</div>

<dd>
<ol>
<p>The <code>DOMStringMap</code> interface is used for the <code
data-x="dom-dataset">dataset</code> attribute. Each <code>DOMStringMap</code> has an <dfn
data-x="concept-DOMStringMap-element">associated element</dfn>.</p>

<li>Let <var>list</var> be an empty list of name-value
pairs.</li>
<pre class="idl">[OverrideBuiltins]
interface <dfn>DOMStringMap</dfn> {
<a href="#dom-domstringmap-namedItem">getter</a> DOMString (DOMString name);
[<span>CEReactions</span>] <a href="#dom-domstringmap-setitem">setter</a> void (DOMString name, DOMString value);
[<span>CEReactions</span>] <a href="#dom-domstringmap-removeitem">deleter</a> void (DOMString name);
};</pre>

<li>For each content attribute on the element whose first five characters are the string "<code
data-x="">data-</code>" and whose remaining characters (if any) do not include any
<span>uppercase ASCII letters</span>, in the order that those attributes are listed in the
element's <span>attribute list</span>, add a name-value pair to <var>list</var> whose
name is the attribute's name with the first five characters removed and whose value is the
attribute's value.</li>
<div w-nodev>

<li>For each name in <var>list</var>, for each U+002D HYPHEN-MINUS character (-) in the
name that is followed by a <span data-x="lowercase ASCII letters">lowercase ASCII letter</span>,
remove the U+002D HYPHEN-MINUS character (-) and replace the character that followed it by the
same character <span>converted to ASCII uppercase</span>.</li>
<p>To <dfn data-x="concept-DOMStringMap-pairs">get a <code>DOMStringMap</code>'s name-value
pairs</dfn>, run the following algorithm:</p>

<li>Return <var>list</var>.</li>
<ol>

</ol>
</dd>
<li><p>Let <var>list</var> be an empty list of name-value pairs.</p></li>

<dt>The algorithm for <span>setting names to certain values</span></dt>
<li><p>For each content attribute on the <code>DOMStringMap</code>'s <span
data-x="concept-DOMStringMap-element">associated element</span> whose first five characters are
the string "<code data-x="">data-</code>" and whose remaining characters (if any) do not include
any <span>uppercase ASCII letters</span>, in the order that those attributes are listed in the
element's <span>attribute list</span>, add a name-value pair to <var>list</var> whose name is the
attribute's name with the first five characters removed and whose value is the attribute's
value.</p></li>

<dd>
<ol>
<li><p>For each name in <var>list</var>, for each U+002D HYPHEN-MINUS character (-) in the
name that is followed by a <span data-x="lowercase ASCII letters">lowercase ASCII letter</span>,
remove the U+002D HYPHEN-MINUS character (-) and replace the character that followed it by the
same character <span>converted to ASCII uppercase</span>.</p></li>

<li>Let <var>name</var> be the name passed to the algorithm.</li>
<li><p>Return <var>list</var>.</p></li>
</ol>

<li>Let <var>value</var> be the value passed to the algorithm.</li>
<p>The <span>supported property names</span> on a <code>DOMStringMap</code> object at any instant
are the names of each pair returned from <span data-x="concept-DOMStringMap-pairs">getting the
<code>DOMStringMap</code>'s name-value pairs</span> at that instant, in the order returned.</p>

<li>If <var>name</var> contains a U+002D HYPHEN-MINUS character (-) followed by a
<span data-x="lowercase ASCII letters">lowercase ASCII letter</span>, throw a
<span>"<code>SyntaxError</code>"</span> <code>DOMException</code> and abort these steps.</li>
<p id="dom-domstringmap-nameditem">To <span>determine the value of a named property</span>
<var>name</var> for a <code>DOMStringMap</code>, return the value component of the name-value pair
whose name component is <var>name</var> in the list returned from <span
data-x="concept-DOMStringMap-pairs">getting the <code>DOMStringMap</code>'s name-value
pairs</span>.</p>

<li>For each <span data-x="uppercase ASCII letters">uppercase ASCII letter</span> in <var>name</var>, insert a U+002D HYPHEN-MINUS character (-) before the character and
replace the character with the same character <span>converted to ASCII lowercase</span>.</li>
<p id="dom-domstringmap-setitem">To <span>set the value of a new named property</span> or
<span>set the value of an existing named property</span> for a <code>DOMStringMap</code>, given a
property name <var>name</var> and a new value <var>value</var>, run the following steps:</p>

<li>Insert the string <code data-x="">data-</code> at the front of <var>name</var>.</li>
<ol>
<li><p>If <var>name</var> contains a U+002D HYPHEN-MINUS character (-) followed by a
<span data-x="lowercase ASCII letters">lowercase ASCII letter</span>, then throw a
<span>"<code>SyntaxError</code>"</span> <code>DOMException</code> and abort these steps.</p></li>

<li>Set the value of the attribute with the name <var>name</var>, to the value <var>value</var>, replacing any previous value if the attribute already existed. If <code
data-x="">setAttribute()</code> would have thrown an exception when setting an attribute with
the name <var>name</var>, then this must throw the same exception.</li>
<li><p>For each <span data-x="uppercase ASCII letters">uppercase ASCII letter</span> in
<var>name</var>, insert a U+002D HYPHEN-MINUS character (-) before the character and replace the
character with the same character <span>converted to ASCII lowercase</span>.</p></li>

</ol>
</dd>
<li><p>Insert the string <code data-x="">data-</code> at the front of <var>name</var>.</p></li>

<dt>The algorithm for <span>deleting names</span></dt>
<li><p>If <var>name</var> does not match the XML <code data-x="xml-Name">Name</code> production,
throw an <span>"<code>InvalidCharacterError</code>"</span> <code>DOMException</code> and abort
these steps.</p></li>

<dd>
<ol>
<li><p><span data-x="concept-element-attributes-set-value">Set an attribute value</span> for the
<code>DOMStringMap</code>'s <span data-x="concept-DOMStringMap-element">associated element</span>
using <var>name</var> and <var>value</var>.</p></li>
</ol>

<li>Let <var>name</var> be the name passed to the algorithm.</li>
<p id="dom-domstringmap-removeitem">To <span>delete an existing named property</span>
<var>name</var> for a <code>DOMStringMap</code>, run the following steps:</p>

<ol>
<!--(can't happen while the DOMStringMap deleter has no name)
<li>If <var>name</var> contains a U+002D HYPHEN-MINUS character (-) followed by a
<span data-x="lowercase ASCII letters">lowercase ASCII letter</span>, throw a
<span>"<code>SyntaxError</code>"</span> <code>DOMException</code> and abort these steps.</li>
<li><p>If <var>name</var> contains a U+002D HYPHEN-MINUS character (-) followed by a
<span data-x="lowercase ASCII letters">lowercase ASCII letter</span>, throw a
<span>"<code>SyntaxError</code>"</span> <code>DOMException</code> and abort these steps.</p></li>
-->

<li>For each <span data-x="uppercase ASCII letters">uppercase ASCII letter</span> in <var>name</var>, insert a U+002D HYPHEN-MINUS character (-) before the character and
replace the character with the same character <span>converted to ASCII lowercase</span>.</li>

<li>Insert the string <code data-x="">data-</code> at the front of <var>name</var>.</li>
<li><p>For each <span data-x="uppercase ASCII letters">uppercase ASCII letter</span> in
<var>name</var>, insert a U+002D HYPHEN-MINUS character (-) before the character and replace the
character with the same character <span>converted to ASCII lowercase</span>.</p></li>

<li>Remove the attribute with the name <var>name</var>, if such an attribute exists.
Do nothing otherwise.</li>
<li><p>Insert the string <code data-x="">data-</code> at the front of <var>name</var>.</p></li>

</ol>

<p class="note">This algorithm will only get invoked by the Web IDL specification for names that
are given by the earlier algorithm for <span>getting the list of name-value pairs</span>. <ref
spec=WEBIDL></p>

</dd>
<li><p><span data-x="concept-element-attributes-remove">Remove an attribute by name</span> given
<var>name</var> and the <code>DOMStringMap</code>'s <span
data-x="concept-DOMStringMap-element">associated element</span>.</p></li>
</ol>

</dl>
<p class="note">This algorithm will only get invoked by the Web IDL specification for names that
are given by the earlier algorithm for <span data-x="concept-DOMStringMap-pairs">getting the
<code>DOMStringMap</code>'s name-value pairs</span>. <ref
spec=WEBIDL></p>

</div>

Expand All @@ -11783,33 +11757,32 @@ translate="no">HTML&lt;/span> markup.&lt;/p></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>

<div w-nodev>

<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>
<div class="example">

</div>
<p>Given the following fragment and elements with similar constructions:</p>

<p>JavaScript libraries may use the <span data-x="custom data attribute">custom data
attributes</span>, as they are considered to be part of the page on which they are used. Authors
of libraries that are reused by many authors are encouraged to include their name in the attribute
names, to reduce the risk of clashes. Where it makes sense, library authors are also encouraged to
make the exact name used in the attribute names customizable, so that libraries whose authors
unknowingly picked the same name can be used on the same page, and so that multiple versions of a
particular library can be used on the same page even when those versions are not mutually
compatible.</p>
<pre>&lt;img class="tower" id="tower5" data-<!---->x="12" data-y="5"
data-ai="robotarget" data-hp="46" data-ability="flames"
src="towers/rocket.png" alt="Rocket Tower"></pre>

<div class="example">
<p>...one could imagine a function <code
data-x="">splashDamage()</code> that takes some arguments, the first
of which is the element to process:</p>

<p>For example, a library called "DoQuery" could use attribute names like <code
data-x="">data-doquery-range</code>, and a library called "jJo" could use attributes names like
<code data-x="">data-jjo-range</code>. The jJo library could also provide an API to set which
prefix to use (e.g. <code data-x="">J.setDataPrefix('j2')</code>, making the attributes have names
like <code data-x="">data-j2-range</code>).</p>
<pre>function splashDamage(node, x, y, damage) {
if (node.classList.contains('tower') && // checking the 'class' attribute
node.dataset.x == x && // reading the 'data-x' attribute
node.dataset.y == y) { // reading the 'data-y' attribute
var hp = parseInt(node.dataset.hp); // reading the 'data-hp' attribute
hp = hp - damage;
if (hp &lt; 0) {
hp = 0;
node.dataset.ai = 'dead'; // setting the 'data-ai' attribute
delete node.dataset.ability; // removing the 'data-ability' attribute
}
node.dataset.hp = hp; // setting the 'data-hp' attribute
}
}</pre>

</div>

Expand Down Expand Up @@ -107981,7 +107954,7 @@ document.body.appendChild(text);
can get adjusted, so this isn't an excuse) -->

<li>A node with a <!--prefix or--> local name that does not match the XML <code
data-x="">Name</code> production. <ref spec=XML></li> <!--(again, prefixes can get
data-x="xml-Name">Name</code> production. <ref spec=XML></li> <!--(again, prefixes can get
adjusted, so this isn't an excuse) -->

<li>An <code>Attr</code> node with no namespace whose local name is the lowercase string "<code
Expand Down

0 comments on commit 177b8a5

Please sign in to comment.