- From: Ian Hickson via cvs-syncmail <cvsmail@w3.org>
- Date: Mon, 11 May 2009 08:18:28 +0000
- To: public-html-commits@w3.org
Update of /sources/public/html5/spec
In directory hutz:/tmp/cvs-serv31349
Modified Files:
Overview.html
Log Message:
more intro text for microdata (whatwg r3081)
Index: Overview.html
===================================================================
RCS file: /sources/public/html5/spec/Overview.html,v
retrieving revision 1.2238
retrieving revision 1.2239
diff -u -d -r1.2238 -r1.2239
--- Overview.html 11 May 2009 03:46:10 -0000 1.2238
+++ Overview.html 11 May 2009 08:18:25 -0000 1.2239
@@ -733,7 +733,8 @@
<ol>
<li><a href="#the-basic-syntax"><span class="secno">5.1.1 </span>The basic syntax</a></li>
<li><a href="#typed-items"><span class="secno">5.1.2 </span>Typed items</a></li>
- <li><a href="#selecting-names-when-defining-vocabularies"><span class="secno">5.1.3 </span>Selecting names when defining vocabularies</a></ol></li>
+ <li><a href="#selecting-names-when-defining-vocabularies"><span class="secno">5.1.3 </span>Selecting names when defining vocabularies</a></li>
+ <li><a href="#using-the-microdata-dom-api"><span class="secno">5.1.4 </span>Using the microdata DOM API</a></ol></li>
<li><a href="#encoding-microdata"><span class="secno">5.2 </span>Encoding microdata</a>
<ol>
<li><a href="#the-microdata-model"><span class="secno">5.2.1 </span>The microdata model</a></li>
@@ -36275,7 +36276,8 @@
</div><p>Properties can also themselves be groups of name-value pairs, by
putting the <code title="attr-item"><a href="#items:-the-item-attribute">item</a></code> attribute on the
- element that declares the property.<div class="example">
+ element that declares the property.<p>Items that are not part of others are called <a href="#top-level-microdata-items">top-level
+ microdata items</a>.<div class="example">
<p>In this example, the outer item represents a person, and the
inner one represents a band:</p>
@@ -36285,10 +36287,13 @@
<p>Band: <span property="band" item> <span property="name">Jazz Band</span> (<span property="size">12</span> players)</span></p>
</div></pre>
- <p>In this example, the outer item has two properties, "name" and
- "band". The "name" is "Amanda", and the "band" is an item in its own
- right, with two properties, "name" and "size". The "name" of the
- band is "Jazz Band", and the "size" is "12".</p>
+ <p>The outer item here has two properties, "name" and "band". The
+ "name" is "Amanda", and the "band" is an item in its own right,
+ with two properties, "name" and "size". The "name" of the band is
+ "Jazz Band", and the "size" is "12".</p>
+
+ <p>The outer item in this example is a top-level microdata
+ item.</p>
</div><p>Properties don't have to be given as ancestors of the element
with the <code title="attr-item"><a href="#items:-the-item-attribute">item</a></code> attribute. They can be
@@ -36342,19 +36347,21 @@
re-used. Microdata is most useful, though, when it is used in
contexts where other authors and readers are able to cooperate to
make new uses of the markup.<p>For this purpose, it is necessary to give each <a href="#concept-item" title="concept-item">item</a> a type, such as "person", or "cat",
- or "band". Types are identified in three ways:<ul class="brief"><li>As <a href="#url" title="URL">URLs</a>
+ or "band". Types are identified in three ways:<ul class="brief"><li>As <a href="#url" title="URL">URLs</a>.
<li>As <a href="#valid-reversed-dns-identifier" title="valid reversed DNS identifier">reversed DNS
- labels</a>
+ labels</a>.
<!--
- <li>Using the names of <span>predefined types</span>
+ <li>Using the names of <span>predefined types</span>, which are described below.
-->
</ul><p><a href="#url" title="URL">URLs</a> are self-explanatory. <a href="#valid-reversed-dns-identifier" title="valid reversed DNS identifier">Reversed DNS labels</a> are
strings such as "org.example.animals.cat" or "org.example.band".<p>The type for an <a href="#concept-item" title="concept-item">item</a> is given
as the value of the <code title="attr-item"><a href="#items:-the-item-attribute">item</a></code>
- attribute.<div class="example">
+ attribute.<p>When using custom typed items, the property names are also given
+ in the form of <a href="#url" title="URL">URLs</a> or <a href="#valid-reversed-dns-identifier" title="valid
+ reversed DNS identifier">reversed DNS labels</a>.<div class="example">
<p>Here, the item is "org.example.animals.cat":</p>
@@ -36365,10 +36372,42 @@
<img property="org.example.img" src="hedral.jpeg" alt="" title="Hedral, age 18 months">
</section></pre>
- </div><p>When using custom typed items, the property names are also given
- in this form.</p><!--
- <p><span>Predefined types</span> are described below.</p>
---><h4 id="selecting-names-when-defining-vocabularies"><span class="secno">5.1.3 </span>Selecting names when defining vocabularies</h4><p><em>This section is non-normative.</em><p>Using microdata means using a vocabulary. For some purposes, an
+ <p>In this example the "org.example.animals.cat" item has three
+ properties, an "org.example.name" ("Hedral"), an "org.example.desc"
+ ("Hedral is..."), and an "org.example.img" ("hedral.jpeg").</p>
+
+ </div><p>An item can have several types, in the same way that an element
+ can declare several properties at once.<div class="example">
+
+ <p>Here, the item is both an "org.example.animals.cat" and a "com.example.feline":</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>This example has one item with two types and the following
+ properties:</p>
+
+ <table><thead><tr><td>Property
+ <td>Value
+ <tbody><tr><td>org.example.name
+ <td>Hedral
+ <tr><td>com.example.fn
+ <td>Hedral
+ <tr><td>org.example.desc
+ <td>Hedral is a male american domestic shorthair, with a fluffy black fur with white paws and belly.
+ <tr><td>com.example.color
+ <td>black
+ <tr><td>com.example.color
+ <td>white
+ <tr><td>org.example.img
+ <td>.../hedral.jpeg
+ </table></div><h4 id="selecting-names-when-defining-vocabularies"><span class="secno">5.1.3 </span>Selecting names when defining vocabularies</h4><p><em>This section is non-normative.</em><p>Using microdata means using a vocabulary. For some purposes, an
ad-hoc vocabulary is adequate. For others, a vocabulary will need to
be designed. Where possible, authors are encouraged to re-use
existing vocabularies, as this makes content re-use easier.<p>When designing new vocabularies, identifiers can be created
@@ -36385,7 +36424,28 @@
could select identifiers of the form "com.example.jon.name" and
"com.example.adam.name" respectively.</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><p>The microdata model consists of groups of name-value pairs known
+ </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>.<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
+
+ <p>This function can be used to get all the "com.example.feline"
+ items as follows:</p>
+
+ <pre>var cats = getItems("com.example.feline");</pre>
+
+ </pre></div><!-- XXX ... --><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><p>The microdata model consists of groups of name-value pairs known
as <dfn id="concept-item" title="concept-item">items</dfn>.<p>Each group has zero or more types, each name has one or more
values, and each value is either a string or another group of
name-value pairs.<h4 id="items:-the-item-attribute"><span class="secno">5.2.2 </span>Items: the <dfn title="attr-item"><code>item</code></dfn> attribute</h4><p>Every <a href="#html-elements" title="HTML elements">HTML element</a> may have an
Received on Monday, 11 May 2009 08:18:38 UTC