This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
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.
Information presented in this document is for informational purposes only, and does not reflect final choices in the integration of Device APIs with HTML within Opera or elsewhere. As such, this document or the need to work on this document has not been formall ratified by the W3C.
Other routes for integrating Device API access with HTML are also being explored on an active basis within the W3C DAP Working Group.
All comments on this draft should be directed to the W3C DAP mailing list.
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.
This specification builds on the existing HTML device
element [[!HTML-DEVICE]].
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.
...
The following code illustrates how to obtain contact information from a user's address book.
<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>
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.
Feedback on this section is encouraged from implementors.
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.
The device
element's type
attribute MUST be set to contact to indicate the device element is in the contacts
state, according to the table below.
Keyword | State | Device Description | Example |
---|---|---|---|
contact
|
Contacts | Contacts Database/Storage | Access to a group of contacts residing on the user's system or in the current user agent. |
A device
element in the contacts database state SHOULD render as a graphical control on the current web page.
TBW: Passing parameters via params
in to the UI control widget...
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:
device
element's data
attribute MUST be set to a corresponding Contact
Array object (Contact[]
) as defined in [[!CONTACTS-API]].
device
element's change
event MUST be triggered.
[[!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.
A website requests access to a user's address book with the following code:
<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>
This page may render in the user agent as follows:
If the user clicks on the rendered device control, the user agent may provide the contact picker, utilising all of the parameters provided in the originating device element.
If the user clicks 'Cancel', then the user is returned to the page and no further action is taken.
If the user clicks 'Select', the data attribute of the originating device element is set to the contact information selected by the user as defined in HTML Device Element Integration.
Many thanks to Wojciech Maslowski for helping to put this initial proposal together.