Quickstart: Showing contact data in a contact card (HTML)

Here, we'll show you how to create a contact, apply data to it, and then display that data in a contact card.

Prerequisites

• We recommend that you be familiar with Microsoft Visual Studio and its associated templates.
• We recommend that you be familiar with JavaScript development.

Create a contact and apply data to it

Create an instance of a Windows.ApplicationModel.Contacts.Contact and assign it to a variable. Then, apply to the Contact the email address, the phone number, or both that were supplied through the UI by a user.

        var emailAddress = document.getElementById("inputEmailAddress").value;
        var phoneNumber = document.getElementById("inputPhoneNumber").value;

        if ((emailAddress.length === 0) && (phoneNumber.length === 0)) {
            WinJS.log && WinJS.log("You must enter an email address and/or phone number of the contact for the system to search and show the contact card.", "sample", "error");
        }
        else {
            // Create input contact object for calling ContactManager.showContactCard().
            var contact = new ContactsNS.Contact();
            if (emailAddress.length > 0) {
                if (emailAddress.length <= MAX_EMAIL_ADDRESS_LENGTH) {
                    var email = new ContactsNS.ContactEmail();
                    email.address = emailAddress;
                    contact.emails.append(email);
                }
                else {
                    WinJS.log && WinJS.log("The email address you entered is too long.", "sample", "error");
                    return;
                }
            }

            if (phoneNumber.length > 0) {
                if (phoneNumber.length <= MAX_PHONE_NUMBER_LENGTH) {
                    var phone = new ContactsNS.ContactPhone();
                    phone.number = phoneNumber;
                    contact.phones.append(phone);
                }
                else {
                    WinJS.log && WinJS.log("The phone number you entered is too long.", "sample", "error");
                    return;
                }
            }

Show the contact data in a contact card

Call the ContactManager.ShowContactCard(Contact, Rect, Placement) method to show the previously supplied contact data in a contact card.

            // Get the selection rect of the button pressed to show contact card.
            var boundingRect = evt.srcElement.getBoundingClientRect();
            var selectionRect = { x: boundingRect.left, y: boundingRect.top, width: boundingRect.width, height: boundingRect.height };

            ContactsNS.ContactManager.showContactCard(contact, selectionRect, Windows.UI.Popups.Placement.default);
            WinJS.log && WinJS.log("ContactManager.showContactCard() was called.", "sample", "status");
        }

Use the contact card

You can use the contact card to perform operations, such as adding the contact to the People app, getting details about the contact if it's already in the People app, or calling a phone number that is associated with the contact.

Complete example

This example uses Contact and ContactManager to create a contact and to show the contact's data in a contact card.

(function () {
    "use strict";
    var ContactsNS = Windows.ApplicationModel.Contacts;

    var page = WinJS.UI.Pages.define("/html/ScenarioShowContactCard.html", {
        ready: function (element, options) {
            // Use element.querySelector() instead of document.getElementById() to ensure that the correct default.html page is targeted.
            element.querySelector("#buttonShowContactCard").addEventListener("click", ShowContactCard, false);
        }
    });

    // Length limits allowed by the API
    var MAX_EMAIL_ADDRESS_LENGTH = 321;
    var MAX_PHONE_NUMBER_LENGTH = 50;

    function ShowContactCard(evt) {
        var emailAddress = document.getElementById("inputEmailAddress").value;
        var phoneNumber = document.getElementById("inputPhoneNumber").value;

        if ((emailAddress.length === 0) && (phoneNumber.length === 0)) {
            WinJS.log && WinJS.log("You must enter an email address and/or phone number of the contact for the system to search and show the contact card.", "sample", "error");
        }
        else {
            // Create input contact object for calling ContactManager.showContactCard().
            var contact = new ContactsNS.Contact();
            if (emailAddress.length > 0) {
                if (emailAddress.length <= MAX_EMAIL_ADDRESS_LENGTH) {
                    var email = new ContactsNS.ContactEmail();
                    email.address = emailAddress;
                    contact.emails.append(email);
                }
                else {
                    WinJS.log && WinJS.log("The email address you entered is too long.", "sample", "error");
                    return;
                }
            }

            if (phoneNumber.length > 0) {
                if (phoneNumber.length <= MAX_PHONE_NUMBER_LENGTH) {
                    var phone = new ContactsNS.ContactPhone();
                    phone.number = phoneNumber;
                    contact.phones.append(phone);
                }
                else {
                    WinJS.log && WinJS.log("The phone number you entered is too long.", "sample", "error");
                    return;
                }
            }

            // Get the selection rect of the button pressed to show contact card.
            var boundingRect = evt.srcElement.getBoundingClientRect();
            var selectionRect = { x: boundingRect.left, y: boundingRect.top, width: boundingRect.width, height: boundingRect.height };

            ContactsNS.ContactManager.showContactCard(contact, selectionRect, Windows.UI.Popups.Placement.default);
            WinJS.log && WinJS.log("ContactManager.showContactCard() was called.", "sample", "status");
        }
    }
})();

Summary and next steps

We created a contact, applied data to it, and then displayed that data in a contact card.

Now you have a basic understanding of how to show contact data in a contact card. Download the Contact manager API sample from the code gallery to see the complete sample of how to use contacts and the contact manager.

Next, we'll create a contact, apply initial data to it, show the initial data in a contact card, and then update that contact card in a delayed fashion with more contact data.

Showing initial contact data and then later applying more contact data

Related topics

Contact manager API sample