--- a/contacts/Overview.html Fri Jun 22 16:35:57 2012 +0200
+++ b/contacts/Overview.html Fri Jun 22 16:36:38 2012 +0200
@@ -1091,226 +1091,5 @@
</p>
</section>
</section>
-
- <section class="informative appendix">
- <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 and paradigms in order to
- achieve 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>
-
- <p>
- 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>. A <dfn>vCard
- object</dfn> is a text-based representation of contact information provided according to any version of
- the vCard family of specifications.
- </p>
-
- <p class="note">Need to add informative references to all specs within the 'vCard family of
- specifications'.
- </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/vcard</code></li>
- <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 <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>
- 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 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 <a>vCard object</a> on the client side for download to the
- user's unified address book via either data: URIs [[RFC2397]] or using the [[FILE-WRITER]] and
- [[FILE-API]] interfaces. The following examples show two methods for creating a <a>vCard object</a>
- dynamically and then presenting this to the user. The user may then save this information by clicking
- on the presented information, download the dynamically generated <a>vCard object</a> 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">
- var vcard = 'BEGIN:VCARD\r\n' +
- 'VERSION:2.1\r\n' +
- 'N:Doe;John\r\n' +
- 'FN:John Doe\r\n' +
- 'TEL;WORK;VOICE:123456\r\n' +
- 'END:VCARD';
-
- // assign vCard as a Data URI to an anchor element for presentation and download by the user
- document.getElementById('vcard').href = "data:text/x-vcard;charset=utf-8," + encodeURIComponent( vcard );
- </script>
- </pre>
- </div>
-
- <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 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-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options'>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 of any resulting <a>vCard object</a> to be processed by the <a>user
- agent</a> according to the <a>rule for storing a Contact resource</a>.
- </p>
-
- <p>
- The examples below show two methods for updating 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">Save our Contact Details</a>
-
- <script type="text/javascript">
- // Obtain a single existing Contact object resulting from navigator.contacts.find()
- var existingContactObj = ...;
-
- var vcard = 'BEGIN:VCARD\r\n' +
- 'VERSION:3.0\r\n' +
- 'UID:' + existingContactObj.id + '\r\n' + // assign the Contact.id to a UID property
- 'N:Doe;John\r\n' +
- 'FN:John Doe\r\n' +
- 'TEL;HOME;VOICE:654321\r\n' +
- 'END:VCARD';
-
- // assign vCard as a Data URI to an anchor element for presentation and download by the user
- document.getElementById('vcard').href = "data:text/x-vcard;charset=utf-8," + encodeURIComponent( vcard );
- </script>
- </pre>
- </div>
-
- <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.contacts.find()
- var existingContactObj = ...;
-
- // Modify some parameters as required. e.g. add a new phone number
- existingContactObj.phoneNumbers.push({
- type: 'home',
- value: '654321'
- });
-
- // 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>
- </section>
</body>
</html>