Windows Live Contacts Control (Beta) - Getting Started

Getting Started


Incorporating the Control into Your Web Page
Writing Data to a User's Windows Live Contacts

Incorporating the Control into Your Web Page

Incorporating the Windows Live Contacts control into your web page is quite simple.

  1. First, you need to include the JavaScript source files for the control into your HTML page. Place the following statements between the <head> and </head> tags at the top of your HTML page: 
    <script type="text/javascript" 
        src="http://controls.services.live.com/scripts/base/v0.3/live.js"> 
    </script>
    <script type="text/javascript" 
        src="http://controls.services.live.com/scripts/base/v0.3/controls.js"> 
    </script>
  2. Next, you need to display the contacts control. For this, you must first declare an xml namespace for http://dev.live.com. You can do this by modifying the html tag as follows: 
    <html xmlns:devlive="http://dev.live.com">
  3. Now you insert a contactscontrol element in your HTML page. This element hosts the contact control, and allows manipulation of positioning (Note: limit the width to 500 or fewer pixels). You are required to supply the following information as attributes on the contactscontrol element.

Attribute

Description

privacyStatementURL

A URL to your Web site’s privacy statement.

channelEndpointURL

The Windows Live Contacts control uses a communication channel technique to send data between pages from different domains within the browser. To enable your Web site to receive data from the control, you need to create a channel file with the following content on your Web server.

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Channel</title>
<meta name="ROBOTS" content="NONE"/>
 
<script type="text/javascript">
function doc_loaded()
{
    try
    {
        var hash = window.location.hash.substr(1);
        if (window.location.replace == null)
            window.location.replace = window.location.assign;
        window.location.replace("about:blank");
        var name = hash.split("/")[0];
        var win = null;
        if (name)
            win = window.parent.frames[name];
        else
            win = window.parent.parent;
        win.Microsoft.Live.Channels.Mux._recv_chunk(hash);
    }
    catch (ex)
    {
        /* ignore */
    }
}
</script>
</head>
<body onload="doc_loaded()">
</body>
</html>

Let’s say your Web site is www.mydomain.com; you could create channel.htm to the root directory of your Web server so that the file would appear as http://www.mydomain.com/channel.htm to the outside world.

dataDesired

A comma delimited list of fields you’d like returned.

market

The market or language requested. Supported today:

Chinese (simplified): zh-cn
Dutch: nl
English: en
French: fr
German: de
Italian: it
Japanese: ja
Korean: ko
Portuguese (Brazil): pt-br
Spanish: sp
Swedish: sv

If no market is specified, the English control is displayed.

innerBackgroundColor

Sets the background color scheme of the internal area.
Color values:

Hex: #ffffff style
Rgb: rgb(255,255,255) style
W3C standard colors: aqua| black| blue| fuchsia| gray| green| lime| maroon| navy| olive| purple| red| silver| teal| white| yellow

If no color is specified, the default colors apply.

innerTextColor

Sets the color scheme of the internal text. See above for supported color values.

outerBackgroundColor

Sets the color scheme of the outer background. See above for supported color values.

outerTextColor

Sets the color scheme of the outer text. See above for supported color values.

linkColor

Sets the color scheme of the URL hyperlinks. See above for supported color values.

onSignin

An event handler that gets called on sign in.

onSignout

An event handler that gets called on sign out.

onError

An event handler that gets called when an error is detected.

onData

An event handler that gets called when data is received.

onLoad

An event handler that gets called when all of the contact controls on the page have been loaded.


Here’s an example of a contactscontrol tag for a French language control: 

<devlive:contactscontrol 
 style="width:250px;height:500px;float:right;border:solid 1px black;"
 devlive:privacyStatementURL= "http://mydomain.org/privacyPolicy.html"
 devlive:channelEndpointURL="channel.htm"
 devlive:dataDesired="name,email"
 devlive:market="fr"
 devlive:onSignin="onSignin"
 devlive:onSignout="onSignout"
 devlive:onError="onError"
 devlive:onData="onData"
 devlive:onLoad="onLoad">
</devlive:contactscontrol>

Some users may have JavaScript disabled in their browser, or may be using a browser that does not support JavaScript (such as the mini-browsers on cellular phones). To handle this case, you should provide a friendly message by nesting a <noscript> tag in your contacts control tag: 

<noscript>This control requires a web browser that supports JavaScript</noscript>

Next, you need to write a little bit of JavaScript for the event handlers: 

<script type="text/javascript">
function onSignin() {
  // user is signed in
}

function onSignout() {
  // user is not signed in 
}

function onError() {
  // there was a data transfer error
}

function onData(p_contacts) {
  // here comes the data!
  var s = "Done! " + p_contacts.length + " records received. <br>";
  for (var i = 0; i < p_contacts.length; i++) {
   s += "<p>";
   s += "Name: " + p_contacts[i].name +"<br>";
   s += "Email: " + p_contacts[i].email;
   s += "</p>";
  }
  alert(s);
}
function onLoad() {
   // contact controls loaded
}

</script>

Your customers can now send their Windows Live and MSN contact lists to your Web site. That's more than 400 million contact records available to you through your users.

Writing Data to a User's Windows Live Contacts

This functionality is only available in List View.

  1. You first need to create a button to add contacts.
    <input value="Add Custom Contact" type="button" onclick="addCustomContact();" />
  2. The addCustomContact function prompts you to enter details of a contact, which then is added to the  user’s contact list. The callback function on the commitContacts method displays any errors. 
    function addCustomContact(){
                var contacts = [
                    {
                     firstname:prompt("Name",""),       
                     lastname:prompt("Lastname",""),           
              emailpersonal:prompt("Personal Email",""),
              phonebusiness:prompt("Business Phone","")
                    }
                ];   
                ContactsControl.createContacts(contacts);
                ContactsControl.commitContacts(processErrorDescription);
        }

        function processErrorDescription(p_description){
            var s = "";
            for (var i = 0; i < p_description.length; i++) {
                s += "";
                for (var j in p_description[i]) {
                    s += j + ": " + p_description[i][j] + "";
                }
                s += "";
            }         
            document.getElementById("ContactsDisplay").innerHTML = s;
        }

That's it! Your customers can now save your contact information to their contacts list.