- From: Richard Tibbett via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 21 Sep 2010 13:53:38 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv16234/contacts
Added Files:
HTML.html
Log Message:
- Adding first draft of the HTML-based proposal for Contact database sharing.
- Added HTML-DEVICE to ReSpec biblio.js
--- NEW FILE: HTML.html ---
<!DOCTYPE html>
<html>
<head>
<title>HTML Contact Sharing</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
<script src='../ReSpec.js/js/respec.js' class='remove'></script>
<script
type="text/javascript"
src='../ReSpec.js/js/sh_main.min.js'
class='remove'>
</script>
<script
type="text/javascript"
class='remove'>
var respecConfig = {
specStatus: "ED",
shortName: "contacts-html-api",
editors: [{name: "Richard Tibbett", url: "http://richt.me", company: "Opera Software ASA", companyURL: "http://www.opera.com"}],
//publishDate: "2010-08-17",
//previousPublishDate: "2010-08-17",
//previousMaturity: "WD",
edDraftURI: "http://dev.w3.org/2009/dap/contacts/HTML_Contacts.html",
// lcEnd: "2009-08-05",
};
</script>
<script
type="text/javascript"
src='../common/config.js'
class='remove'>
</script>
<style
type="text/css">
/* ReSpec.js CSS optimizations (Richard Tibbett) */
div.example {
border-top: 1px solid #ff4500;
border-bottom: 1px solid #ff4500;
background: #fff;
padding: 1em;
font-size: 0.9em;
margin-top: 1em;
}
div.example::before {
content: "Example";
display: block;
width: 150px;
background: #ff4500;
color: #fff;
font-family: initial;
padding: 3px;
padding-left: 5px;
font-weight: bold;
margin: -1em 0 1em -1em;
}
/* Clean up pre.idl */
pre.idl::before {
font-size:0.9em;
}
/* Add better spacing to sections */
section, .section {
margin-bottom: 2em;
}
/* Reduce note & issue render size */
.note, .issue {
font-size:0.8em;
}
/* Add addition spacing to <ol> and <ul> for rule definition */
ol.rule li, ul.rule li {
padding:0.2em;
}
</style>
</head>
<body>
<section id='abstract'>
This specification defines HTML enhancements that provide access to a user's address book.
</section>
<section
id='conformance'>
<p>
This specification defines conformance criteria that apply to a single product: the <dfn>user agent</dfn> that implements the
interfaces that it contains.
</p>
<p>
Implementations that use ECMAScript to provide the callbacks defined in this specification must implement them in a manner consistent
with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], as this specification uses that specification and
terminology.
</p>
</section>
<section class='informative'>
<h2>Introduction</h2>
<p>
This HTML Contact Sharing recommendation defines an HTML extension to enable websites to quickly and unobtrusively obtain a list of
contacts from the current user based on the records available in their address book.
</p>
<p>
This specification builds on the existing HTML <code>device</code> element [[!HTML-DEVICE]].
</p>
<p>
In addition, this recommednation also reuses the basic security and privacy principles and existing low-level parts of the Contacts API [[!CONTACTS-API]] to provide address book data to a web application.
</p>
<p>
...
</p>
<div
class="example">
<p>
The following code illustrates how to obtain contact information from a user's address book <em>manually</em>:
</p>
<pre
class="sh_javascript">
<device type="contact" params="fields=name,emails;filter=Bob;updatedSince=2010-05-23T00:00:00Z"
onchange="successContactFindCallback(this.data)" />
<script type="text/javascript">
function successContactFindCallback(contacts) {
// do something with resulting contact objects
for (var i in contacts) alert(contacts[i].name.formatted);
// ...
}
</script>
</pre>
</div>
</section>
<section>
<h2>
HTML Device Element Integration
</h2>
<p
class="issue">
This section is likely to evolve significantly over time due to [[!HTML-DEVICE]] not currently being a mature proposal. This is included to illustrate an HTML integration model for this and
other select Device APIs, hooking in to the same low-level objects of a corresponding programmatic API being actively developed within the W3C DAP WG.<br>
<br>
Feedback on this section is encouraged from implementors.
</p>
<p>
This section details an extension to the HTML Device specification [[!HTML-DEVICE]] to enable contact information to be shared
through graphical controls embedded on a web page.
</p>
<p>
The <code>device</code> element's <code>type</code> attribute MUST be set to <var>contact</var> to indicate the device element is in the <dfn>contacts
state</dfn>, according to the table below.
</p>
<table
class='simple'
summary='Device Element in the Contacts Database state'>
<thead>
<tr>
<th>
Keyword
</th>
<th>
State
</th>
<th>
Device Description
</th>
<th>
Example
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>contact</code>
</td>
<td>
Contacts
</td>
<td>
Contacts Database/Storage
</td>
<td>
Access to a group of contacts residing on the user's system or in the current <a>user agent</a>.
</td>
</tr>
</tbody>
</table>
<p>
A <code>device</code> element in the <a>contacts database state</a> SHOULD render as a graphical control on the current web page.
</p>
<div
class="example">
<p
class="note">
Include example UI control for <code>device</code> element in the <a>contacts state</a>.
</p>
</div>
<p
class="note">
TBW: Passing parameters via <code>params</code> in to the UI control widget...
</p>
<p>
Once the user has selected the graphical control they MAY be presented with a modal, UI control widget dialog to select and review
contact sharing with the current web page. If the user selects one or more contacts from this dialog then:
</p>
<ol
class="rule">
<li>
The modal UI Widget control dialog used to select the contact objects MUST be terminated.
</li>
<li>
The originating <code>device</code> element's <code>data</code> attribute MUST be set to a corresponding <a
href="#contact-interface"><code>Contact</code></a> Array object (<code>Contact[]</code>).
</li>
<li>
The originating <code>device</code> element's <code>change</code> event MUST be triggered.
</li>
</ol>
<p
class="issue">
[[!HTML-DEVICE]] is not currently provisioned as being a HTML web form element. If serialization of the resulting data is required
for use in a web forms context neither the [[!HTML-DEVICE]] specification or this specification currently provide any
recommendations to that effect.
</p>
</section>
<section class="informative appendix">
<h3>
User Interaction Guidelines
</h3>
<p>
A website requests access to a user's address book with the following code:
</p>
<div
class="example">
<pre
class="sh_javascript">
<html>
<body>
<h1>Contacts API Test Page</h1>
<device type="contact" params="fields=name,emails;filter=Bob" onchange="successContactFindCallback(this.data)" />
<script type="text/javascript">
function successContactFindCallback(contacts) {
// do something with resulting contact objects
for (var i in contacts) alert(contacts[i].name.formatted);
// ...
}
</script>
</body>
</html>
</pre>
</div>
<p>
This page may render in the <a>user agent</a> as follows:
</p>
<p
class="note">
TODO: include rendered page mockup with <device> button-like rendering.
</p>
<p>
If the user clicks on the rendered device control, the <a>user agent</a> may provide the <a>contact picker</a>, utilising all of
the parameters provided in the originating device element.
</p>
<p
class="note">
TODO: The 'Remember these settings for this page' checkbox in the contact picker is not relevant in manual mode...
</p>
<p
align="center">
<img
src="contacts_picker.png"
alt="Contact Picker"><br>
(<a
href="contacts_picker.png">View as PNG</a>)
</p>
<p>
If the user clicks 'Cancel', then the user is returned to the page and no further action is taken.
</p>
<p>
If the user clicks 'Select', the <var>data</var> attribute of the originating device element is set to the contact
information selected by the user as defined in <a
href="#html-device-element-integration">HTML Device Element Integration</a>.
</p>
</section>
<section class='appendix'>
<h2>Acknowledgements</h2>
<p>
Many thanks to Wojciech Maslowski for helping to put this initial proposal together.
</p>
</section>
</body>
</html>
Received on Tuesday, 21 September 2010 13:53:44 UTC