W3C home > Mailing lists > Public > public-dap-commits@w3.org > October 2010

2009/dap/contacts Overview.html,1.89,1.90

From: Richard Tibbett via cvs-syncmail <cvsmail@w3.org>
Date: Mon, 04 Oct 2010 09:55:25 +0000
To: public-dap-commits@w3.org
Message-Id: <E1P2hlV-0000BZ-JR@lionel-hutz.w3.org>
Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv698/contacts

Modified Files:
	Overview.html 
Log Message:
+ 'API Invocation via DOM Events' section
+ 'User Interaction Guidelines > Sharing Contact Information - Example #2'

http://lists.w3.org/Archives/Public/public-device-apis/2010Sep/0134.html
http://lists.w3.org/Archives/Public/public-device-apis/2010Sep/0140.html

Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/contacts/Overview.html,v
retrieving revision 1.89
retrieving revision 1.90
diff -u -d -r1.89 -r1.90
--- Overview.html	21 Sep 2010 11:17:30 -0000	1.89
+++ Overview.html	4 Oct 2010 09:55:23 -0000	1.90
@@ -331,7 +331,7 @@
            href='#widl-Contact-tags'><code>tags</code></a> value(s) as part of individual <a
            href="#contact-interface"><code>Contact</code></a> objects. Multiple contact groups can be displayed by filtering on the
           required <a
-           href='#widl-Contact-tags'><code>tags</code></a> value(s) via the <code>Contacts</code> <a
+           href='#widl-Contact-tags'><code>tags</code></a> value(s) via the <a href="#contacts-interface"><code>Contacts</code></a> <a
            href='#widl-Contacts-find'>find()</a> function.
         </p>
         <dl
@@ -435,7 +435,7 @@
           <dd>
             <p>
               A globally unique identifier for the given <code>Contact</code> object. Each <code>Contact</code> referenced from
-              <code>Contacts</code> MUST include a non-empty <code>id</code> value.
+              <a href="#contacts-interface"><code>Contacts</code></a> MUST include a non-empty <code>id</code> value.
             </p>
             <p>
               An implementation MUST maintain this globally unique resource identifier when a Contact is added to, or present within, an
@@ -1550,6 +1550,26 @@
 </pre>
       </div>
     </section>
+    <section class="informative appendix">
+      <h3>API Invocation via DOM Events</h3>
+    
+    <p>The API contained in this document can be invoked either programmatically (for example, inline within a general script) or resulting from the <a>interaction of a user</a>.</p> 
+
+<p>The <dfn>interaction of a user</dfn> is when a user invokes the API from an <a href="http://dev.w3.org/html5/markup/elements.html"><code>HTMLElement</code></a> [[HTML5]] within the current <a>browsing context</a> via a <a>valid auto-invocation event</a>.</p>
+
+<p>A <dfn>valid auto-invocation event</dfn> includes any of the following event types, as defined in [[DOM-LEVEL-3-EVENTS]]:</p> 
+
+<ul>
+   <li><code>click</code></li>
+   <li><code>dblclick</code></li>
+   <li><code>mouseup</code></li>
+</ul>
+
+<p>The <code>find()</code> method on <a href="#contacts-interface"><code>Contacts</code></a> should, if the method was invoked by an <a>interaction of a user</a> (as opposed to having been created and executed in general script), display the <a>Contact Picker</a> directly.</p>
+
+
+    </section>
+    
     <section
      class="informative appendix">
       <h2>
@@ -1562,7 +1582,7 @@
       </p>
       <section>
         <h3>
-          Sharing Contact Information
+          Sharing Contact Information - Example #1
         </h3>
         <p>
           A website requests access to a user&#39;s address book with the following code:
@@ -1571,6 +1591,8 @@
          class='example'>
 <pre
  class="sh_javascript">
+ &lt;script type="text/javascript"&gt;
+ 
 function successContactFindCallback(contacts) {
     // do something with resulting contact objects
     for (var i in contacts) alert(contacts[i].name);
@@ -1590,6 +1612,8 @@
                                 generalErrorCB,
                                 {filter: &#39;Bob&#39;}
                                );
+                               
+&lt;/script&gt;
 </pre>
         </div>
         <p>
@@ -1653,6 +1677,97 @@
           be able to review and revoke permissions to web applications at a later date.
         </p>
       </section>
+      
+      <section>
+        <h3>
+          Sharing Contact Information - Example #2
+        </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;input type="button" value="Share Contacts" onclick="getContacts()" /&gt;
+ 
+&lt;script type="text/javascript"&gt;
+  function successContactFindCallback(contacts) {
+    // do something with resulting contact objects
+    for (var i in contacts) alert(contacts[i].name);
+    // ...
+  }
+
+  function generalErrorCB(error) {
+    // do something with resulting errors
+    alert(error.code);
+    // ...
+  }
+  
+  function getContacts() {
+    // Perform an address book search. Obtain the &#39;name&#39; and &#39;emails&#39; properties 
+    // and initially filter the list to Contact records containing &#39;Bob&#39;:
+    navigator.service.contacts.find([&#39;name&#39;, &#39;emails&#39;],
+                                    successContactFindCallback, 
+                                    generalErrorCB,
+                                    {filter: &#39;Bob&#39;}
+                                   );
+  }
+&lt;/script&gt;
+</pre>
+        </div>
+        <p>
+          If the user clicks on the rendered button element the <a>user agent</a> may provide a non-blocking <dfn>contact search notification</dfn> as
+          follows:
+        </p>
+        <p
+         align="center">
+          <img
+           src="contacts_element.png"
+           alt="Contact Search via DOM Events"><br>
+           (<a
+           href="contacts_element.png">View as PNG</a>)
+        </p>
+        <p>
+          If the user clicks on the rendered button element the <a>user agent</a> may directly provide a <dfn>contact picker</dfn>, as defined in 
+          <a href="#api-invocation-via-dom-events">API Invocation via DOM Events</a>, utilizing all of the
+          parameters provided in the <code>find()</code> operation as follows:
+        </p>
+        <p
+         align="center">
+          <img
+           src="contacts_picker.png"
+           alt="Contact Picker"><br>
+           (<a
+           href="contacts_picker.png">View as PNG</a>)
+        </p>
+        <p>
+          In this dialog, the user is provided with a summary of the sharing that the application is requesting and the option to select
+          one or more contacts (as appropriate) from the user interface.
+        </p>
+        <p>
+          If an additional find() operation is called by the current web application before the user has clicked &#39;Select&#39; or
+          &#39;Cancel&#39; on the current notification, an error will be invoked with a code of <a
+           href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PENDING_OPERATION_ERROR</code></a> if that operation was defined with a
+          non-<code>null</code> <code>errorCB</code> parameter.
+        </p>
+        <p>
+          If the user clicks &#39;Cancel&#39;, the <code>errorCB</code>, if non-<code>null</code> for the current find() operation, will be
+          invoked with an error code of <a
+           href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PERMISSION_DENIED_ERROR</code></a>.
+        </p>
+        <p>
+          If the user clicks &#39;Select&#39;, the <a
+           href="#contactfindcb-interface"><code>ContactFindCB</code></a> associated to the current find() operation will be invoked with
+          the contact information selected by the user provided as the only parameter.
+        </p>
+        <p>
+          Further to this initial sharing of Contact information, the <a
+           href="#security-and-privacy-considerations">Security and Privacy Considerations</a> section expects that the user should easily
+          be able to review and revoke permissions to web applications at a later date.
+        </p>
+      </section>
+
     </section>
   </body>
 </html>
Received on Monday, 4 October 2010 09:55:27 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Monday, 4 October 2010 09:55:27 GMT