- From: Richard Tibbett via cvs-syncmail <cvsmail@w3.org>
- Date: Mon, 04 Oct 2010 09:55:25 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv698/contacts
Modified Files:
Overview.html
Log Message:
+ 'API Invocation via DOM Events' section
+ 'User Interaction Guidelines > Sharing Contact Information - Example #2'
http://lists.w3.org/Archives/Public/public-device-apis/2010Sep/0134.html
http://lists.w3.org/Archives/Public/public-device-apis/2010Sep/0140.html
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/contacts/Overview.html,v
retrieving revision 1.89
retrieving revision 1.90
diff -u -d -r1.89 -r1.90
--- Overview.html 21 Sep 2010 11:17:30 -0000 1.89
+++ Overview.html 4 Oct 2010 09:55:23 -0000 1.90
@@ -331,7 +331,7 @@
href='#widl-Contact-tags'><code>tags</code></a> value(s) as part of individual <a
href="#contact-interface"><code>Contact</code></a> objects. Multiple contact groups can be displayed by filtering on the
required <a
- href='#widl-Contact-tags'><code>tags</code></a> value(s) via the <code>Contacts</code> <a
+ href='#widl-Contact-tags'><code>tags</code></a> value(s) via the <a href="#contacts-interface"><code>Contacts</code></a> <a
href='#widl-Contacts-find'>find()</a> function.
</p>
<dl
@@ -435,7 +435,7 @@
<dd>
<p>
A globally unique identifier for the given <code>Contact</code> object. Each <code>Contact</code> referenced from
- <code>Contacts</code> MUST include a non-empty <code>id</code> value.
+ <a href="#contacts-interface"><code>Contacts</code></a> MUST include a non-empty <code>id</code> value.
</p>
<p>
An implementation MUST maintain this globally unique resource identifier when a Contact is added to, or present within, an
@@ -1550,6 +1550,26 @@
</pre>
</div>
</section>
+ <section class="informative appendix">
+ <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 resulting from the <a>interaction of a user</a>.</p>
+
+<p>The <dfn>interaction of a user</dfn> is when a user invokes the API from an <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>
+
+<ul>
+ <li><code>click</code></li>
+ <li><code>dblclick</code></li>
+ <li><code>mouseup</code></li>
+</ul>
+
+<p>The <code>find()</code> method on <a href="#contacts-interface"><code>Contacts</code></a> should, if the method was invoked by an <a>interaction of a user</a> (as opposed to having been created and executed in general script), display the <a>Contact Picker</a> directly.</p>
+
+
+ </section>
+
<section
class="informative appendix">
<h2>
@@ -1562,7 +1582,7 @@
</p>
<section>
<h3>
- Sharing Contact Information
+ Sharing Contact Information - Example #1
</h3>
<p>
A website requests access to a user's address book with the following code:
@@ -1571,6 +1591,8 @@
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);
@@ -1590,6 +1612,8 @@
generalErrorCB,
{filter: 'Bob'}
);
+
+</script>
</pre>
</div>
<p>
@@ -1653,6 +1677,97 @@
be able to review and revoke permissions to web applications at a later date.
</p>
</section>
+
+ <section>
+ <h3>
+ Sharing 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>
+ If the user clicks on the rendered button element the <a>user agent</a> may provide a non-blocking <dfn>contact search notification</dfn> as
+ follows:
+ </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 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 Monday, 4 October 2010 09:55:27 UTC