android contact list example

[thegrymek]

Hi,

I want to share android version of contact list. There's example, facade and android implementation.
Could you review and check it on your phones?

Thanks!
best regards

[tito]

Documentation lack of knowing the exact format of the contact list, and usage. The attached example is too complex to understand, but demonstrate it.

Could you explain how a contact is structured? What field are always here, the one that are optional? Best would be to give an output example like:

>>> from plyer import Contacts
>>> Contacts.refresh()
>>> print "I have {} contacts".format(len(Contacts))
I have 3 contacts
>>> print Contacts[0]
{ .... }

[thegrymek]

These two links give you a glance to know how its structured:
http://developer.android.com/images/providers/contacts_structure.png

and scroll to the down to know how look tables:
http://xianminx.github.io/2012/06/24/android-contact-provider-in-deep/

Contacts and other data like emails or groups are in sqlite database. Everything we can get by making a query.

>>> print Contacts[0]
{
  'contact_id': 150,
  'display_name': 'Johny W'
  'has_phone_number': '2',
  'phone_numbers': [ '111-111-111', '111-111-112']
}

>>> print "I have {} contacts".format(len(Contacts))
I have 5 contacts
>>> print [contact for contact in Contacts]
[{ 'contact_id':... , 'display_name':...  }]

I have added that features in last commit.

My propose is to do make Contacts even like that

>>> contact = Contacts[5]
>>> print Contacts.get_phones(contact.id)
['111-111-111', '111-111-112']
>>> print contact.phones
['111-111-111', '111-111-112']
>>> groups = Contacts.get_groups()
>>> contact.groups[0] in groups
True
>>> contact in groups[0].contacts
True

[tito]

That's great! Now, you need to get a little step outside the implementation to look at the result, and ask yourself: is it good and simple enough? is the format will works into other platforms (iOS ?)

The latest is too close on the android implementation (with column, query etc.).
The API is 1:1 android query / field name, obvsiouly, this wont work on iOS the same, and will put all the work on translating / mapping to the iOS implementation

Now that i've seen the output format (is it the whole thing, or not? If you have any non-documented field, they MUST be documented. The user will not check the android nor ios documentation to see if a field exist or not.)

Let's take your example:

{
  'contact_id': 150,
  'display_name': 'Johny W'
  'has_phone_number': '2',
  'phone_numbers': [ '111-111-111', '111-111-112']
}

Field like "has_phone_number" is redundant. It has a meaning in a db (to prevent subquery), but here on a result, you can always have a "phone_numbers", and if you want to know how much, just use len().

Right now, best would be:

• List all the fields (they can have another name, it doesn't have to be the exact same as Android) you wish to expose in the Contacts API
• Document them
• Do an implementation for Android

Be platform-abstract :)

[tito]

And forget about the query() API right now, focus on the what you want in field in the API, ensure the format / naming you choose would be ok for all the platform, then you focus on Android.

[thegrymek]

As I looked up to other platforms I've noticed that only ID fields are required. Rest are optional, even display_name

In doc, below of facade/Contacts class I listed only 3 fields because rest of all are not implemented. Should I add a more fields - even if there is no implementation from android side?

I didnt add any mapper to that commit, because I think it would be great for another topic for next pull request. Add my propose of "fields mapper" here or in the another branch?

[Julian-O]

Would the reviewers care to give a status on this one? Can we close it or merge it?