[TIMOB-176] API - Contacts Dialog
| GitHub Issue | n/a |
|---|---|
| Type | Bug |
| Priority | Medium |
| Status | Closed |
| Resolution | Fixed |
| Resolution Date | 2011-04-17T01:52:14.000+0000 |
| Affected Version/s | n/a |
| Fix Version/s | Release 0.8.0 |
| Components | iOS |
| Labels | feature, ios, iphone |
| Reporter | Nolan Wright |
| Assignee | Blain Hamon |
| Created | 2011-04-15T02:24:48.000+0000 |
| Updated | 2011-04-17T01:52:14.000+0000 |
Description
Description
The purpose of this API is to display a contacts dialog and allow a user to select a contact
Examples
//
// show contact picker
//
//
// if array of details is specified, the detail view will be shown
// when the contact is selected. this will also trigger e.key, and e.index in the success callback
//
Titanium.Contacts.showContactPicker({
success:function(event)
{
// e.contact
// e.key
// e.index
},
cancel:function()
{
// user canceled
},
details:[array of constants]
);
//
// Supported Contact property names
//
firstName
lastName
middleName
prefix
suffix
nickname
firstNamePhonetic
lastNamePhonetic
middleNamePhonetic
organization
jobTitle
department
birthday
note
creationDate
modificationDate
imageData
phoneNumber
address
email
//
// get all contacts
//
var contacts = Titanium.Contacts.getAllContacts()
var c = contacts[0];
var birthday = c.birthday
// remove contact
Titanium.Contacts.removeContact(c);
// modify contact
c.firstName = 'Fred';
Titanium.Contacts.saveContact(c);
//
// create new contact
//
var c = Titanium.Contacts.createContact({
firstName:'Fred',
lastName:'Smith'
})
Titanium.Contacts.addContact(c);
//
// create new contact using multi-value fields like email, phone and address
//
var c = Titanium.Contacts.createContact({
email:[{label:'home', value:'foo@foo.com'}],
phone:[{label:'home', value:'3032223333'}],
address:[{label:'home', value:[{city:'Foo', state:'GA', zip:'40344', street1:'value', street2:'value'}]
})
We'll probably want to add functionality later on for being able to pick not only a person, but other UI features:
Pick a person and a property (IE, phone number out of several), complete with a filter of what to show.
(See http://developer.apple.com/IPhone/library/documentation/AddressBookUI/Reference/ABPeoplePickerNavigationControllerDelegate_Protocol/Reference/Reference.html#//apple_ref/occ/intfm/ABPeoplePickerNavigationControllerDelegate/peoplePickerNavigationController:shouldContinueAfterSelectingPerson:property:identifier"> http://developer.apple.com/IPhone/library/documentation/AddressBook...: )
View a person that's been chosen from the database, filter of what to show, allow editing of it, etc. The callback should return a boolean on whether to act on user input. (IE, if the user touched the phone number, to launch the phone)
(See http://developer.apple.com/IPhone/library/documentation/AddressBookUI/Reference/ABPersonViewController_Class/Reference/Reference.html"> http://developer.apple.com/IPhone/library/documentation/AddressBook... )
Present an 'add a person' dialog, with prepopulated properties, and let them add it to the address book.
(See http://developer.apple.com/IPhone/library/documentation/AddressBookUI/Reference/ABNewPersonViewController_Class/Reference/Reference.html"> http://developer.apple.com/IPhone/library/documentation/AddressBook... )
Present an 'unknown person' (IE, could be new person, could be old person and the data needs merging) which has the new person dynamicness as well as the ability to launch actions like view a person.
(See http://developer.apple.com/IPhone/library/documentation/AddressBookUI/Reference/ABUnknownPersonViewController_Class/Reference/Reference.html"> http://developer.apple.com/IPhone/library/documentation/AddressBook... )
Notes to self:
More flies in the ointment. While the properties are integers on the native side, accessing images are done with a completely different function. Fetching this all for getAllContacts is prohibitive. The image blobs alone would take too much memory all at one time.
Not only that, but it's unlikely that Android will have the same values. So perhaps we should use string values and do the mapping native-side.
So the data sent to the callback must be an array of lazy-loading objects with the following properties:
_REFID:,
_CACHE:{dict of fetched values},
_DELTA:{dict of js-set values},
getFoo:function(){
if(this.DELTA.foo)return this.DELTA.foo;
if(this.CACHE.foo===undefined)this.CACHE.foo = Ti.TIDO('contacts','getContactProperty',[this.REFID,'foo']);
return this._CACHE.foo;
},
setFoo:function(newFoo){this._DELTA.foo=newFoo;}
appropriate setters and getters for every foo. I'm thinking making an object class for this. The win here also is that there need not be any native-side caching contacts, and when saving a contact, only the delta need be sent back.
Actually, this pattern may be very useful in other objects.
this is mostly implemented and tested for iphone.
however, it crashes when you pass
@symbol to email property when creating a contact.Ready for testing.
add read only properties w/ getters.
displayLabel (map to display value in "pick list" style, e.g. Company if no person name)
displayName (constructed from Person Name Attributes Prefix, First, Middle, Last Suffix)
displayAddress (Address String a concatenation of the pieces)
displayPhoneticName (same as displayName using phonetic values, does not include prefix and suffix)
Ready for testing.