Quickstart: Showing initial contact data and then later applying more contact data (HTML)

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

Note  The contact card will time out in four seconds. So, if an update doesn't occur in four seconds, the contact card UI becomes final, and no more updates can be applied. In our example, we force a two second delay to simulate downloading more data from the network for the contact.

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 initial data to it

Create an instance of a Windows.ApplicationModel.Contacts.Contact and assign it to a variable. Then, apply to the Contact some initial data.

        // Create contact object with small set of initial data to display.
        var contact = new ContactsNS.Contact();
        contact.firstName = "Gail";
        contact.lastName = "Wilson";

        var email = new ContactsNS.ContactEmail();
        email.address = "gail@contoso.com";
        contact.emails.append(email);

Show initial contact data in a contact card

Call the ContactManager.ShowDelayLoadedContactCard method to show the initial contact data in a contact card. ShowDelayLoadedContactCard returns a ContactCardDelayedDataLoader object that is used to update the contact card in a delayed fashion.

        // 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 };

        var delayedDataLoader = ContactsNS.ContactManager.showDelayLoadedContactCard(
            contact,
            selectionRect,
            Windows.UI.Popups.Placement.below // The contact card placement can change when it is updated with more data. For improved user experience, specify placement 
                                              // of the card so that it has space to grow and will not need to be repositioned. In this case, default placement first places 
                                              // the card above the button because the card is small, but after the card is updated with more data, the operating system moves 
                                              // the card below the button to fit the card's expanded size. Specifying that the contact card is placed below at the beginning 
                                              // avoids this repositioning.
            );
        var message = "ContactManager.showDelayLoadedContactCard() was called.\r\n";
        WinJS.log && WinJS.log(message, "sample", "status");

Update the contact card in a delayed fashion with more contact data

Populate the contact with more data and then call ContactCardDelayedDataLoader.SetData to update the contact card with this data.

        // Simulate downloading more data from the network for the contact.
        message += "Downloading data ...\r\n";
        WinJS.log && WinJS.log(message, "sample", "status");
        downLoadContactDataAsync(contact).then(
            function complete(result) {
                if (result.hasMoreData) {
                    // We get more data - update the contact card with the full set of contact data.
                    delayedDataLoader.setData(result.fullContact);
                    message += "ContactCardDelayedDataLoader.setData() was called.\r\n";
                    WinJS.log && WinJS.log(message, "sample", "status");
                }
                else {
                    // No more data to show - just close the data loader to tell the contact card UI all data has been set.
                    delayedDataLoader.close();
                }
            },
            function error(e) {
                WinJS.log && WinJS.log(e.message, "sample", "error");
            });


    function downLoadContactDataAsync(contact) {
        return new WinJS.Promise(function (comp) {
            // Simulate the download latency by delaying the execution by 2 seconds.
            setTimeout(function () {
                // Add more data to the contact object.
                var workEmail = new ContactsNS.ContactEmail();
                workEmail.address = "gail@adatum.com";
                workEmail.kind = ContactsNS.ContactEmailKind.work;
                contact.emails.append(workEmail);                   

                var homePhone = new ContactsNS.ContactPhone();
                homePhone.number = "(555) 555-0100";
                homePhone.kind = ContactsNS.ContactPhoneKind.home;
                contact.phones.append(homePhone);

                var workPhone = new ContactsNS.ContactPhone();
                workPhone.number = "(555) 555-0111";
                workPhone.kind = ContactsNS.ContactPhoneKind.work;
                contact.phones.append(workPhone);

                var mobilePhone = new ContactsNS.ContactPhone();
                mobilePhone.number = "(555) 555-0112";
                mobilePhone.kind = ContactsNS.ContactPhoneKind.mobile;
                contact.phones.append(mobilePhone);

                var address = new ContactsNS.ContactAddress();
                address.streetAddress = "One Microsoft Way";
                address.locality = "Redmond";
                address.region = "WA";
                address.country = "USA";
                address.postalCode = "23456";
                address.kind = ContactsNS.ContactAddressKind.home;
                contact.addresses.append(address);

                comp({ fullContact: contact, hasMoreData: true });
            },
            2000);
        });
    }

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/ScenarioShowContactCardDelayLoad.html", {
        ready: function (element, options) {
            // Use element.querySelector() instead of document.getElementById() to ensure that the correct default.html page is targeted.
            element.querySelector("#buttonShowContactCardDelayLoad").addEventListener("click", ShowContactCardDelayLoad, false);
        }
    });

    function downLoadContactDataAsync(contact) {
        return new WinJS.Promise(function (comp) {
            // Simulate the download latency by delaying the execution by 2 seconds.
            setTimeout(function () {
                // Add more data to the contact object.
                var workEmail = new ContactsNS.ContactEmail();
                workEmail.address = "gail@adatum.com";
                workEmail.kind = ContactsNS.ContactEmailKind.work;
                contact.emails.append(workEmail);                   

                var homePhone = new ContactsNS.ContactPhone();
                homePhone.number = "(555) 555-0100";
                homePhone.kind = ContactsNS.ContactPhoneKind.home;
                contact.phones.append(homePhone);

                var workPhone = new ContactsNS.ContactPhone();
                workPhone.number = "(555) 555-0111";
                workPhone.kind = ContactsNS.ContactPhoneKind.work;
                contact.phones.append(workPhone);

                var mobilePhone = new ContactsNS.ContactPhone();
                mobilePhone.number = "(555) 555-0112";
                mobilePhone.kind = ContactsNS.ContactPhoneKind.mobile;
                contact.phones.append(mobilePhone);

                var address = new ContactsNS.ContactAddress();
                address.streetAddress = "One Microsoft Way";
                address.locality = "Redmond";
                address.region = "WA";
                address.country = "USA";
                address.postalCode = "23456";
                address.kind = ContactsNS.ContactAddressKind.home;
                contact.addresses.append(address);

                comp({ fullContact: contact, hasMoreData: true });
            },
            2000);
        });
    }

    function ShowContactCardDelayLoad(evt) {
        // Create contact object with small set of initial data to display.
        var contact = new ContactsNS.Contact();
        contact.firstName = "Gail";
        contact.lastName = "Wilson";

        var email = new ContactsNS.ContactEmail();
        email.address = "gail@contoso.com";
        contact.emails.append(email);

        // 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 };

        var delayedDataLoader = ContactsNS.ContactManager.showDelayLoadedContactCard(
            contact,
            selectionRect,
            Windows.UI.Popups.Placement.below // The contact card placement can change when it is updated with more data. For improved user experience, specify placement 
                                              // of the card so that it has space to grow and will not need to be repositioned. In this case, default placement first places 
                                              // the card above the button because the card is small, but after the card is updated with more data, the operating system moves 
                                              // the card below the button to fit the card's expanded size. Specifying that the contact card is placed below at the beginning 
                                              // avoids this repositioning.
            );
        var message = "ContactManager.showDelayLoadedContactCard() was called.\r\n";
        WinJS.log && WinJS.log(message, "sample", "status");

        // Simulate downloading more data from the network for the contact.
        message += "Downloading data ...\r\n";
        WinJS.log && WinJS.log(message, "sample", "status");
        downLoadContactDataAsync(contact).then(
            function complete(result) {
                if (result.hasMoreData) {
                    // We get more data - update the contact card with the full set of contact data.
                    delayedDataLoader.setData(result.fullContact);
                    message += "ContactCardDelayedDataLoader.setData() was called.\r\n";
                    WinJS.log && WinJS.log(message, "sample", "status");
                }
                else {
                    // No more data to show - just close the data loader to tell the contact card UI all data has been set.
                    delayedDataLoader.close();
                }
            },
            function error(e) {
                WinJS.log && WinJS.log(e.message, "sample", "error");
            });
    }
})();

Summary

We created a contact, applied initial data to it, displayed that initial data in a contact card, and then updated that contact card in a delayed fashion with more contact data.

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

Related topics

Contact manager API sample