Mailing-List: contact dev-help@cordova.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cordova.apache.org
Received-SPF: pass (nike.apache.org: domain of brian.leroux@gmail.com
 designates 209.85.220.169 as permitted sender)
MIME-Version: 1.0
Sender: brian.leroux@gmail.com
In-Reply-To: 
 <CADjNb+mroL8jJTU32uknE47QK_2mQjdp1VzZ8hetDxnaf3z=CQ@mail.gmail.com>
References: 
 <CADjNb+mroL8jJTU32uknE47QK_2mQjdp1VzZ8hetDxnaf3z=CQ@mail.gmail.com>
Date: Tue, 22 Jan 2013 16:04:56 -0600
Message-ID: 
 <CADVgkyOf5NiSZvt39g=73XAKSuVhk4Co95badM-m2LiH6mRKnA@mail.gmail.com>
Subject: Re: Review of Contacts API against W3C
From: Brian LeRoux <b@brian.io>
To: dev@cordova.apache.org
Content-Type: text/plain; charset=windows-1252
Content-Transfer-Encoding: quoted-printable

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 <gibson.becky@gmail.com> wrot=
e:
> 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 warra=
nt
> 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 wit=
h
> 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 with=
in
> the specified fields (where fields were the field types that were returne=
d
> in the found contact(s)).  We could add some rules to the search string t=
o
> 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, =85 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 containi=
ng
> "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 cod=
e.