RE: ACTION-19 contact api review / feedback

> On 7th Oct, 2009 10:41am, anssi.kostiainen@nokia.com wrote:
> 
> On 7.10.2009 4.42, "ext Brian LeRoux" 
> <brian@westcoastlogic.com> wrote:
> 
> > Groups can be very useful and, one use case in particular, 
> would be to 
> > support subsets of your contacts. For example: Friends, 
> Family, Work, 
> > Work Friends. Very helpful for filtering messages and 
> knowing whom is 
> > appropriate for that next chain email you need to send out.
> > 
> > I would like to recommend: MAY enable the ability to CRUD 
> groups of contacts.
> 
> +1

The subject of performance aside for a moment and focusing on the
current proposal [1]: if we add a category/rel field to the Contact
attributes then this should cover your use case for groups.

You would be able to perform CRUD either on the contact entries
themselves (CRUD on a global contact entry) or directly on the category
field of a given contact entry for the purposes of CRUDing groups.

In addition you would be able to filter and display groups using the
existing ContactFilter interface defined in [1].

Here's some (pseudo-)code based on the current proposal [1] with the
addition of a category attribute to allow for the CRUD and filtering of
groups:

var friends = /*...*/device.contacts.addressbook.find({ category:
'friends' });
for(var i=0; i<friends.length; i++) {
    // do something with all contacts that have a 'friend'
categorisation
}

> 
> > Something we ran into with PhoneGap was the need to 
> paginate results.
> > Some of the platforms support this out of the box. Others 
> don't seem 
> > to be worried about any user experience lag related to 
> painting 5000+ 
> > contacts to a mobile screen. At any rate, loading 1000's of contact 
> > object literals into an array was rather cpu intensive. I 
> would like 
> > to recommend:
> > 
> > SHOULD provide an interface for pagination of contacts listing.
> 
> The performance issue is a valid point. We could also use an 
> iterator to tackle this (see Nokia's strawman proposal for 
> Contacts API [1]). Yet another alternative would be to 
> combine an iterator with pagination (e.g.
> the API returns an iterator of arrays where each array 
> contains requested number of contact objects). Btw. this API 
> design decision has implications to other interfaces dealing 
> with large number of objects as well.
> 
> IMHO one potential downside of the iterator approach is that 
> it's not as convenient to work with as arrays. With arrays we 
> have built-in support for e.g. Array.prototype augmentation, 
> length property and useful array methods such as concat(), 
> push(), pop() etc.
> 
> For reference, Mozilla has been experimenting with iterators 
> in JavaScript
> 1.7 [2]. 
> 

On the subject of performance, I'd agree with a concept of pagination
over an iterator model. As pointed out an Iterator loses some
interesting Array.prototype methods such as length, push and pop.

In light of the current proposal [1] and to allow for pagination, how
about the addition of a (optional) contacts filter options attribute to
the device.contacts.addressbook.find method?

E.g.,

var friends = /*...*/device.contacts.addressbook.find({ category:
'friends' }, { limit: 10, page: 1 });
for(var i=0; i<friends.length; i++) {
    // do something with all contacts that have a 'friend'
categorisation...on page 1 
    // (max. no. of results in given example will be 10)
}

> > And finally I'd like to raise an issue. If we offer the idea of 
> > pagination then it wouldn't be too far to assume that a search 
> > interface should be offered. Thoughts?
> 
> Surely there should be a search interface. Otherwise 
> developers would end up fetching all the contacts and 
> searching though them in JavaScript which is slow if the 
> number of contacts is large. This UC can be implemented 
> without a specific interface, but there are performance concerns.
> 
> > In summary:
> > 
> > MAY enable the ability to CRUD groups of contacts.
> > SHOULD provide an interface for pagination of contacts listing.
> 
> I'd also add:
> 
> MAY provide an interface to search through contacts.

ContactFilter could already be considered a search interface over
Contacts records albeit a rigid search feature that is broken down to
individual attribute matching rather than a universal search over all
contact attributes.

I would rather make the existing ContactFilter interface more flexible
to allow AND/OR pattern matching across the available contact attributes
(thereby creating a more flexible universal search feature possible).
Currently ContactFilter is rigid in it's search but it could be made to
allow for more flexible search use cases:

Filter contacts that are in my ('friends' OR 'collegues') group AND are
based in the 'UK'.

OR

Search for the entered query string over any of the following contact
attributes: 'firstname', 'lastname', 'address', 'job', etc, etc and
return all matching results.

Furthermore, adapting the ContactFilter in to a more flexible search
mechanism still allows us to paginate results based on the addition of
ContactFilterOptions described above.


> > * * *
> > 
> > Not to get ahead of ourselves but on the topic of Contacts...
> > 
> > During my travels I came across the rather beautiful Google 
> > Contact API (not to be confused with the Android Contacts 
> > ContentProvider):
> > 
> > gContact:billingInformation
> > gContact:birthday
> > gContact:calendarLink
> > gContact:directoryServer
> > gContact:event
> > gContact:externalId
> > gContact:gender
> > gContact:groupMembershipInfo
> > gContact:hobby
> > gContact:initials
> > gContact:jot
> > gContact:language
> > gContact:maidenName
> > gContact:mileage
> > gContact:nickname
> > gContact:occupation
> > gContact:priority
> > gContact:relation
> > gContact:sensitivity
> > gContact:shortName
> > gContact:subject
> > gContact:systemGroup
> > gContact:userDefinedField
> > gContact:website
> 
> Some nice stuff there once you get past the namespace. Also 
> nice is Palms take:
> http://developer.palm.com/index.php?option=com_content&view=ar
ticle&id=1701
> >
> > My takeaway? We need to provide a schemaless object literal 
> > and not try to think too hard on all the possible properties 
> > a contact could potentially have.
> > 

I agree that the Contacts API properties proposed in [1] are not
particularly complete at the moment.

However, rather than going down a schemaless route I would prefer to
define a more extensive, interoperable base of properties and attributes
that a contact object should support with support for adding custom
properties as and when required. This will provide a clearer idea of the
fields that should be present in all implementations while still
allowing scope to allow for extensions as and when required.


On the subject of performance and async vs. sync contact searching, the
specification [1] could define a DEFAULT value for ContactFilterOptions
such as default page=1, default limit=200. This would keep contact
searching performant and synchronous but could be overridden by the
developer at their own peril.


Any feedback is of course welcome.


Best Regards,

Richard


[1] http://dev.w3.org/2009/dap/contacts/Overview.html

Received on Wednesday, 7 October 2009 11:44:43 UTC