View source for ContactsMozDapComparison

This is a comparison between the [http://mozillalabs.com/blog/2010/03/contacts-in-the-browser Mozilla Contacts Add-on] and the latest [http://dev.w3.org/2009/dap/contacts/ W3C Contacts API] draft.

== Summary == 

* Mozilla implementation is read-only at this stage (webapps can read contacts but not create, update or delete contacts). 
* Of the read-only parts of the W3C Contacts API all methods are implemented (i.e. find), with only the ordering of parameters being different between the Mozilla implementation and the W3C spec (+ API endpoint names are different). 
* Success and Error API callbacks are consistent with the W3C Contacts API. 
* User Experience and User Interaction conform to the current Privacy and Security Considerations included in the specification.

== API Endpoint ==

* MOZ: <code>navigator.people</code>
* W3C: <code>[http://dev.w3.org/2009/dap/contacts/Overview.html#servicecontacts-interface navigator.service.contacts]</code>

Having the two separate endpoints is probably a really good idea in the short term to avoid polluting any official endpoint navigator object - whatever that will be. Let's not get in to another bikeshed discussion on this just now ;-)

== API read methods ==

Both the W3C API and Mozilla API include a 'find' method:

* MOZ: <code>find(options, fields, successCallback, errorCallback)</code>
* W3C: <code>[http://dev.w3.org/2009/dap/contacts/Overview.html#widl-Contacts-find find(fields, successCallback, errorCallback, options)]</code>

Comparing the two, the only difference seems to be that Mozilla place '<code>options</code>' as the first parameter compared to the W3C spec setting
'<code>options</code>' as the last parameter. It should be noted that the actual '<code>options</code>' accepted by the Mozilla API is unclear to me at this stage. In the Mozilla API demo, the '<code>options</code>' parameter is an empty object <code>{}</code>, whereas in the W3C API this parameter would not need to be included if <code>{}</code>/<code>null</code> - hence the reason it is set as the last parameter in the W3C spec.

=== Minimization ===

The concept of 'minimization' requires that a web app request the attributes required from Contact objects (the '<code>[http://dev.w3.org/2009/dap/contacts/Overview.html#widl-Contacts-find fields]</code>' parameter). The
user can then accept or reject the fields requested from the web app via the Contacts Picker UI. The Mozilla API have implemented this concept which is included in the W3C API. The W3C API needs more normative description around this.

=== One Contact Object by default ===

The W3C API includes a '<code>[http://dev.w3.org/2009/dap/contacts/Overview.html#widl-ContactFindOptions-multiple multiple]</code>' options attribute. By default, the W3C Contacts Picker should return only one Contact object. If the <code>multiple</code> attribute is present in a W3C API <code>find(..)</code> request, the Contacts Picker is then capable of returning x Contact objects - where x is the value of the '<code>[http://dev.w3.org/2009/dap/contacts/Overview.html#widl-ContactFindOptions-limit limit]</code>' options attribute or infinity (i.e. the upper-bound is not specified). The model for this proposal is taken from the [http://www.w3.org/TR/html5/forms.html#attr-input-multiple W3C HTML5 File Input control]. Again, this needs more description in the W3C spec which I will work on in the coming days.

=== Pending Operations ===

The Mozilla implementation does not return a [http://dev.w3.org/2009/dap/contacts/Overview.html#idl-def-Contacts <code>PendingOp</code> object from the <code>find(..)</code> method] as defined in the [http://dev.w3.org/2009/dap/device/#the-pendingop-interface DAP Core Device Interfaces Spec]. The PendingOp object is intended as a way for the requesting web application to cancel the request for Contact information before the user may have completed the process. This may be useful in a number of cases e.g. on webapp specified timeout / after a related async operation completes or after any other event(s) that may have occured that may negate the need for the user to select the Contacts that have been previously requested by the webapp. Further feedback on this aspect would be interesting for other APIs also as this is a pattern in use across DAP APIs currently.

== API read callbacks ==

The successCallback and errorCallback Mozilla implementation for <code>find(...)</code> is identical to that defined in the W3C Contacts API.

* MOZ: <code>successCallback(Contact[])</code>
* W3C: <code>[http://dev.w3.org/2009/dap/contacts/Overview.html#idl-def-ContactFindSuccessCB successCallback(Contact[]])</code>

Resulting Contact objects seem to match to a large degree (to be discussed wrt Portable Contacts usage).

* MOZ: <code>errorCallback(Error)</code>
* W3C: <code>[http://dev.w3.org/2009/dap/contacts/Overview.html#idl-def-ContactErrorCB errorCallback(Error)]</code>

== API write methods ==

* MOZ: Read-only API and therefore only provides the <code>[http://dev.w3.org/2009/dap/contacts/Overview.html#widl-Contacts-find find(...)]</code> method detailed above.
* W3C: Read and write API. Two write methods: <code>[http://dev.w3.org/2009/dap/contacts/Overview.html#widl-Contact-save save(...)]</code>, <code>[http://dev.w3.org/2009/dap/contacts/Overview.html#widl-Contact-remove remove(...)]</code> and two write helper methods <code>[http://dev.w3.org/2009/dap/contacts/Overview.html#widl-Contacts-create create(...)]</code>, <code>[http://dev.w3.org/2009/dap/contacts/Overview.html#widl-Contact-clone clone()]</code> not implemented by Mozilla.

It would be interesting to get more info on whether write methods are in the roadmap of the Mozilla implementation.

== Auto-Complete on &lt;input type='text'/&gt; ==

My understanding is this: the Mozilla implementation auto-detects input text fields with a name attribute of '<code>email</code>'. Autocomplete then applies to these input elements, managed from the UA rather than any API.

An auto-complete API has been discussed in this W3C group. The discussion ended with the suggestion that auto-complete would be a
product of web app and/or UA coding rather than requiring any special API 'autocomplete' call(s). The Mozilla implementation seems to support this view.

It seems reasonable to leave auto-complete functionality/implementation to the developers - though perhaps some guidelines/requirements around UI could be useful in the W3C spec according to what Mozilla have demonstrated.

== Privacy and Security Considerations ==

There is considerable activity around the 'Security and Privacy' sections included in most W3C DAP API specs - including the [http://dev.w3.org/2009/dap/contacts/Overview.html#security-and-privacy-considerations Contacts API Security and Privacy Considerations]. However, based on the current text, the Mozilla implementation is a good example of the effectiveness of leaving UI considerations to implementers. The innovation demonstrated aids in our understanding of the requirements required and is likely to help us refine these sections in the specs. That's not to say we don't need to do more in the W3C Security and Privacy sections - we probably do - just that early implementations such as Mozilla Contacts help to inform us on the requirements better.

The Mozilla implementation presents a non-modal dialog asking the user whether they would like to share address book information with the requesting web application. On clicking 'Allow Access...' the user is then presented with a modal dialog to select the Contacts to share. The workflow of the user is respected with this implementation. The user is not interrupted during their workflow and direct interaction with the non-modal informational bar results in a 'confirmation' modal Contact Picker dialog - allowing the user to select and control the data to exchange with the web application at a granualar level. It could have been confusing but the Mozilla implementation shows this working really nicely (IMO).

Furthermore, the implementation allows users to view permissions previously granted, revoke provided permissions and manage their contact information via chrome-based urls. This is inline with the [http://dev.w3.org/2009/dap/contacts/Overview.html#security-and-privacy-considerations Security and Privacy requirements included in the W3C Contacts API].