Contact API HTML input element integration (was: Re: API patterns and requirements)

I split this second discussion about HTML input element integration from the
previous discussion.

HTML <input...> integration is not currently a part of the Contacts API spec
though I'd ultimately like to include this. This email explores <input...>
integration in light of Wojciech's feedback.

- Richard

2010/6/18 Wojciech Masłowski <wmaslowski@opera.com>
       W dniu 2010-06-17 16:23, Rich Tibbett pisze:

>
> 2. the 'result' and 'error' objects become a permanent well-known fixture
> on the DOM (@ navigator.contacts.request for Contacts and
> navigator.system.request for SysInfo). A common DOM node is useful if/when
> integrating such APIs with HTML <input...> elements (very much in a similar
> vein to the File API [2]).
>
> In an ideal world a Contact input element would be implemented as <input
> type="contact" ... /> which, on click, would bring up a 'contacts picker'
> [2]. When contacts are selected by the user and this element goes in to an
> equivalent of the 'File Upload' state, as defined in [3], the *.onsuccess
> (or *.onerror) callbacks above would be invoked according to whatever the
> current web app has specified.
>
> Final thought: we may want to bind access to navigator.contacts.* and
> navigator.system.* methods to click events (specifically, bind such methods
> to HTML anchor and button element click events only).
>
> The concept of having contact input field is interesting but I don't know
> if having them bound to global objects would be the cleanest solution. Lets
> say the web app wants to provide 2 buttons one to search for contacts and
> one to delete contact. In that case onsuccess callback would be called both
> for find and delete success which would probably lead to messy code?
>

We need to do this one step at a time so initially focussing on read
operations is a good start.

In the Contacts API there is only one read operation. When then considering
write operations we could do one of three things:

a. include a flag in the navigator.contacts.request interface that stores
the current operation type so it may be used in the resulting
navigator.contacts.request.onsuccess function.
b. define separate callback endpoints for different methods or method types:
e.g.
navigator.contacts.request.read.onsuccess,
navigator.contacts.request.write.onsuccess
c. make the callbacks of both search and delete functions equivalent (i.e.
make 'save' and 'delete' callbacks return the same object as the 'search'
callback).

I haven't explored this enough to know which is the best solution - we don't
yet have a detailed proposal yet - but this would naturally be covered in
any resulting proposal.


> Personally I'd rather have something like this:
> <input id="getcontacts" type="contact" properties="name,address"
> filter="work">
> ...
>
>  var el = document.getElementById("getcontacts");
>  el.addEventListener("contactSelected", doSthWithContacts, false);
>

Your event-bound method makes sense though it could probably use more common
event triggers (e.g 'loaded', 'progress', 'error'). The doSthWithContacts
function above would then look like this (?):

...
el.addEventListener("loaded", doSthWithContacts, false);
...
function doSthWithContacts(evt) {
    // get contact objects
    var contacts = evt.target.result;
    // do something with contacts... e.g.:
    for(i in contacts) alert(contacts[i].name.formatted);
}

I could live with something like that for HTML element access.

However, we could easily integrate the element with the serialization
proposal therefore minimizing the differences:

<input id="getcontacts" type="contact" properties="name,address"
filter="work">

...
el.addEventListener("change", doSthWithContacts, false);
...
function doSthWithContacts(evt) {
    // get contact objects
    var contacts = navigator.contacts.request.read.result;
    // do something with contacts... e.g.:
    for(i in contacts) alert(contacts[i].name.formatted);
}


For the programmatic access method, I still consider serial access as a
suitable proposal [1].

- Richard


[1] http://lists.w3.org/Archives/Public/public-device-apis/2010Jun/0200.html