Quickstart: Selecting user contacts (HTML)
Through the Windows.ApplicationModel.Contacts namespace, you have several options for selecting contacts. Here, we'll show you how to select a single contact or multiple contacts, and we'll show you how to configure the contact picker to retrieve only the contact information that your app needs.
Prerequisites
- We recommend that you be familiar with Microsoft Visual Studio and its associated templates.
- We recommend that you be familiar with JavaScript.
Set up the contact picker
Create an instance of Windows.ApplicationModel.Contacts.ContactPicker and assign it to a variable.
var picker = Windows.ApplicationModel.Contacts.ContactPicker();
Provide a name for the commit button
The commit button is the button that the user presses to confirm the contact that they selected. Set the name of this button with Windows.ApplicationModel.Contacts.CommitButtonText.
picker.commitButtonText = "Select";
Set the selection mode (optional)
By default, the contact picker retrieves all of the available data for the contacts that the user selects. The selectionMode property lets you configure the contact picker to retrieve only the data fields that your app needs. This is a more efficient way to use the contact picker if you only need a subset of the available contact data.
First, set the selectionMode property to fields:
picker.selectionMode = Windows.ApplicationModel.Contacts.ContactSelectionMode.fields;
Then, use the desiredFieldsWithContactFieldType property to specify the fields that you want the contact picker to retrieve. This example configures the contact picker to retrieve email addresses:
picker.desiredFieldsWithContactFieldType.append(Windows.ApplicationModel.Contacts.ContactFieldType.email);
Launch the picker
Now you can launch the picker. Use pickContactAsync if you want the user to select only one contact. To process the contact that the user selects, use done to call a function to process the contact that the picker returns.
picker.pickContactAsync().done(function (contact) {
if (contact !== null) {
// Create UI to display the contact information for the selected contact
var contactElement = document.createElement("div");
contactElement.className = "contact";
// Display the name
contactElement.appendChild(createTextElement("h3", contact.displayName));
Use pickContactsAsync if you want the user to select one or more contacts. To process the contacts that the user selects, use done to call a function to process the contact that the picker returns.
picker.pickContactsAsync().done(function (contacts) {
if (contacts.length > 0) {
// Display the selected contact names
var output = "Selected contacts:\n";
contacts.forEach(function (contact) {
output += contact.displayName + "\n";
});
Complete example (single contact)
This example uses the contact picker to retrieve a single contact's name, email addresses, phone numbers, and addresses.
(function () {
"use strict";
var page = WinJS.UI.Pages.define("/html/scenarioSingle.html", {
ready: function (element, options) {
// Use element.querySelector() instead of document.getElementById() to ensure that the correct default.html page is targeted.
element.querySelector("#open").addEventListener("click", pickContact, false);
}
});
function pickContact() {
// Clean scenario output
WinJS.log && WinJS.log("", "sample", "status");
// Create the picker
var picker = new Windows.ApplicationModel.Contacts.ContactPicker();
picker.commitButtonText = "Select";
// Open the picker for the user to select a contact
picker.pickContactAsync().done(function (contact) {
if (contact !== null) {
// Create UI to display the contact information for the selected contact
var contactElement = document.createElement("div");
contactElement.className = "contact";
// Display the name
contactElement.appendChild(createTextElement("h3", contact.displayName));
// Add the different types of contact data
if (contact.emails.length > 0) {
contactElement.appendChild(createTextElement("h4", "Emails:"));
contact.emails.forEach(function (email) {
switch (email.kind) {
case Windows.ApplicationModel.Contacts.ContactEmailKind.personal:
contactElement.appendChild(createTextElement("div", email.address + " (personal)"));
break;
case Windows.ApplicationModel.Contacts.ContactEmailKind.work:
contactElement.appendChild(createTextElement("div", email.address + " (work)"));
break;
case Windows.ApplicationModel.Contacts.ContactEmailKind.other:
contactElement.appendChild(createTextElement("div", email.address + " (other)"));
break;
}
});
}
if (contact.phones.length > 0) {
contactElement.appendChild(createTextElement("h4", "Phone Numbers:"));
contact.phones.forEach(function (phone) {
switch (phone.kind) {
case Windows.ApplicationModel.Contacts.ContactPhoneKind.home:
contactElement.appendChild(createTextElement("div", phone.number + " (home)" ));
break;
case Windows.ApplicationModel.Contacts.ContactPhoneKind.work:
contactElement.appendChild(createTextElement("div", phone.number + " (work)" ));
break;
case Windows.ApplicationModel.Contacts.ContactPhoneKind.mobile:
contactElement.appendChild(createTextElement("div", phone.number + " (mobile)" ));
break;
case Windows.ApplicationModel.Contacts.ContactPhoneKind.other:
contactElement.appendChild(createTextElement("div", phone.number + " (other)" ));
break;
}
});
}
if (contact.addresses.length > 0) {
contactElement.appendChild(createTextElement("h4", "Addresses:"));
contact.addresses.forEach(function (address) {
switch (address.kind) {
case Windows.ApplicationModel.Contacts.ContactAddressKind.home:
contactElement.appendChild(createTextElement("div", getUnstructuredAddress(address) + " (home)" ));
break;
case Windows.ApplicationModel.Contacts.ContactAddressKind.work:
contactElement.appendChild(createTextElement("div", getUnstructuredAddress(address) + " (work)"));
break;
case Windows.ApplicationModel.Contacts.ContactAddressKind.other:
contactElement.appendChild(createTextElement("div", getUnstructuredAddress(address) + " (other)"));
break;
}
});
}
// Add the contact element to the page
document.getElementById("output").appendChild(contactElement);
} else {
// The picker was dismissed without selecting a contact
WinJS.log && WinJS.log("No contact was selected", "sample", "status");
}
});
}
function createTextElement(tag, text) {
var element = document.createElement(tag);
element.className = "singleLineText";
element.innerText = text;
return element;
}
function getUnstructuredAddress(contactAddress) {
var unstructuredAddress = contactAddress.streetAddress + ", " + contactAddress.locality + ", " + contactAddress.region + ", " + contactAddress.postalCode;
return unstructuredAddress;
}
})();
Complete example (multiple contacts)
This example uses the contact picker to retrieve multiple contacts and then displays the contact names.
(function () {
"use strict";
var page = WinJS.UI.Pages.define("/html/scenarioMultiple.html", {
ready: function (element, options) {
// Use element.querySelector() instead of document.getElementById() to ensure that the correct default.html page is targeted.
element.querySelector("#open").addEventListener("click", pickContacts, false);
}
});
function pickContacts() {
// Clean scenario output
WinJS.log && WinJS.log("", "sample", "status");
// Create the picker
var picker = new Windows.ApplicationModel.Contacts.ContactPicker();
picker.commitButtonText = "Select";
// Open the picker for the user to select contacts
picker.pickContactsAsync().done(function (contacts) {
if (contacts.length > 0) {
// Display the selected contact names
var output = "Selected contacts:\n";
contacts.forEach(function (contact) {
output += contact.displayName + "\n";
});
WinJS.log && WinJS.log(output, "sample", "status");
} else {
// The picker was dismissed without selecting any contacts
WinJS.log && WinJS.log("No contacts were selected", "sample", "status");
}
});
}
})();
Summary and next steps
Now you have a basic understanding of how to use the contact picker to retrieve contact information. Download the Contact Picker app sample from the code gallery to see more examples of how to use contacts and the contact picker.