W3C home > Mailing lists > Public > public-html-commits@w3.org > January 2010

html5/spec Overview.html,1.3601,1.3602

From: Ian Hickson via cvs-syncmail <cvsmail@w3.org>
Date: Wed, 06 Jan 2010 05:02:03 +0000
To: public-html-commits@w3.org
Message-Id: <E1NSO1z-0007jF-Ky@lionel-hutz.w3.org>
Update of /sources/public/html5/spec
In directory hutz:/tmp/cvs-serv27629

Modified Files:
	Overview.html 
Log Message:
Add some examples of list='' usage. (whatwg r4502)

Index: Overview.html
===================================================================
RCS file: /sources/public/html5/spec/Overview.html,v
retrieving revision 1.3601
retrieving revision 1.3602
diff -u -d -r1.3601 -r1.3602
--- Overview.html	6 Jan 2010 04:50:06 -0000	1.3601
+++ Overview.html	6 Jan 2010 05:01:59 -0000	1.3602
@@ -29385,6 +29385,41 @@
    <code class="no-backref" title="dom-input-stepDown"><a href="#dom-input-stepdown">stepDown()</a></code> and
    <code class="no-backref" title="dom-input-stepUp"><a href="#dom-input-stepup">stepUp()</a></code> methods.</p>
 
+  </div><div class="example">
+
+   <p>If a document contained the following markup:</p>
+
+   <pre>&lt;input type="url" name="location" list="urls"&gt;
+&lt;datalist id="urls"&gt;
+ &lt;option label="MIME: Format of Internet Message Bodies" value="http://www.ietf.org/rfc/rfc2045"&gt;
+ &lt;option label="HTML 4.01 Specification" value="http://www.w3.org/TR/html4/"&gt;
+ &lt;option label="Form Controls" value="http://www.w3.org/TR/xforms/slice8.html#ui-commonelems-hint"&gt;
+ &lt;option label="Scalable Vector Graphics (SVG) 1.1 Specification" value="http://www.w3.org/TR/SVG/"&gt;
+ &lt;option label="Feature Sets - SVG 1.1 - 20030114" value="http://www.w3.org/TR/SVG/feature.html"&gt;
+ &lt;option label="The Single UNIX Specification, Version 3" value="http://www.unix-systems.org/version3/"&gt;
+&lt;/datalist&gt;
+</pre>
+
+   <p>...and the user had typed "<kbd>www.w3</kbd>", and the user
+   agent had also found that the user had visited
+   <code>http://www.w3.org/Consortium/#membership</code> and
+   <code>http://www.w3.org/TR/XForms/</code> in the recent past, then
+   the rendering might look like this:</p>
+
+   <p><img alt='A text box with an icon on the left followed by the text "www.w3" and a cursor, with a drop down button on the right hand side; with, below, a drop down box containing a list of six URIs on the left, with the first four having grayed out labels on the right; and a scroll bar to the right of the drow down box, indicating further values are available.' src="images/sample-url.png"></p>
+
+   <p>The first four URIs in this sample consist of the four URIs in
+   the author-specified list that match the text the user has entered,
+   sorted lexically. Note how the UA is using the knowledge that the
+   values are URIs to allow the user to omit the scheme part and
+   perform intelligent matching on the domain name.</p>
+
+   <p>The last two URIs (and probably many more, given the scrollbar's
+   indications of more values being available) are the matches from
+   the user agent's session history data. This data is not made
+   available to the page DOM. In this particular case, the UA has no
+   titles to provide for those values.</p>
+
   </div><h6 id="e-mail-state"><span class="secno">4.10.5.1.5 </span><dfn title="attr-input-type-email">E-mail</dfn> state</h6><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i><div class="impl">
 
   <p>When an <code><a href="#the-input-element">input</a></code> element's <code title="attr-input-type"><a href="#attr-input-type">type</a></code> attribute is in the <a href="#e-mail-state" title="attr-input-type-email">E-mail</a> state, the rules in this
@@ -30607,6 +30642,42 @@
    <code class="no-backref" title="dom-textarea/input-select"><a href="#dom-textarea-input-select">select()</a></code> and
    <code class="no-backref" title="dom-textarea/input-setSelectionRange"><a href="#dom-textarea-input-setselectionrange">setSelectionRange()</a></code> methods.</p>
 
+  </div><div class="example">
+
+   <p>Here is an of a range control using an autocomplete list with
+   the <code title="attr-input-list"><a href="#attr-input-list">list</a></code> attribute. This could
+   be useful if there are values along the full range of the control
+   that are especially important, such as preconfigured light levels
+   or typical speed limits in a range control used as a speed
+   control. The following markup fragment:</p>
+
+   <pre>&lt;input type="range" min="-100" max="100" value="0" step="10" name="power" list="powers"&gt;
+&lt;datalist id="powers"&gt;
+ &lt;option value="0"&gt;
+ &lt;option value="-30"&gt;
+ &lt;option value="30"&gt;
+ &lt;option value="+50"&gt;
+&lt;/datalist&gt;
+</pre>
+
+   <p>...with the following style sheet applied:</p>
+
+   <pre>input { height: 75px; width: 49px; background: #D5CCBB; color: black; }</pre>
+
+   <p>...might render as:</p>
+
+   <p><img alt="A vertical slider control whose primary colour is black and whose background colour is beige, with the slider having five tick marks, one long one at each extremity, and three short ones clustered around the midpoint." src="images/sample-range.png"><p>Note how the UA determined the orientation of the control from
+   the ratio of the style-sheet-specified height and width properties.
+   The colours were similiarly derived from the style sheet. The tick
+   marks, however, were derived from the markup. In particular, the
+   <code title="attr-input-step"><a href="#attr-input-step">step</a></code> attribute has not
+   affected the placement of tick marks, the UA deciding to only use
+   the author-specified completion values and then adding longer tick
+   marks at the extremes.</p>
+
+   <p>Note also how the invalid value <code title="">+50</code> was
+   completely ignored.</p>
+
   </div><h6 id="color-state"><span class="secno">4.10.5.1.15 </span><dfn title="attr-input-type-color">Color</dfn> state</h6><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i><div class="impl">
 
   <p>When an <code><a href="#the-input-element">input</a></code> element's <code title="attr-input-type"><a href="#attr-input-type">type</a></code> attribute is in the <a href="#color-state" title="attr-input-type-color">Color</a> state, the rules in this
@@ -31590,6 +31661,66 @@
    <p>Other URLs from the user's history might show also; this is up
    to the user agent.</p>
 
+  </div><div class="example">
+
+   <p>This example demonstrates how to design a form that uses the
+   autocompletion list feature while still degrading usefully in
+   legacy user agents.</p>
+
+   <p>If the autocompletion list is merely an aid, and is not
+   important to the content, then simply using a <code><a href="#the-datalist-element">datalist</a></code>
+   element with children <code><a href="#the-option-element">option</a></code> elements is enough. To
+   prevent the values from being rendered in legacy user agents, they
+   should be placed inside the <code title="attr-option-value"><a href="#attr-option-value">value</a></code> attribute instead of
+   inline.</p>
+
+   <pre>&lt;p&gt;
+ &lt;label&gt;
+  Enter a breed:
+  &lt;input type="text" name="breed" list="breeds"&gt;
+  &lt;datalist id="breeds"&gt;
+   &lt;option value="Abyssinian"&gt;
+   &lt;option value="Alpaca"&gt;
+   &lt;!-- ... --&gt;
+  &lt;/datalist&gt;
+ &lt;/label&gt;
+&lt;/p&gt;</pre>
+
+   <p>However, if the values need to be shown in legacy UAs, then
+   fallback content can be placed inside the <code><a href="#the-datalist-element">datalist</a></code>
+   element, as follows:</p>
+
+   <pre>&lt;p&gt;
+ &lt;label&gt;
+  Enter a breed:
+  &lt;input type="text" name="breed" list="breeds"&gt;
+ &lt;/label&gt;
+ &lt;datalist id="breeds"&gt;
+  &lt;label&gt;
+   or select one from the list:
+   &lt;select name="breed"&gt;
+    &lt;option value=""&gt; (none selected)
+    &lt;option&gt;Abyssinian
+    &lt;option&gt;Alpaca
+    &lt;!-- ... --&gt;
+   &lt;/select&gt;
+  &lt;/label&gt;
+ &lt;/datalist&gt;
+&lt;/p&gt;
+</pre>
+
+   <p>The fallback content will only be shown in UAs that don't
+   support <code><a href="#the-datalist-element">datalist</a></code>. The options, on the other hand, will
+   be detected by all UAs, even though they are not direct children of
+   the <code><a href="#the-datalist-element">datalist</a></code> element.</p>
+
+   <p>Note that if an <code><a href="#the-option-element">option</a></code> element used in a
+   <code><a href="#the-datalist-element">datalist</a></code> is <code title="attr-option-selected"><a href="#attr-option-selected">selected</a></code>, it will be selected
+   by default by legacy UAs (because it affects the
+   <code><a href="#the-select-element">select</a></code>), but it will not have any effect on the
+   <code><a href="#the-input-element">input</a></code> element in UAs that support
+   <code><a href="#the-datalist-element">datalist</a></code>.</p>
+
   </div><h6 id="the-readonly-attribute"><span class="secno">4.10.5.2.3 </span>The <code title="attr-input-readonly"><a href="#attr-input-readonly">readonly</a></code> attribute</h6><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i><p>The <dfn id="attr-input-readonly" title="attr-input-readonly"><code>readonly</code></dfn>
   attribute is a <a href="#boolean-attribute">boolean attribute</a> that controls whether
   or not the use can edit the form control. <span class="impl">When
Received on Wednesday, 6 January 2010 05:02:05 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Wednesday, 6 January 2010 05:02:13 GMT