- From: Richard Tibbett via cvs-syncmail <cvsmail@w3.org>
- Date: Mon, 10 Jan 2011 15:16:54 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv23313/contacts
Modified Files:
Overview.html
Log Message:
Updated 'Adding and Updating Contacts' section
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/contacts/Overview.html,v
retrieving revision 1.99
retrieving revision 1.100
diff -u -d -r1.99 -r1.100
--- Overview.html 6 Jan 2011 16:19:46 -0000 1.99
+++ Overview.html 10 Jan 2011 15:16:52 -0000 1.100
@@ -104,8 +104,9 @@
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.
+ This specification also provides normative guidelines for manipulating a user's unified address book, to
+ <a href="#adding-and-updating-contact-information">add and update contact information</a>, utilising existing web platform APIs and negating the need for such mechanisms to be
+ provided as part of a specialized Contacts API.
</p>
</section>
<section
@@ -1594,24 +1595,30 @@
</section>
<section>
- <h2>Adding and Updating Contact Information</h2>
+ <h2>Adding and Updating Contacts</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.
+ intention is to reuse existing web platform APIs and paradigms in order to acheive add and update 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:
+ A <dfn>valid Contact resource</dfn> is a web resource with a <code>.vcard</code> or <code>.vcf</code> filename extension or a web resource with a
+ MIME-type matching a <a>valid media type</a>.
+ </p>
+
+ <p>
+ To handle the saving of a new Contact, a <a>user agent</a> SHOULD register as the default handler for any <a>valid Contact resource</a>.
</p>
+ <p>
+ A <dfn>valid media type</dfn> will be one of the following web resource MIME types:
+ </p>
+
<ul>
<li><code>text/x-vcard</code></li>
<li><code>text/directory</code></li>
@@ -1619,20 +1626,61 @@
</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.
+ On invocation of a <a>valid Contact resource</a>, the <a>user agent</a> SHOULD, on successful download of the <a>valid Contact resource</a>, store the
+ given resource in the user's unified address book according to the <a>rule for storing a Contact resource</a>. As part of this
+ standard download process, the <a>user agent</a> MAY present a dialog to the user allowing them to select a different application with which to handle
+ the given resource, thereby overriding the use of the unified address book for the storage of the data contained therein and bypassing the
+ <a>rule for storing a Contact resource</a>.
</p>
<p>
- If required, a web page can dynamically generate a vCard object for download to the user's unified address book via the
+ The <dfn>rule for storing a Contact resource</dfn> is defined as follows:
+ </p>
+
+ <p>
+ Let <var>Contact</var> be the parsed key/value pairs contained in the <a>valid Contact resource</a>.
+ </p>
+
+ <ol>
+
+ <li>
+ If <var>Contact</var> contains a <code>UID</code> key [VCard4] then process the <a>valid Contact resource</a> as follows.
+
+ <ol>
+ <li>
+ Let <var>MatchedContact</var> be the result of obtaining a Contact object from the user's unified address book that matches exactly the value of the
+ <code>UID</code> provided.
+ </li>
+ <li>
+ If a <var>MatchedContact</var> has been found (i.e <var>MatchedContact</var> is not-<code>null</code>) then update the contents of
+ <var>MatchedContact</var> with the contents of <var>Contact</var> and exit this rule.
+ </li>
+ </ol>
+
+ </li>
+
+ <li>
+ Save the contents of <var>Contact</var> in the user's unified address book as a new Contact object.
+ </li>
+ </ol>
+
+ <p>
+ As part of the <a>rule for storing a Contact resource</a>, the <a>user agent</a> MAY provide additional dialogs to the user after successful completion of
+ the download and before the Contact information is saved to the unified address book, such as to show a preview of the Contact information contained therein
+ as it will be stored in the user's unified address book. The user MAY be able to override the information provided before accepting the additions and
+ permanently storing the given data in their unified address book.
+ </p>
+
+ <section class="informative">
+ <h4>Adding a new Contact</h4>
+
+ <p>
+ A web page can dynamically generate a vCard object on the client side 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>
@@ -1653,39 +1701,31 @@
</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>
+ </section>
- <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>
+ <section class="informative">
+ <h4>Updating an existing Contact</h4>
+
+ <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 will 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 to be processed by the <a>user agent</a> according to the <a>rule for storing a Contact resource</a>.
+ </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>
+
+ <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()
@@ -1714,11 +1754,10 @@
document.getElementById('vcard').href = contactBlobURL;
</script>
</pre>
- </div>
-
-
- </section>
-
+ </div>
+
+ </section>
+
<p>
</p>
Received on Monday, 10 January 2011 15:16:56 UTC