- From: Richard Tibbett via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 06 Jan 2011 16:19:48 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv15983/contacts
Modified Files:
Overview.html
Log Message:
Improved 'Abstract' section.
Added 'Adding and Updating Contact Information' section.
Made 'API Invocation via DOM Events' normative.
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/contacts/Overview.html,v
retrieving revision 1.98
retrieving revision 1.99
diff -u -d -r1.98 -r1.99
--- Overview.html 8 Dec 2010 15:48:34 -0000 1.98
+++ Overview.html 6 Jan 2011 16:19:46 -0000 1.99
@@ -24,8 +24,8 @@
specStatus: "WD",
shortName: "contacts-api",
editors: [{name: "Richard Tibbett", url: "http://richt.me", company: "Opera Software ASA", companyURL: "http://www.opera.com"}],
- publishDate: "2010-12-09",
- previousPublishDate: "2010-08-17",
+ publishDate: "2011-01-06",
+ previousPublishDate: "2010-12-09",
previousMaturity: "WD",
edDraftURI: "http://dev.w3.org/2009/dap/contacts/",
// lcEnd: "2009-08-05",
@@ -90,8 +90,22 @@
The Contacts API defines the high-level interfaces required to provide read access to a user's unified address book.
</p>
<p>
- Methods to manipulate a user's unified address book, to add and remove contact information, are being developed in an
- accompanying specification [[CONTACTS-WRITER-API]].
+ This API includes the following key interfaces:
+ </p>
+ <ul>
+ <li>A <a href="#servicecontacts-interface"<code>ServiceContacts</code></a> interface, which provides a Contacts extension to the <code>navigator.service</code> object.</li>
+ <li>A <a href="#contacts-interface"<code>Contacts</code></a> interface, which provides the read operation for access to a user's unified address book.</li>
+ <li>A <a href="#contact-interface"<code>Contact</code></a> interface, which provides individual contact records that are returned following a successful read operation.</li>
+ </ul>
+ <p>
+ A set of <a href="#security-and-privacy-considerations">Security and Privacy Considerations</a> are presented for the discretion of both
+ implementors of the Contacts API and recipients of contact information (i.e. web pages). 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
+ provided herein.
+ </p>
+ <p>
+ This specification also provides non-normative examples for manipulating a user's unified address book, to
+ <a href="#adding-and-updating-contact-information">add and update contact information</a>, with existing web platform APIs.
</p>
</section>
<section
@@ -1554,7 +1568,7 @@
</pre>
</div>
</section>
- <section class="informative appendix">
+ <section>
<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
@@ -1564,7 +1578,7 @@
<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>
+<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>
@@ -1579,6 +1593,137 @@
</section>
+ <section>
+ <h2>Adding and Updating Contact Information</h2>
+
+ <p>
+ The ability to add and update contact information is not a function of the API provided in this specification. Instead, the
+ intention is to reuse existing web platform APIs in order to acheive this functionality.
+ </p>
+ <p>
+ In this section we show how the existing web platform would be used to provide add and update writeback functionality to allow users to
+ add new contacts or update existing contacts from a web page to their unified address book.
+ </p>
+
+ <section>
+ <h3>Saving a new Contact</h3>
+
+ <p>
+ To handle the saving of a new Contact, a <a>user agent</a> SHOULD register as the default MIME-type handler for the following media types:
+ </p>
+
+ <ul>
+ <li><code>text/x-vcard</code></li>
+ <li><code>text/directory</code></li>
+ <li><code>text/directory;profile=vCard</code></li>
+ </ul>
+
+ <p>
+ On invocation of a web resource that matches one of the media types above, the <a>user agent</a> SHOULD, on successful download by the user,
+ store the given resource in the user's unified address book. As part of this process, the <a>user agent</a> MAY present a dialog to the user
+ allowing them to override storage to the unified address book by selecting some other application with which to handle the given resource.
+ Additionally, the <a>user agent</a> MAY provide additional dialogs to the user as required, such as to show a preview of the Contact information
+ that will be stored in their unified address book, for the user to accept before permanently storing the given resource.
+ </p>
+
+ <p>
+ If required, a web page can dynamically generate a vCard object for download to the user's unified address book via the
+ [[FILE-WRITER]] and [[FILE-API]] interfaces. The following example shows the process in which a web site may create a vCard object
+ dynamically and then present this to the user. The user may then save this information by clicking on the presented information, download the
+ dynamically generated vCard object and invoke a suitable application with which to handle the dynamic resource.
+ </p>
+
+ <div class="example">
+ <pre class="sh_javascript"><a id="vcard">Save our Contact Details</a>
+
+<script type="text/javascript">
+ // obtain an ArrayBuffer consisting of valid vCard syntax (out of scope)
+ var vCardObj = getVCard( /* ... */ );
+
+ // create a new vCard Blob [[FILE-WRITER]]
+ var contactBlobBuilder = new BlobBuilder();
+ contactBlobBuilder.append( vCardObj );
+ var contactBlob = contactBlobBuilder.getBlob( "text/x-vcard" );
+
+ // obtain a vCard Blob URL [[FILE-API]]
+ var contactBlobURL = window.URL.createObjectUrl( contactBlob );
+
+ // assign vCard Blob URL to an anchor element for presentation and download by the user
+ document.getElementById('vcard').href = contactBlobURL;
+</script>
+</pre>
+ </div>
+ </section>
+
+ <section>
+ <h3>Updating an existing Contact</h3>
+
+ <p>
+ To update an existing Contact, the user must have already shared the contact information to edit with the current web page via the
+ <a href='#widl-Contacts-find'>find()</a> operation of the <a href="#contacts-interface"><code>Contacts</code></a> interface.
+ This section assumes that the user is already sharing some contact information with the current web page via this process.
+ </p>
+
+ <p>
+ If this existing Contact information is to be updated in the user's unified address book then the developer MUST assign the
+ <code>id</code> attribute, as returned in the <code>Contact</code> object, as the <code>UID</code> property [VCard4] of any resulting
+ vCard object.
+ </p>
+
+ <p>
+ The example below shows how to update an existing Contact in the user's unified address book by maintaining a valid UID property
+ while changing other parameters of the Contact card. The user is then required to click on the resulting anchor element to download
+ the modified Contact resource.
+ </p>
+
+ <p>
+ On invocation of a web resource that matches one of the valid media types above, the <a>user agent</a> SHOULD, on successful download by the user,
+ store the given resource in the user's unified address book. As part of this process, the <a>user agent</a> MAY present a dialog to the user
+ allowing them to override storage to the unified address book by selecting some other application with which to handle the given resource.
+ Additionally, the <a>user agent</a> MAY provide additional dialogs to the user as required, such as to show a preview of the Contact information
+ that will be stored in their unified address book, for the user to accept before permanently storing the given resource.
+ </p>
+
+ <div class="example">
+ <pre class="sh_javascript"><a id="vcard">Update our Contact Details</a>
+
+<script type="text/javascript">
+ // Obtain a single existing Contact object resulting from navigator.service.contacts.find()
+ var existingContactObj = ...;
+
+ // Modify some parameters as required. e.g. add a new phone number
+ existingContactObj.phoneNumbers.push({
+ type: 'home',
+ value: '+440000000002'
+ });
+
+ // With the existing Contact object, create an ArrayBuffer consisting of valid vCard
+ // syntax (out of scope) making sure to set the resulting vCard UID property to
+ // the id parameter returned in the existing Contact object
+ var vCardObj = getVCard( existingContactObj );
+
+ // create a new vCard Blob [[FILE-WRITER]]
+ var contactBlobBuilder = new BlobBuilder();
+ contactBlobBuilder.append( vCardObj );
+ var contactBlob = contactBlobBuilder.getBlob( "text/x-vcard" );
+
+ // obtain a vCard Blob URL [[FILE-API]]
+ var contactBlobURL = window.URL.createObjectUrl( contactBlob );
+
+ // assign vCard Blob URL to an anchor element for presentation and download by the user
+ document.getElementById('vcard').href = contactBlobURL;
+</script>
+</pre>
+ </div>
+
+
+ </section>
+
+ <p>
+
+ </p>
+ </section>
+
<section
class="informative appendix">
<h2>
@@ -1777,6 +1922,7 @@
</section>
</section>
+
</body>
</html>
Received on Thursday, 6 January 2011 16:19:50 UTC