Skip to content

Latest commit

 

History

History
97 lines (79 loc) · 4.26 KB

README.md

File metadata and controls

97 lines (79 loc) · 4.26 KB
Raw

ZLPeoplePickerViewController

A replacement for ABPeoplePickerNavigationController that supports UILocalized​Indexed​Collation. ZLPeoplePickerViewController was originally created for Talkly.

Why?

ABPeoplePickerNavigationController does not work well with contact names of multiple languages, neither does some address book based app that worths $16 billion. Here are some examples:

And this is how it should have been:

Preview

###Present ABPersonViewController on select ABPersonViewController ###Send group emails on return Group Emails ###Custom Multiple Select Custom Multiple Select

Features

  • Supports multilingual indexing and sorting by implementing UILocalized​Indexed​Collation using LRIndexedCollationWithSearch.
  • Supports searching by name, emails and addresses. The results are displayed using UISearchController in iOS 8.
  • Supports multiple selection.
  • Supports field mask for filtering contacts.
  • Support searching by phone number

CocoaPods

You can install ZLPeoplePickerViewController through CocoaPods adding the following to your Podfile:

pod 'ZLPeoplePickerViewController'

Usage

Check out the demo app for an example.

ZLPeoplePickerViewController can be initialized and pushed to navigation controller in a way similar to ABPeoplePickerNavigationController:

self.peoplePicker = [[ZLPeoplePickerViewController alloc] init];
self.peoplePicker.delegate = self;
[self.navigationController pushViewController:self.peoplePicker animated:YES];

There is also a convenience method for presenting the people picker modally.

self.peoplePicker = [ZLPeoplePickerViewController presentPeoplePickerViewControllerForParentViewController:self];

Loading a large address book may take a long time. Therefore ZLPeoplePickerViewController caches it in memory after initialization. You can further reduce the first-time delay by initializing the address book with the following class method in advance (for instance, in viewDidLoad).

+ (void)initializeAddressBook;

ZLPeoplePickerViewController uses the fieldMask property to filter contacts, graying out those that have missing information. Currently supported fields inlucde emails, photo and addresses.

@property (nonatomic) ZLContactField filedMask;

The numberOfSelectedPeople property controls the multiple selection behavior. It indicates the maximum number of people the picker can select at a time.

@property (nonatomic) ZLNumSelection numberOfSelectedPeople;

ZLPeoplePickerViewController can have an optional delegate to receive callback.

- (void)peoplePickerViewController:(ZLPeoplePickerViewController *)peoplePicker didSelectPerson:(NSNumber *)recordId {
  // show an ABPersonViewController
  [self showPersonViewController:[recordId intValue] onNavigationController:peoplePicker.navigationController];
}
- (void)peoplePickerViewController:(ZLPeoplePickerViewController *)peoplePicker didReturnWithSelectedPeople:(NSArray *)people {
  // people will be empty if no person is selected
  if (!people || people.count==0) {return;}
  [self presentViewController: [self alertControllerWithTitle:@"Return with selected people:" Message:[[self firstNameForPeople:people] componentsJoinedByString:@", "]] animated:YES completion:nil];
}
- (void)newPersonViewControllerDidCompleteWithNewPerson:(nullable ABRecordRef)person {
    NSLog(@"Added a new person");
}

Dependencies

ZLPeoplePickerViewController uses APAddressBook internally for accessing address book. It requires APAddressBook.

Requirements

  • iOS 8 or higher.
  • Automatic Reference Counting (ARC).

License

ZLPeoplePickerViewController is available under MIT license. See the LICENSE file for more info.