2009/dap/contacts Overview.html,1.55,1.56 contacts_picker.png,1.1,1.2

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

Modified Files:
	Overview.html contacts_picker.png 
Log Message:
- Added 'User Interaction Guidelines' Annex

Index: contacts_picker.png
===================================================================
RCS file: /sources/public/2009/dap/contacts/contacts_picker.png,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
Binary files /tmp/cvsqMw8hY and /tmp/cvshoF2LG differ

Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/contacts/Overview.html,v
retrieving revision 1.55
retrieving revision 1.56
diff -u -d -r1.55 -r1.56
--- Overview.html	7 Jun 2010 10:15:04 -0000	1.55
+++ Overview.html	7 Jun 2010 10:49:43 -0000	1.56
@@ -91,7 +91,6 @@
         extent to which they share their address book information and the ability to restrict which pieces of information related to which
         contact gets shared.
       </p>
-      
       <p>
         The API itself is agnostic of any underlying address book sources, data formats and storage.
       </p>
@@ -1534,6 +1533,122 @@
         </section>
       </section>
     </section>
+    <section
+     class="informative appendix">
+      <h2>
+        User Interaction Guidelines
+      </h2>
+      <p>
+        This specification is primarily intended to provide the user with the ability to view and control the contact information that may
+        be shared, saved or removed from their unified address book. This annex provides some examples of a conformant user experience that
+        this specification enables.
+      </p>
+      <section>
+        <h3>
+          Sharing Contact Information
+        </h3>
+        <p>
+          A website requests access to a user&#39;s address book with the following code:
+        </p>
+<pre
+ class='example sh_javascript_dom'>
+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);
+    // ...
+}
+
+// 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;}
+                               );
+</pre>
+        <p>
+          As a result of executing this code, the <a>user agent</a> may provide a non-blocking <dfn>contact search notification</dfn> as
+          follows:
+        </p>
+        <p align="center">
+          <img
+           src="contacts_notification.png"
+           alt="Contact Search Notification" /><br>
+          (<a
+           href="contacts_notification.png">View as PNG</a>)
+        </p>
+        <p>
+          If the user clicks &#39;Cancel&#39;, the <a
+           href="#contacterrorcb-interface"><code>ContactErrorCB</code></a> defined for the find() operation will be invoked with an error
+          code of <a
+           href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>ContactError::PERMISSION_DENIED_ERROR</code></a>.
+        </p>
+        <p>
+          If the user clicks &#39;Select&#39;, the <a>user agent</a> may provide a <dfn>contact picker</dfn>, utilising all of the
+          parameters provided in the find() 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 the user clicks &#39;Cancel&#39;, the <a
+           href="#contacterrorcb-interface"><code>ContactErrorCB</code></a> associated to the current find() operation will be invoked with
+          an error code of <a
+           href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>ContactError::PERMISSION_DENIED_ERROR</code></a>.
+        </p>
+        <p>
+          If the user clicks &#39;Select&#39;, the <a
+           href="#contactfindsuccesscb-interface"><code>ContactFindSuccessCB</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>
+        <p
+         class="note">
+          Include permission review/revocation mockup?
+        </p>
+      </section>
+      <section>
+        <h3>
+          Contact Writebacks
+        </h3>
+        <section>
+          <h4>
+            Saving a Contact to the Address Book
+          </h4>
+          <p
+           class="note">
+            Include Contact creation/modification writeback mockup.
+          </p>
+        </section>
+        <section>
+          <h4>
+            Removing a Contact from the Address Book
+          </h4>
+          <p
+           class="note">
+            Include Contact deletion writeback mockup.
+          </p>
+        </section>
+      </section>
+    </section>
   </body>
 </html>

Received on Monday, 7 June 2010 10:49:50 UTC