- From: Dominique Hazael-Massieux via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 19 Jan 2011 15:30:18 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv30008
Modified Files:
Overview.html
Log Message:
updated based on dicsussions on teleconf: move add/write as informative appendix, remove mention from abstract
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/contacts/Overview.html,v
retrieving revision 1.104
retrieving revision 1.105
diff -u -d -r1.104 -r1.105
--- Overview.html 14 Jan 2011 12:07:53 -0000 1.104
+++ Overview.html 19 Jan 2011 15:30:16 -0000 1.105
@@ -21,10 +21,10 @@
type="text/javascript"
class='remove'>
var respecConfig = {
- specStatus: "WD",
+ specStatus: "ED",
shortName: "contacts-api",
editors: [{name: "Richard Tibbett", url: "http://richt.me", company: "Opera Software ASA", companyURL: "http://www.opera.com"}],
- publishDate: "2011-01-10",
+ //publishDate: "2011-01-10",
previousPublishDate: "2010-12-09",
previousMaturity: "WD",
edDraftURI: "http://dev.w3.org/2009/dap/contacts/",
@@ -96,17 +96,6 @@
<li>A <a href="#contacts-interface"<code>Contacts</code></a> interface, which provides the method needed to access to a user's unified address book.</li>
<li>A <a href="#contact-interface"<code>Contact</code></a> interface, which provides the individual contact information that can be 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 normative guidelines for manipulating a user's unified address book, to
- <a href="#adding-and-updating-contacts">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
id='sotd'>
@@ -127,7 +116,10 @@
with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], as this specification uses that specification and
terminology.
</p>
- </section>
+ <p>
+ A conforming implementation is required to implement all fields defined in this specification.
+ </p>
+ </section>
<section
class="informative">
<h2>
@@ -154,9 +146,16 @@
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 conforming implementation is required to implement all fields defined in this specification.
+ 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 informative examples illustrating how to <a href="#adding-and-updating-contacts">add and update contact information</a>, utilising existing web platform APIs.</p>
+
<div
class="example">
<p>
@@ -1593,7 +1592,206 @@
</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 from their unified address book. This annex provides some examples of a conformant user experience that this
+ specification enables.
+ </p>
+ <section>
+ <h3>
+ Accessing Contact Information - Example #1
+ </h3>
+ <p>
+ A website requests access to a user's address book with the following code:
+ </p>
+ <div
+ class='example'>
+<pre
+ class="sh_javascript">
+ <script type="text/javascript">
+
+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 'name' and 'emails' properties
+// and initially filter the list to Contact records containing 'Bob':
+navigator.service.contacts.find(['name', 'emails'],
+ successContactFindCallback,
+ generalErrorCB,
+ {filter: 'Bob'}
+ );
+
+</script>
+</pre>
+ </div>
+ <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 an additional find() operation is called by the current web application before the user has clicked 'Select' or
+ 'Cancel' on the current notification, an error will be invoked with a code of <a
+ href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PENDING_OPERATION_ERROR</code></a> if that operation was defined with a
+ non-<code>null</code> <code>errorCB</code> parameter.
+ </p>
+ <p>
+ If the user clicks 'Cancel', the <code>errorCB</code>, if non-<code>null</code> for the current find() operation, will be
+ invoked with an error code of <a
+ href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PERMISSION_DENIED_ERROR</code></a>.
+ </p>
+ <p>
+ If the user clicks 'Select', the <a>user agent</a> may provide a <dfn>contact picker</dfn>, utilizing 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 an additional find() operation is called by the current web application before the user has clicked 'Select' or
+ 'Cancel' on the current notification, an error will be invoked with a code of <a
+ href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PENDING_OPERATION_ERROR</code></a> if that operation was defined with a
+ non-<code>null</code> <code>errorCB</code> parameter.
+ </p>
+ <p>
+ If the user clicks 'Cancel', the <code>errorCB</code>, if non-<code>null</code> for the current find() operation, will be
+ invoked with an error code of <a
+ href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PERMISSION_DENIED_ERROR</code></a>.
+ </p>
+ <p>
+ If the user clicks 'Select', the <a
+ href="#contactfindcb-interface"><code>ContactFindCB</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>
+ </section>
+
+ <section>
+ <h3>
+ Accessing Contact Information - Example #2
+ </h3>
+ <p>
+ A website requests access to a user's address book with the following code:
+ </p>
+ <div
+ class='example'>
+<pre
+ class="sh_javascript">
+<input type="button" value="Share Contacts" onclick="getContacts()" />
+
+<script type="text/javascript">
+ 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);
+ // ...
+ }
+
+ function getContacts() {
+ // Perform an address book search. Obtain the 'name' and 'emails' properties
+ // and initially filter the list to Contact records containing 'Bob':
+ navigator.service.contacts.find(['name', 'emails'],
+ successContactFindCallback,
+ generalErrorCB,
+ {filter: 'Bob'}
+ );
+ }
+</script>
+</pre>
+ </div>
+ <p>
+ This code may render as follows within the <a>user agent</a>:
+ </p>
+ <p
+ align="center">
+ <img
+ src="contacts_element.png"
+ alt="Contact Search via DOM Events"><br>
+ (<a
+ href="contacts_element.png">View as PNG</a>)
+ </p>
+ <p>
+ If the user clicks on the rendered button element then the <a>user agent</a> may directly provide a <dfn>contact picker</dfn>, as defined in
+ <a href="#api-invocation-via-dom-events">API Invocation via DOM Events</a>, utilizing all of the
+ parameters provided in the <code>find()</code> 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 an additional find() operation is called by the current web application before the user has clicked 'Select' or
+ 'Cancel' on the current notification, an error will be invoked with a code of <a
+ href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PENDING_OPERATION_ERROR</code></a> if that operation was defined with a
+ non-<code>null</code> <code>errorCB</code> parameter.
+ </p>
+ <p>
+ If the user clicks 'Cancel', the <code>errorCB</code>, if non-<code>null</code> for the current find() operation, will be
+ invoked with an error code of <a
+ href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PERMISSION_DENIED_ERROR</code></a>.
+ </p>
+ <p>
+ If the user clicks 'Select', the <a
+ href="#contactfindcb-interface"><code>ContactFindCB</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>
+ </section>
+
+ </section>
+ <section class="informative appendix">
<h2>Adding and Updating Contacts</h2>
<p>
@@ -1799,205 +1997,6 @@
</p>
</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 from their unified address book. This annex provides some examples of a conformant user experience that this
- specification enables.
- </p>
- <section>
- <h3>
- Accessing Contact Information - Example #1
- </h3>
- <p>
- A website requests access to a user's address book with the following code:
- </p>
- <div
- class='example'>
-<pre
- class="sh_javascript">
- <script type="text/javascript">
-
-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 'name' and 'emails' properties
-// and initially filter the list to Contact records containing 'Bob':
-navigator.service.contacts.find(['name', 'emails'],
- successContactFindCallback,
- generalErrorCB,
- {filter: 'Bob'}
- );
-
-</script>
-</pre>
- </div>
- <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 an additional find() operation is called by the current web application before the user has clicked 'Select' or
- 'Cancel' on the current notification, an error will be invoked with a code of <a
- href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PENDING_OPERATION_ERROR</code></a> if that operation was defined with a
- non-<code>null</code> <code>errorCB</code> parameter.
- </p>
- <p>
- If the user clicks 'Cancel', the <code>errorCB</code>, if non-<code>null</code> for the current find() operation, will be
- invoked with an error code of <a
- href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PERMISSION_DENIED_ERROR</code></a>.
- </p>
- <p>
- If the user clicks 'Select', the <a>user agent</a> may provide a <dfn>contact picker</dfn>, utilizing 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 an additional find() operation is called by the current web application before the user has clicked 'Select' or
- 'Cancel' on the current notification, an error will be invoked with a code of <a
- href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PENDING_OPERATION_ERROR</code></a> if that operation was defined with a
- non-<code>null</code> <code>errorCB</code> parameter.
- </p>
- <p>
- If the user clicks 'Cancel', the <code>errorCB</code>, if non-<code>null</code> for the current find() operation, will be
- invoked with an error code of <a
- href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PERMISSION_DENIED_ERROR</code></a>.
- </p>
- <p>
- If the user clicks 'Select', the <a
- href="#contactfindcb-interface"><code>ContactFindCB</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>
- </section>
-
- <section>
- <h3>
- Accessing Contact Information - Example #2
- </h3>
- <p>
- A website requests access to a user's address book with the following code:
- </p>
- <div
- class='example'>
-<pre
- class="sh_javascript">
-<input type="button" value="Share Contacts" onclick="getContacts()" />
-
-<script type="text/javascript">
- 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);
- // ...
- }
-
- function getContacts() {
- // Perform an address book search. Obtain the 'name' and 'emails' properties
- // and initially filter the list to Contact records containing 'Bob':
- navigator.service.contacts.find(['name', 'emails'],
- successContactFindCallback,
- generalErrorCB,
- {filter: 'Bob'}
- );
- }
-</script>
-</pre>
- </div>
- <p>
- This code may render as follows within the <a>user agent</a>:
- </p>
- <p
- align="center">
- <img
- src="contacts_element.png"
- alt="Contact Search via DOM Events"><br>
- (<a
- href="contacts_element.png">View as PNG</a>)
- </p>
- <p>
- If the user clicks on the rendered button element then the <a>user agent</a> may directly provide a <dfn>contact picker</dfn>, as defined in
- <a href="#api-invocation-via-dom-events">API Invocation via DOM Events</a>, utilizing all of the
- parameters provided in the <code>find()</code> 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 an additional find() operation is called by the current web application before the user has clicked 'Select' or
- 'Cancel' on the current notification, an error will be invoked with a code of <a
- href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PENDING_OPERATION_ERROR</code></a> if that operation was defined with a
- non-<code>null</code> <code>errorCB</code> parameter.
- </p>
- <p>
- If the user clicks 'Cancel', the <code>errorCB</code>, if non-<code>null</code> for the current find() operation, will be
- invoked with an error code of <a
- href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PERMISSION_DENIED_ERROR</code></a>.
- </p>
- <p>
- If the user clicks 'Select', the <a
- href="#contactfindcb-interface"><code>ContactFindCB</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>
- </section>
-
- </section>
</body>
</html>
Received on Wednesday, 19 January 2011 15:30:20 UTC