hixie: Change document.items to document.getItems() with built-in filtering. (whatwg r3436)

hixie: Change document.items to document.getItems() with built-in
filtering. (whatwg r3436)

http://dev.w3.org/cvsweb/html5/spec/Overview.html?r1=1.2561&r2=1.2562&f=h
http://html5.org/tools/web-apps-tracker?from=3435&to=3436

===================================================================
RCS file: /sources/public/html5/spec/Overview.html,v
retrieving revision 1.2561
retrieving revision 1.2562
diff -u -d -r1.2561 -r1.2562
--- Overview.html 17 Jul 2009 01:11:59 -0000 1.2561
+++ Overview.html 17 Jul 2009 01:30:48 -0000 1.2562
@@ -5832,9 +5832,9 @@
   readonly attribute <a href="#htmlcollection-0">HTMLCollection</a> <a href="#dom-document-links" title="dom-document-links">links</a>;
   readonly attribute <a href="#htmlcollection-0">HTMLCollection</a> <a href="#dom-document-forms" title="dom-document-forms">forms</a>;
   readonly attribute <a href="#htmlcollection-0">HTMLCollection</a> <a href="#dom-document-scripts" title="dom-document-scripts">scripts</a>;
-  readonly attribute <a href="#htmlcollection-0">HTMLCollection</a> <a href="#dom-document-items" title="dom-document-items">items</a>;
   NodeList <a href="#dom-document-getelementsbyname" title="dom-document-getElementsByName">getElementsByName</a>(in DOMString elementName);
   NodeList <a href="#dom-document-getelementsbyclassname" title="dom-document-getElementsByClassName">getElementsByClassName</a>(in DOMString classNames);
+  NodeList <a href="#dom-document-getitems" title="dom-document-getItems">getItems</a>([Optional] in DOMString typeNames);
 
   // <a href="#dynamic-markup-insertion">dynamic markup insertion</a>
            attribute DOMString <a href="#dom-innerhtml" title="dom-innerHTML">innerHTML</a>;
@@ -36793,30 +36793,19 @@
 
   </div><h4 id="using-the-microdata-dom-api"><span class="secno">5.1.4 </span>Using the microdata DOM API</h4><p>The microdata becomes even more useful when scripts can use it to
   expose information to the user, for example offering it in a form
-  that can be used by other applications.<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>. This attribute returns an <code><a href="#htmlcollection-0">HTMLCollection</a></code>,
-  which can be enumerated.<p>Each <a href="#concept-item" title="concept-item">item</a> is represented in the
+  that can be used by other applications.<p>The <code title="dom-document-getItems"><a href="#dom-document-getitems">document.getItems(<var title="">typeNames</var>)</a></code> method provides access to the
+  <a href="#top-level-microdata-items">top-level microdata items</a>. It returns a
+  <code>NodeList</code> containing the items with the specified types,
+  or all types if no argument is specified.<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
   that the element has can be obtained using the <code title="dom-item"><a href="#dom-item">element.item</a></code> DOM attribute, which returns a
   <code><a href="#domsettabletokenlist-0">DOMSettableTokenList</a></code> object.<div class="example">
 
-   <p>This sample code shows a function that returns all the top-level
-   microdata items of the type that it is passed:</p>
-
-   <pre>function getItems(type) {
-  var result = [];
-  for (var i = 0; i &lt; document.items.length; i += 1) {
-    if (document.items[i].item.contains(type))
-      result.push(document.items[i]);
-  }
-  return result;
-}</pre>
-
-   <p>This function can be used to get all the "com.example.feline"
-   items as follows:</p>
+   <p>This sample how the <code title="dom-document-getItems"><a href="#dom-document-getitems">getItems()</a></code> method can be used
+   to obtain a list of all the top-level microdata items of one type
+   given in the document:</p>
 
-   <pre>var cats = getItems("com.example.feline");</pre>
+   <pre>var cats = document.getItems("com.example.feline");</pre>
 
   </div><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
@@ -36829,11 +36818,11 @@
 
   <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>
+   <p>This sample gets 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];
+   <pre>var user = document.getItems('net.example.user')[0];
 alert('Hello ' + user.properties['net.example.name'][0].content + '!');</pre>
 
   </div><p>The <code><a href="#htmlpropertycollection-0">HTMLPropertyCollection</a></code> object, when indexed by
@@ -36847,7 +36836,7 @@
    "com.example.color" values. This script looks up the first such
    item and then lists all its values.</p>
 
-   <pre>var cat = getItems('com.example.feline')[0];
+   <pre>var cat = document.getItems('com.example.feline')[0];
 var colors = cat.properties['com.example.color'].contents;
 var result;
 if (colors.length == 0) {
@@ -37079,11 +37068,13 @@
   elements.<p>If a property's <a href="#concept-property-value" title="concept-property-value">value</a>
   is an <a href="#absolute-url">absolute URL</a>, the property must be specified
   using an <a href="#url-property-elements" title="URL property elements">URL property
-  element</a>.<h3 id="microdata-dom-api"><span class="secno">5.3 </span>Microdata DOM API</h3><dl class="domintro"><dt><var title="">document</var> . <code title="dom-items">items</code></dt>
+  element</a>.<h3 id="microdata-dom-api"><span class="secno">5.3 </span>Microdata DOM API</h3><dl class="domintro"><dt><var title="">document</var> . <code title="dom-getItems()">getItems</code>( [ <var title="">types</var> ] )</dt>
 
    <dd>
 
-    <p>Returns an <code><a href="#htmlcollection-0">HTMLCollection</a></code> of the elements in the <code>Document</code> that create <a href="#concept-item" title="concept-item">items</a> and that are not part of other <a href="#concept-item" title="concept-item">items</a>.</p>
+    <p>Returns a <code>NodeList</code> of the elements in the <code>Document</code> that create <a href="#concept-item" title="concept-item">items</a>, that are not part of other <a href="#concept-item" title="concept-item">items</a>, and that have all the types given in the argument, if any.</p>
+
+    <p>The <var title="">types</var> argument is interpreted as a space-separated list of classes.</p>
 
    </dd>
 
@@ -37110,10 +37101,17 @@
 
   </dl><div class="impl">
 
-  <p>The <dfn id="dom-document-items" title="dom-document-items"><code>document.items</code></dfn>
-  attribute must return an <code><a href="#htmlcollection-0">HTMLCollection</a></code> rooted at the
-  <code>Document</code> node, whose filter matches only elements in
-  the list of <a href="#top-level-microdata-items">top-level microdata items</a>.</p>
+  <p>The <dfn id="dom-document-getitems" title="dom-document-getItems"><code>document.getItems(<var title="">typeNames</var>)</code></dfn> method takes an optional
+  string that contains an <a href="#unordered-set-of-unique-space-separated-tokens">unordered set of unique
+  space-separated tokens</a> representing types. When called, the
+  method must return a live <code>NodeList</code> object containing
+  all the elements in the document, in <a href="#tree-order">tree order</a>, that
+  are <a href="#top-level-microdata-items">top-level microdata items</a> that have all the <a href="#item-types" title="item types">types</a> specified in that argument, having
+  obtained the types by <a href="#split-a-string-on-spaces" title="split a string on
+  spaces">splitting a string on spaces</a>. If there are no tokens
+  specified in the argument, or if the argument is missing, then the
+  method must return a <code>NodeList</code> containing all the
+  <a href="#top-level-microdata-items">top-level microdata items</a> in the document.</p>
 
   <p>The <dfn id="dom-item" title="dom-item"><code>item</code></dfn> DOM attribute
   on elements must <a href="#reflect">reflect</a> the element's <code title="attr-item"><a href="#items:-the-item-attribute">item</a></code> content attribute.</p>

Received on Friday, 17 July 2009 01:32:56 UTC