Quickstart: Selecting user contacts (Windows Store apps using JavaScript and HTML) (Windows)

Language: JavaScript and HTML | VB/C#/C++ and XAML

1 out of 2 rated this helpful - Rate this topic

In this article

Prerequisites
Set up the contact picker
Provide a name for the commit button
Set the selection mode (optional)
Launch the picker
Complete example (single contact)
Complete example (multiple contacts)
Summary and next steps
Related topics

Important APIs

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

You should be familiar with Microsoft Visual Studio 2012 and its associated templates.
You should be familiar with JavaScript.

Set up the contact picker

Create an instance of Windows.ApplicationModel.Contacts.ContactPicker and assign it to a variable.

JavaScript


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.

JavaScript


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:

JavaScript


picker.selectionMode = Windows.ApplicationModel.Contacts.ContactSelectionMode.fields;

Then, use the desiredFields property to specify the fields that you want the contact picker to retrieve. This example configures the contact picker to retrieve email addresses:

JavaScript


picker.desiredFields.append(Windows.ApplicationModel.Contacts.KnownContactField.email);

Launch the picker

Now you can launch the picker. Use pickSingleContactAsync if you want the user to select only one contact. To process the contact that the user selects, use then to call a function to process the contact that the picker returns.

JavaScript


picker.pickSingleContactAsync().then(function (contact) {
    var contactElement = document.createElement("div");
    contactElement.innerText = contact.name + " " + contact.emails[0].value;
    document.body.appendChild(contactElement);
});

Use pickMultipleContactsAsync if you want the user to select one or more contacts. To process the contacts that the user selects, use then to call a function to process the contact that the picker returns.

JavaScript


picker.pickMultipleContactsAsync().then(function (contacts) {
    contacts.forEach(function (contact) {
        var contactElement = document.createElement("div");
        contactElement.innerText = contact.name;
    });
});

Complete example (single contact)

This example uses the contact picker to retrieve a single contact's name, email addresses, phone numbers, and addresses.

JavaScript


function pickContact() {
    // Verify that the app is unsnapped or can unsnap to open the picker.
    var viewState = Windows.UI.ViewManagement.ApplicationView.value;
    if (viewState === Windows.UI.ViewManagement.ApplicationViewState.snapped &&
        !Windows.UI.ViewManagement.ApplicationView.tryUnsnap()) {
        // Fail silently if we can't unsnap.
        return;
    };

    // Create the picker.
    var picker = new Windows.ApplicationModel.Contacts.ContactPicker();
    picker.commitButtonText = "Select";

    // Open the picker for the user to select a contact.
    picker.pickSingleContactAsync().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 contact name.
            contactElement.appendChild(createTextElement("h3", contact.name));

            // Add the different types of contact data.
            appendFields("Emails:", contact.emails, contactElement);
            appendFields("Phone Numbers:", contact.phoneNumbers, contactElement);
            appendFields("Addresses:", contact.locations, contactElement);

            // Add the contact element to the page.
            document.getElementById("output").appendChild(contactElement);
        }
    });
}

function appendFields(title, fields, container) {
    // Create UI for a list of contact fields of the same type, such as email 
    // addresses or phone numbers.
    fields.forEach(function (field) {
        if (field.value) {
            // Append the title once we have a non-empty contact field.
            if (title) {
                container.appendChild(createTextElement("h4", title));
                title = "";
            }

            // Display the category next to the field value
            switch (field.category) {
                case Windows.ApplicationModel.Contacts.ContactFieldCategory.home:
                    container.appendChild(createTextElement("div", field.value + " (home)"));
                    break;
                case Windows.ApplicationModel.Contacts.ContactFieldCategory.work:
                    container.appendChild(createTextElement("div", field.value + " (work)"));
                    break;
                case Windows.ApplicationModel.Contacts.ContactFieldCategory.mobile:
                    container.appendChild(createTextElement("div", field.value + " (mobile)"));
                    break;
                case Windows.ApplicationModel.Contacts.ContactFieldCategory.other:
                    container.appendChild(createTextElement("div", field.value + " (other)"));
                    break;
                case Windows.ApplicationModel.Contacts.ContactFieldCategory.none:
                default:
                    container.appendChild(createTextElement("div", field.value));
                    break;
            }
        }
    });
}

function createTextElement(tag, text) {
    var element = document.createElement(tag);
    element.className = "singleLineText";
    element.innerText = text;
    return element;
}

Complete example (multiple contacts)

This example uses the contact picker to retrieve multiple contacts and then displays the contact names.

JavaScript



function pickContacts() {
    // Verify that we are unsnapped or can unsnap to open the picker.
    var viewState = Windows.UI.ViewManagement.ApplicationView.value;
    if (viewState === Windows.UI.ViewManagement.ApplicationViewState.snapped &&
        !Windows.UI.ViewManagement.ApplicationView.tryUnsnap()) {
        // Fail silently if we can't unsnap.
        return;
    };

    // Create the picker.
    var picker = new Windows.ApplicationModel.Contacts.ContactPicker();
    picker.commitButtonText = "Select";

    // Open the picker for the user to select contacts.
    picker.pickMultipleContactsAsync().done(function (contacts) {
        if (contacts.length > 0) {
            // Display the selected contact names.
            var output = "Selected contacts:\n";
            contacts.forEach(function (contact) {
                output += contact.name + "\n";
            });
        }
    });
}

Summary and next steps

Now you should 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.

Quickstart: Selecting user contacts (Windows Store apps using JavaScript and HTML)

Prerequisites

Set up the contact picker

Provide a name for the commit button

Set the selection mode (optional)

Launch the picker

Complete example (single contact)

Complete example (multiple contacts)

Summary and next steps

Related topics