[html5] r3084 - [e] (0) Finish off the microdata intro, and define the order and duplicate handl [...]

[whatwg at whatwg.org]

Author: ianh
Date: 2009-05-11 03:22:59 -0700 (Mon, 11 May 2009)
New Revision: 3084

Modified:
   index
   source
Log:
[e] (0) Finish off the microdata intro, and define the order and duplicate handling for property names.

Modified: index
===================================================================
--- index	2009-05-11 09:07:13 UTC (rev 3083)
+++ index	2009-05-11 10:22:59 UTC (rev 3084)
@@ -6525,8 +6525,10 @@
   <p>The <dfn id=dom-htmlpropertycollection-names title=dom-HTMLPropertyCollection-names><code>names</code></dfn>
   attribute must return a live <code>DOMStringList</code> object
   giving the <a href=#property-names>property names</a> of all the elements
-  <a href=#represented-by-the-collection>represented by the collection</a>. The same object must be
-  returned each time.</p>
+  <a href=#represented-by-the-collection>represented by the collection</a>, listed in <a href=#tree-order>tree
+  order</a>, but with duplicates removed, leaving only the first
+  occurrence of each name. The same object must be returned each
+  time.</p>
 
   <p>The <dfn id=dom-htmlpropertycollection-item title=dom-HTMLPropertyCollection-item><code>item(<var title="">index</var>)</code></dfn> method must return the <var title="">index</var>th node in the collection. If there is no <var title="">index</var>th node in the collection, then the method must
   return null.</p>
@@ -40880,7 +40882,8 @@
 
   <p>The <code title=dom-document-items><a href=#dom-document-items>document.items</a></code> DOM
   attribute provides access to all the <a href=#top-level-microdata-items>top-level microdata
-  items</a>.</p>
+  items</a>. This attribute returns an <code><a href=#htmlcollection-0>HTMLCollection</a></code>,
+  which can be enumerated.</p>
 
   <p>Each <a href=#concept-item title=concept-item>item</a> is represented in the
   DOM by the element on which the relevant <code title=attr-item><a href=#items:-the-item-attribute>item</a></code> attribute is found. The various types
@@ -40908,10 +40911,96 @@
 
   </div>
 
-  <!-- XXX ... -->
+  <p>Once an element representing an <a href=#concept-item title=concept-item>item</a> has been obtained, its properties
+  can be extracted using the <code title=dom-properties><a href=#dom-properties>properties</a></code> DOM attribute. This
+  attribute returns an <code><a href=#htmlpropertycollection-0>HTMLPropertyCollection</a></code>, which can
+  be enumerated to go through each element that adds one or more
+  properties to the item. It can also be indexed by name, which will
+  return the property with that name (if there is just one).</p>
 
+  <p>Each element that adds a property also has a <code title=dom-content><a href=#dom-content>content</a></code> DOM attribute that returns its
+  value.
 
+  <div class=example>
 
+   <p>This sample uses the function above to get the first item of
+   type "net.example.user" and then pops up an alert using the
+   "net.example.name" property from that item.</p>
+
+   <pre>var user = getItems('net.example.user')[0];
+alert('Hello ' + user.properties['net.example.name'].content + '!');</pre>
+
+  </div>
+
+  <p>When an item has multiple properties with the same name, the
+  <code><a href=#htmlpropertycollection-0>HTMLPropertyCollection</a></code> returns a
+  <code><a href=#propertynodelist>PropertyNodeList</a></code> object with all those properties
+  instead of returning just one. The <code><a href=#propertynodelist>PropertyNodeList</a></code>
+  object can be used to obtained all the values at once using
+  <em>its</em> <code title=dom-PropertyNodeList-content><a href=#dom-propertynodelist-content>content</a></code> attribute, which
+  returns an array of all the values.</p>
+
+  <div class=example>
+
+   <p>In an earlier example, a "com.example.feline" item had two
+   "com.example.color" values. This script looks up such items and
+   then lists all their values. Because it doesn't know ahead of time
+   if the item has zero, one, or more colors, it checks whether the
+   value returned from the <code><a href=#htmlpropertycollection-0>HTMLPropertyCollection</a></code> is a
+   <code><a href=#propertynodelist>PropertyNodeList</a></code> (multiple colors), just a regular
+   element (one color), or null (no colors) before using it.</p>
+
+   <pre>var cat = getItems('com.example.feline')[0];
+var colors = cat.properties['com.example.color'];
+var result;
+if (!colors) {
+  result = 'Color unknown.';
+} else if (colors instanceof PropertyNodeList) {
+  result = 'Colors:';
+  for (var i = 0; i 
+
+  </pre></div>
+
+  <p>It's also possible to get a list of all the <a href=#property-names>property
+  names</a> using the object's <code title=dom-HTMLPropertyCollection-names><a href=#dom-htmlpropertycollection-names>names</a></code> DOM
+  attribute.</p>
+
+  <div class=example>
+
+   <p>This example creates a big list with a nested list for each item
+   on the page, each with of all the property names used in that
+   item./p>
+
+   <pre>var outer = document.createElement('ul');
+for (var item = 0; item 
+
+   <p>If faced with the following from an earlier example:</p>
+
+   <pre><section item="org.example.animal.cat com.example.feline">
+ <h1 property="org.example.name com.example.fn">Hedral</h1>
+ <p property="org.example.desc">Hedral is a male american domestic
+ shorthair, with a fluffy <span
+ property="com.example.color">black</span> fur with <span
+ property="com.example.color">white</span> paws and belly.</p>
+ <img property="org.example.img" src="hedral.jpeg" alt="" title="Hedral, age 18 months">
+</section></pre>
+
+   <p>...it would result in the following output:</p>
+
+   </pre><ul><li>
+     <ul><li>org.example.name</li>
+      <li>com.example.fn</li>
+      <li>org.example.desc</li>
+      <li>com.example.color</li>
+      <li>org.example.img</li>
+     </ul></li>
+   </ul><p>(The duplicate occurrence of "com.example.color" is not included
+   in the list.)</p>
+
+  </div>
+
+
+
   <h3 id=encoding-microdata><span class=secno>5.2 </span>Encoding microdata</h3>
 
   <h4 id=the-microdata-model><span class=secno>5.2.1 </span>The microdata model</h4>
@@ -41034,7 +41123,9 @@
   </ul><p>The <dfn id=property-names>property names</dfn> of an element are the tokens that
   the element's <code title=attr-property><a href=#names:-the-property-attribute>property</a></code> attribute
   is found to contain when its value is <a href=#split-a-string-on-spaces title="split a string on
-  spaces">split on spaces</a>.</p>
+  spaces">split on spaces</a>, with the order preserved but with
+  duplicates removed (leaving only the first occurrence of each
+  name).</p>
 
 
   <h4 id=values><span class=secno>5.2.5 </span>Values</h4>

Modified: source
===================================================================
--- source	2009-05-11 09:07:13 UTC (rev 3083)
+++ source	2009-05-11 10:22:59 UTC (rev 3084)
@@ -6522,8 +6522,10 @@
   title="dom-HTMLPropertyCollection-names"><code>names</code></dfn>
   attribute must return a live <code>DOMStringList</code> object
   giving the <span>property names</span> of all the elements
-  <span>represented by the collection</span>. The same object must be
-  returned each time.</p>
+  <span>represented by the collection</span>, listed in <span>tree
+  order</span>, but with duplicates removed, leaving only the first
+  occurrence of each name. The same object must be returned each
+  time.</p>
 
   <p>The <dfn
   title="dom-HTMLPropertyCollection-item"><code>item(<var
@@ -46119,7 +46121,8 @@
 
   <p>The <code title="dom-document-items">document.items</code> DOM
   attribute provides access to all the <span>top-level microdata
-  items</span>.</p>
+  items</span>. This attribute returns an <code>HTMLCollection</code>,
+  which can be enumerated.</p>
 
   <p>Each <span title="concept-item">item</span> is represented in the
   DOM by the element on which the relevant <code
@@ -46149,10 +46152,121 @@
 
   </div>
 
-  <!-- XXX ... -->
+  <p>Once an element representing an <span
+  title="concept-item">item</span> has been obtained, its properties
+  can be extracted using the <code
+  title="dom-properties">properties</code> DOM attribute. This
+  attribute returns an <code>HTMLPropertyCollection</code>, which can
+  be enumerated to go through each element that adds one or more
+  properties to the item. It can also be indexed by name, which will
+  return the property with that name (if there is just one).</p>
 
+  <p>Each element that adds a property also has a <code
+  title="dom-content">content</code> DOM attribute that returns its
+  value.
 
+  <div class="example">
 
+   <p>This sample uses the function above to get the first item of
+   type "net.example.user" and then pops up an alert using the
+   "net.example.name" property from that item.</p>
+
+   <pre>var user = getItems('net.example.user')[0];
+alert('Hello ' + user.properties['net.example.name'].content + '!');</pre>
+
+  </div>
+
+  <p>When an item has multiple properties with the same name, the
+  <code>HTMLPropertyCollection</code> returns a
+  <code>PropertyNodeList</code> object with all those properties
+  instead of returning just one. The <code>PropertyNodeList</code>
+  object can be used to obtained all the values at once using
+  <em>its</em> <code
+  title="dom-PropertyNodeList-content">content</code> attribute, which
+  returns an array of all the values.</p>
+
+  <div class="example">
+
+   <p>In an earlier example, a "com.example.feline" item had two
+   "com.example.color" values. This script looks up such items and
+   then lists all their values. Because it doesn't know ahead of time
+   if the item has zero, one, or more colors, it checks whether the
+   value returned from the <code>HTMLPropertyCollection</code> is a
+   <code>PropertyNodeList</code> (multiple colors), just a regular
+   element (one color), or null (no colors) before using it.</p>
+
+   <pre>var cat = getItems('com.example.feline')[0];
+var colors = cat.properties['com.example.color'];
+var result;
+if (!colors) {
+  result = 'Color unknown.';
+} else if (colors instanceof PropertyNodeList) {
+  result = 'Colors:';
+  for (var i = 0; i < colors.content.length; i += 1)
+    result += ' ' + colors.content[i];
+} else {
+  result = 'Color: ' + colors.content;
+}</pre>
+
+  </div>
+
+  <p>It's also possible to get a list of all the <span>property
+  names</span> using the object's <code
+  title="dom-HTMLPropertyCollection-names">names</code> DOM
+  attribute.</p>
+
+  <div class="example">
+
+   <p>This example creates a big list with a nested list for each item
+   on the page, each with of all the property names used in that
+   item./p>
+
+   <pre>var outer = document.createElement('ul');
+for (var item = 0; item < document.items.length; item += 1) {
+  var itemLi = document.createElement('li');
+  var inner = document.createElement('ul');
+  for (var name = 0; name < document.items[item].names.length; name += 1) {
+    var propLi = document.createElement('li');
+    propLi.appendChild(document.createTextNode(document.items[item].names[name]));
+    inner.appendChild(propLi);
+  }
+  itemLi.appendChild(inner);
+  outer.appendChild(itemLi);
+}
+document.body.appendChild(outer);</pre>
+
+   <p>If faced with the following from an earlier example:</p>
+
+   <pre><section item="org.example.animal.cat com.example.feline">
+ <h1 property="org.example.name com.example.fn">Hedral</h1>
+ <p property="org.example.desc">Hedral is a male american domestic
+ shorthair, with a fluffy <span
+ property="com.example.color">black</span> fur with <span
+ property="com.example.color">white</span> paws and belly.</p>
+ <img property="org.example.img" src="hedral.jpeg" alt="" title="Hedral, age 18 months">
+</section></pre>
+
+   <p>...it would result in the following output:</p>
+
+   <ul>
+    <li>
+     <ul>
+      <li>org.example.name</li>
+      <li>com.example.fn</li>
+      <li>org.example.desc</li>
+      <li>com.example.color</li>
+      <li>org.example.img</li>
+     </ul>
+    </li>
+   </ul>
+
+   <p>(The duplicate occurrence of "com.example.color" is not included
+   in the list.)</p>
+
+  </div>
+
+
+
   <h3>Encoding microdata</h3>
 
   <h4>The microdata model</h4>
@@ -46303,7 +46417,9 @@
   <p>The <dfn>property names</dfn> of an element are the tokens that
   the element's <code title="attr-property">property</code> attribute
   is found to contain when its value is <span title="split a string on
-  spaces">split on spaces</span>.</p>
+  spaces">split on spaces</span>, with the order preserved but with
+  duplicates removed (leaving only the first occurrence of each
+  name).</p>
 
 
   <h4>Values</h4>