This specification defines HTML enhancements that provide access to a user's address book.

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.

Introduction

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>

HTML Device Element Integration

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:

  1. The modal UI Widget control dialog used to select the contact objects MUST be terminated.
  2. The originating device element's data attribute MUST be set to a corresponding Contact Array object (Contact[]) as defined in [[!CONTACTS-API]].
  3. The originating 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.

User Interaction Guidelines

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:

Device Element in Contacts State
(View as PNG)

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.

Contact Picker
(View as PNG)

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.

Acknowledgements

Many thanks to Wojciech Maslowski for helping to put this initial proposal together.