This is part 4 in my series on Windows 8 apps for the PhoneGap developer.
It’s time to make contact with a user’s contacts! Since a user’s device is very personal to them, it often has their list of contacts. And it’s very common to build functionality into phone apps for interacting with a user’s contacts. PhoneGap certainly lets you do that!
The PhoneGap api provides a way for your app to get a single contact by searching for it, or get a list of contacts. The general pattern is to retrieve the contacts and display them in a UI so the user can pick one or more. Be warned, however – don’t try this if your phone has a lot of contacts, it will likely crash the app due to memory constraints. Below is the typical example you’ll see on how to get a list of contacts from the user’s phone. Note that it’s an asynchronous operation and as such has callback specified – one for success and one for failure – as well as some parameters to filter the returned results (which can be used to get around the memory limitations I mentioned above).
Windows 8 employs a different mechanism for selecting contacts. You write code that lets your app invoke what’s known as the contact picker. This displays an interactive selection box that allows the user to select one or more contacts (your choice) to be returned to the app.
Here is code that invokes the Contact picker and processes the returned results.
After the user chooses a contact and clicks the Submit button (the title is controlled by the commitButtonText property of the contactPicker), the contact data is returned to the app, which we then parse and display on the screen. There’s a helper method in this example called appendFields that formats things nicely for us.
A side effect of the design of the Windows 8 Contact picker is that you can’t programmatically add contacts to the People app. Now, you might be saying “Hey I have a lot of contacts my app needs to manage. How can I get those contacts added to the user’s contact list so they can work with them?”
Well, an interesting thing about Windows 8 is that when the user goes to pick things like contacts (or files or pictures for that matter), they have the option to select different applications as the source of contacts. This means if your application manages or retrieves information that provides “contact” like data (your company’s personnel database, some online list like the user’s Pinterest friends, or perhaps collaborators in a github project) you can have your application be a source of contacts for any other application on the user’s machine from which they could pick contacts. That means if they’re in the mail app and want to email someone from a contact list you application provides, when they go to pick a contact in their email app, your app’s “contact picker page” that you have defined in your manifest file.
The quickstart for managing contacts has the full sample, but the main things you do is create a contact picker page that other apps (or even your app) will use, then register your app as a contact extension. Here’s what the custom Contact Picker screen from that sample app provides. Keep in mind that now, any other app that wants to pick contacts can use this sample app as its source.
Certainly you’d pretty it up a bit, but being able to show this type of cool selection box and return one or more contacts is pretty powerful.
In the above screenshot, the blue bars at the top and bottom are system provided. The user can switch between contact providers by clicking at the top where it now says ContactPicker JS sample. The Select and Cancel buttons at the bottom live in the collection area. The way this code is written, as the user clicks the checkbox next to each name, it is added to the collection of contacts to be returned, and displayed in the collection area.
In the project’s manifest file (below), you can see that we’ve declared our app a Contact Picker itself, and when it’s invoked in that way, the start page will be the contactPicker.html page.