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 <[email protected]> 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.
