Review of Contacts API against W3C

[Becky Gibson <gi...@gmail.com>]

I thought I would check the state of our Contacts API against the latest
W3C draft.  At this point I don't think there are enough changes to warrant
modifying the Cordova APIs except maybe for search.  We might consider
making search work better but I think at this point we are better off
waiting for the W3C to solidify the spec and decide what is happening with
Web Intents.

Here are the differences I noted in my review:

Current W3C Document just provides a Pick Intent.  We can ignore the Web
Intent based changes for now and focus on the Contact objects and
behaviors.   The only option now is "pick" which is just find.  There is no
api for creating contacts but we can keep what we have implemented with
Contacts.create and Contacts.find.

Most of the Contact objects are the same.  However the input to the pick
operation has changed.  Instead of two parameters of fields and
ContactFindOptions, there is now the ContactIntentExtras Dictionary (
http://www.w3.org/TR/contacts-api/#idl-def-ContactIntentExtras) that
combines the previous options:

ContactIntentExtras {
DomString search,
Unsigned long    limit,  // nullable
DomString[] fields
}

Thus, what used to be the find string in ContactFindOptions is now the
loosely defined search string and the boolean multiple is once again a
numeric limit.  The interesting change is the definition for search:

"search of type DOMString, nullable
A string which provides a hint to the contact service to facilitate
contacts selection by the user. The exact manner in which this hint is
exploited is entirely up to the contact service."

This gives us much more flexibility in implementing find.  Previously, in
the December, 2010 draft, find was defined as the item to search for within
the specified fields (where fields were the field types that were returned
in the found contact(s)).  We could add some rules to the search string to
allow people to search in specific fields rather than all of the returned
fields.  We could use a simple format like:

"searchTerm1, searchTerm2: searchField1, searchField2, … searchField#"

This would allow limiting the search term(s) to one of more fields rather
than the entire fields array of items to be returned.  Thus, to have all
name, address and phone number details returned for all contacts containing
"Smith" in the familyName field you could provide the following
ContentIntentExtras:

{search: "Smith: name.familyName", limit: NULL, fields: ["addresses",
"name", "phoneNumbers"]}

Since the previous draft from June, 2011, does not spell out all the find
details, we could also implement something similar to this now using the
current ContactFindOptions.filter field.

In addition, the ContactError object has been modified to just contain a
DomString with the error message rather than previously defined error code.

Re: Review of Contacts API against W3C

[Brian LeRoux <b...@brian.io>]

Thx for this Becky. Agree we should maybe add this analysis to the
wiki [1] (tho it too is in danger of getting dated) and hold out.

[1] http://wiki.apache.org/cordova/Core%20API%20Audit

On Tue, Jan 22, 2013 at 3:40 PM, Becky Gibson <gi...@gmail.com> wrote:
> I thought I would check the state of our Contacts API against the latest
> W3C draft.  At this point I don't think there are enough changes to warrant
> modifying the Cordova APIs except maybe for search.  We might consider
> making search work better but I think at this point we are better off
> waiting for the W3C to solidify the spec and decide what is happening with
> Web Intents.
>
> Here are the differences I noted in my review:
>
> Current W3C Document just provides a Pick Intent.  We can ignore the Web
> Intent based changes for now and focus on the Contact objects and
> behaviors.   The only option now is "pick" which is just find.  There is no
> api for creating contacts but we can keep what we have implemented with
> Contacts.create and Contacts.find.
>
> Most of the Contact objects are the same.  However the input to the pick
> operation has changed.  Instead of two parameters of fields and
> ContactFindOptions, there is now the ContactIntentExtras Dictionary (
> http://www.w3.org/TR/contacts-api/#idl-def-ContactIntentExtras) that
> combines the previous options:
>
> ContactIntentExtras {
> DomString search,
> Unsigned long    limit,  // nullable
> DomString[] fields
> }
>
> Thus, what used to be the find string in ContactFindOptions is now the
> loosely defined search string and the boolean multiple is once again a
> numeric limit.  The interesting change is the definition for search:
>
> "search of type DOMString, nullable
> A string which provides a hint to the contact service to facilitate
> contacts selection by the user. The exact manner in which this hint is
> exploited is entirely up to the contact service."
>
> This gives us much more flexibility in implementing find.  Previously, in
> the December, 2010 draft, find was defined as the item to search for within
> the specified fields (where fields were the field types that were returned
> in the found contact(s)).  We could add some rules to the search string to
> allow people to search in specific fields rather than all of the returned
> fields.  We could use a simple format like:
>
> "searchTerm1, searchTerm2: searchField1, searchField2, … searchField#"
>
> This would allow limiting the search term(s) to one of more fields rather
> than the entire fields array of items to be returned.  Thus, to have all
> name, address and phone number details returned for all contacts containing
> "Smith" in the familyName field you could provide the following
> ContentIntentExtras:
>
> {search: "Smith: name.familyName", limit: NULL, fields: ["addresses",
> "name", "phoneNumbers"]}
>
> Since the previous draft from June, 2011, does not spell out all the find
> details, we could also implement something similar to this now using the
> current ContactFindOptions.filter field.
>
> In addition, the ContactError object has been modified to just contain a
> DomString with the error message rather than previously defined error code.