2009/dap/contacts HTML.html,NONE,1.1

Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv16234/contacts

Added Files:
	HTML.html 
Log Message:
- Adding first draft of the HTML-based proposal for Contact database sharing.
- Added HTML-DEVICE to ReSpec biblio.js

--- NEW FILE: HTML.html ---
<!DOCTYPE html>
<html>
  <head>
    <title>HTML Contact Sharing</title>
    <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
    <script src='../ReSpec.js/js/respec.js' class='remove'></script>
<script
 type="text/javascript"
 src='../ReSpec.js/js/sh_main.min.js'
 class='remove'>
</script>
<script
 type="text/javascript"
 class='remove'>
            var respecConfig = {
                specStatus: "ED",
                shortName: "contacts-html-api",
                editors: [{name: "Richard Tibbett", url: "http://richt.me", company: "Opera Software ASA", companyURL: "http://www.opera.com"}],
                //publishDate:  "2010-08-17",
                //previousPublishDate:  "2010-08-17",
                //previousMaturity: "WD",
                edDraftURI: "http://dev.w3.org/2009/dap/contacts/HTML_Contacts.html",
                // lcEnd: "2009-08-05",
            };
</script>
<script
 type="text/javascript"
 src='../common/config.js'
 class='remove'>
</script>
<style
 type="text/css">
/* ReSpec.js CSS optimizations (Richard Tibbett) */

div.example {
    border-top: 1px solid #ff4500;
    border-bottom: 1px solid #ff4500;
    background: #fff;
    padding:    1em;
    font-size: 0.9em;
    margin-top: 1em;
}
div.example::before {
    content:    "Example";
    display:    block;
    width:      150px;
    background: #ff4500;
    color:  #fff;
    font-family:    initial;
    padding:    3px;
    padding-left: 5px;
    font-weight:    bold;
    margin: -1em 0 1em -1em;
}

/* Clean up pre.idl */
pre.idl::before {
   font-size:0.9em;
}

/* Add better spacing to sections */
section, .section {
   margin-bottom: 2em;
}

/* Reduce note & issue render size */
.note, .issue {
   font-size:0.8em;
}

/* Add addition spacing to <ol> and <ul> for rule definition */
ol.rule li, ul.rule li {
   padding:0.2em;
}
</style>
  </head>
  <body>
    <section id='abstract'>
      This specification defines HTML enhancements that provide access to a user's address book.
    </section>
    
    <section
     id='conformance'>
      <p>
        This specification defines conformance criteria that apply to a single product: the <dfn>user agent</dfn> that implements the
        interfaces that it contains.
      </p>
      <p>
        Implementations that use ECMAScript to provide the callbacks defined in this specification must implement them in a manner consistent
        with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], as this specification uses that specification and
        terminology.
      </p>
    </section>
    
    <section class='informative'>
      <h2>Introduction</h2>
      <p>
         This HTML Contact Sharing recommendation defines an HTML extension to enable websites to quickly and unobtrusively obtain a list of 
         contacts from the current user based on the records available in their address book.
      </p>
      <p>
         This specification builds on the existing HTML <code>device</code> element [[!HTML-DEVICE]].
      </p>   
      <p>   
         In addition, this recommednation also reuses the basic security and privacy principles and existing low-level parts of the Contacts API [[!CONTACTS-API]] to provide address book data to a web application.
      </p>
      <p>
         ...
      </p>
      
      <div
       class="example">
        <p>
          The following code illustrates how to obtain contact information from a user&#39;s address book <em>manually</em>:
        </p>
<pre
 class="sh_javascript">
&lt;device type=&quot;contact&quot; params=&quot;fields=name,emails;filter=Bob;updatedSince=2010-05-23T00:00:00Z&quot; 
   onchange=&quot;successContactFindCallback(this.data)&quot; /&gt;

&lt;script type=&quot;text/javascript&quot;&gt;
  function successContactFindCallback(contacts) {
    // do something with resulting contact objects
    for (var i in contacts) alert(contacts[i].name.formatted);
    // ...
  }
&lt;/script&gt;
</pre>
</div>
    </section>
    
    <section>
      <h2>
        HTML Device Element Integration
      </h2>
      <p
       class="issue">
        This section is likely to evolve significantly over time due to [[!HTML-DEVICE]] not currently being a mature proposal. This is included to illustrate an HTML integration model for this and
        other select Device APIs, hooking in to the same low-level objects of a corresponding programmatic API being actively developed within the W3C DAP WG.<br>
        <br>
        Feedback on this section is encouraged from implementors.
      </p>
      <p>
        This section details an extension to the HTML Device specification [[!HTML-DEVICE]] to enable contact information to be shared
        through graphical controls embedded on a web page.
      </p>
      <p>
        The <code>device</code> element's <code>type</code> attribute MUST be set to <var>contact</var> to indicate the device element is in the <dfn>contacts
        state</dfn>, according to the table below.
      </p>
      <table
       class='simple'
       summary='Device Element in the Contacts Database state'>
        <thead>
          <tr>
            <th>
              Keyword
            </th>
            <th>
              State
            </th>
            <th>
              Device Description
            </th>
            <th>
              Example
            </th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>
              <code>contact</code> 
            </td>
            <td>
              Contacts
            </td>
            <td>
              Contacts Database/Storage
            </td>
            <td>
              Access to a group of contacts residing on the user&#39;s system or in the current <a>user agent</a>.
            </td>
          </tr>
        </tbody>
      </table>
      <p>
        A <code>device</code> element in the <a>contacts database state</a> SHOULD render as a graphical control on the current web page.
      </p>
      <div
       class="example">
        <p
         class="note">
          Include example UI control for <code>device</code> element in the <a>contacts state</a>.
        </p>
      </div>
      <p
       class="note">
        TBW: Passing parameters via <code>params</code> in to the UI control widget...
      </p>
      <p>
        Once the user has selected the graphical control they MAY be presented with a modal, UI control widget dialog to select and review
        contact sharing with the current web page. If the user selects one or more contacts from this dialog then:
      </p>
      <ol
       class="rule">
        <li>
          The modal UI Widget control dialog used to select the contact objects MUST be terminated.
        </li>
        <li>
          The originating <code>device</code> element&#39;s <code>data</code> attribute MUST be set to a corresponding <a
           href="#contact-interface"><code>Contact</code></a> Array object (<code>Contact[]</code>).
        </li>
        <li>
          The originating <code>device</code> element&#39;s <code>change</code> event MUST be triggered.
        </li>
      </ol>
      <p
       class="issue">
        [[!HTML-DEVICE]] is not currently provisioned as being a HTML web form element. If serialization of the resulting data is required
        for use in a web forms context neither the [[!HTML-DEVICE]] specification or this specification currently provide any
        recommendations to that effect.
      </p>
    </section>
    
    <section class="informative appendix">
        <h3>
          User Interaction Guidelines
        </h3>
        <p>
          A website requests access to a user&#39;s address book with the following code:
        </p>
        <div
         class="example">
<pre
 class="sh_javascript">
&lt;html&gt;
&lt;body&gt;
  &lt;h1&gt;Contacts API Test Page&lt;/h1&gt; 
  &lt;device type=&quot;contact&quot; params=&quot;fields=name,emails;filter=Bob&quot; onchange=&quot;successContactFindCallback(this.data)&quot; /&gt;
  &lt;script type=&quot;text/javascript&quot;&gt;
    function successContactFindCallback(contacts) {
      // do something with resulting contact objects
      for (var i in contacts) alert(contacts[i].name.formatted);
      // ...
    }
  &lt;/script&gt;  
&lt;/body&gt;
&lt;/html&gt;
</pre>
        </div>
        <p>
          This page may render in the <a>user agent</a> as follows:
        </p>
        <p
         class="note">
          TODO: include rendered page mockup with &lt;device&gt; button-like rendering.
        </p>
        <p>
          If the user clicks on the rendered device control, the <a>user agent</a> may provide the <a>contact picker</a>, utilising all of
          the parameters provided in the originating device element.
        </p>
        <p
         class="note">
          TODO: The &#39;Remember these settings for this page&#39; checkbox in the contact picker is not relevant in manual mode...
        </p>
        <p
         align="center">
          <img
           src="contacts_picker.png"
           alt="Contact Picker"><br>
           (<a
           href="contacts_picker.png">View as PNG</a>)
        </p>
        <p>
          If the user clicks &#39;Cancel&#39;, then the user is returned to the page and no further action is taken.
        </p>
        <p>
          If the user clicks &#39;Select&#39;, the <var>data</var> attribute of the originating device element is set to the contact
          information selected by the user as defined in <a
           href="#html-device-element-integration">HTML Device Element Integration</a>.
        </p>
      </section>
    
    <section class='appendix'>
      <h2>Acknowledgements</h2>
      <p>
        Many thanks to Wojciech Maslowski for helping to put this initial proposal together.
      </p>
    </section>
  </body>
</html>

Received on Tuesday, 21 September 2010 13:53:44 UTC