dap commit: introduction

changeset:   116:2a903a4698d3
user:        Robin Berjon <robin@berjon.com>
date:        Fri Jun 22 16:25:55 2012 +0200
files:       contacts/Overview.html
description:
introduction


diff -r 260ff23472a4 -r 2a903a4698d3 contacts/Overview.html
--- a/contacts/Overview.html	Fri Jun 22 16:12:24 2012 +0200
+++ b/contacts/Overview.html	Fri Jun 22 16:25:55 2012 +0200
@@ -50,59 +50,64 @@
     <section class="informative">
       <h2>Introduction</h2>
       <p>
-        Every operating system and a large number of web-based service providers have different ways of
+        Every operating system and a large number of Web-based service providers have different ways of
         representing address book information. Most users are required to maintain a plurality of contact lists
-        which leads to multiple copies of address book data. This in turn
-        often leads to disjoint and inconsistent information being stored across a user's
-        address book providers.
+        which leads to multiple copies of address book data. This in turn often leads to disjoint and inconsistent
+        information being stored across a user's address book providers.
       </p>
       <p>
         When sharing contact data with third parties users are, more often than not, required to hand over access to
         their whole address book. Users are implicitly required to trust third parties with all of their data
         when, in reality, the user may only wish, or need, to share a subset of their address book information so
-        that an application can fulfill its purpose.
+        that an application can fulfil its purpose. When sharing of only a subset of a user's address book is
+        possible, it often requires the user to type the information into a form herself rather than having it
+        extracted from one of her address book services.
       </p>
       <p>
-        This specification defines the concept of a user's unified address book - where address book data may
-        be sourced from a plurality of sources - both online and locally. It then defines the
-        interfaces through which third party applications can access a user's unified address book, with explicit user
-        permission and filtering. The focus of this data sharing is on making the user aware of the data that
-        they will share and putting them at the centre of the data sharing process; free to select both the
-        extent to which they share their address book information and the ability to restrict which pieces of
-        information related to which contact gets shared.
+        This specification enables a Web application to have access to a selected subset of a user's address book,
+        obtained from arbitrary services not known to the Web application. The interactions, brokered using
+        Web Intents [[!WEBINTENTS]] are designed in order to maximise the user's security and privacy.
+        Address book data may be sourced from a plurality of sources — both online and local to the user's device
+        — so long as those sources are registered as Intent services with the user agent. It defines a common
+        format which services use to provide data to Web applications in a consistent and interoperable manner.
+      </p>
+      <p>
+        The expectation is that data sharing happens with explicit user permission and filtering. The focus of 
+        this data sharing is on making the user aware of the data that they will share and putting them at the 
+        centre of the data sharing process; free to select both the 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>
         A set of <a href="#security-and-privacy-considerations">Security and Privacy Considerations</a> are
-        presented for the discretion of both implementers of the Pick Contacts Intent and recipients of contact
-        information (i.e. web pages). This specification provides a set of non-normative 
+        presented for the discretion of both implementers of Pick Contacts Intent services and recipients of contact
+        information (i.e. Web applications). This specification provides a set of non-normative 
         <a href="#user-interaction-guidelines">User Interaction Guidelines</a> demonstrating an example user experience
         that is compliant with the Security and Privacy Considerations described herein.
       </p>
       <p>
-        This specification also provides informative examples illustrating how to 
-        <a href="#adding-and-updating-contacts">add and update contact information</a>, utilizing existing web platform
-        APIs.
-      </p>
-      <p>
         The following code illustrates how to obtain contact information from a user's address book:
       </p>
-      <pre class="example sh_javascript_dom">
-        function success (contacts) {
-            // do something with resulting contact objects
-            for (var i in contacts) alert(contacts[i].name);
-            // ...
+      <pre class="example highlight">
+        var intent = new Intent({ action:   "http://webintents.org/pick",
+                                  type:     "http://w3.org/type/contact",
+                                  extras:   { fields: ["displayName", "emails"] }});
+        navigator.startActivity(intent, contactsOK, contactsFail);
+
+        function contactsOK (contacts) {
+            // iterate over the array of contacts to do something useful with them
         }
-
-        function error (err) {
-            // do something with resulting error
-            alert(err.code);
-            // ...
+        function contactsFail (err) {
+            // display an error to the user
         }
-
-        // Perform an address book search. Obtain the 'name' and 'emails' properties 
-        // and initially filter the list to Contact records containing 'Bob':
-        navigator.contacts.find(  ['name', 'emails'], success, error, { filter: 'Bob', multiple: true } );
       </pre>
+      <p>
+        When the above code is run, the user would typically be prompted by her user agent to select
+        a service able to pick a contact (there may be several such services, if she has multiple address
+        book sources). Upon selecting a service, she will be presented with an interface enabling her
+        to choose what contact information is returned to the Web application. Upon completing her
+        choice, the contacts data would be returned to the Web application in the <code>contactsOK</code>
+        callback.
+      </p>
     </section>
 
     <section id='conformance'>

Received on Friday, 22 June 2012 14:56:17 UTC