cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Becky Gibson <>
Subject Review of Contacts API against W3C
Date Tue, 22 Jan 2013 21:40:56 GMT
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 ( 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

{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.

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message