Our next iteration on the contacts control (nee gadget) is now live and ready for you to experiment with!
The snapshot of the contacts control in the online documentation is a static image. The one below is not! This a live (as in real) contacts control sitting in an iframe on this blog page. Go head, click on it. Login and check out your Live contacts.
The iframe on this page was necessary to get around the html rewriting done by the blogs.msdn.com host server. (grr...) It's also remarkably difficult to upload a file to blogs.msdn.com, which is a critical requirement for getting the cross-domain communication channel to work. Then again, blogs.msn.com wasn't intended to host files, just blog articles.
So, I put the contacts control client demo on my own server and just placed an iframe here to point over there.
It displays the contact info received from the control when the user selects and ok's the transfer. Sign into the control with your LiveID identity, select a few of your contacts, and press Send. The control will display the data and ask for confirmation. If you approve the transfer, the data is sent to the host page via the cross-domain channel.
We've streamlined the control setup, switching from a programmatic constructor call model to a declarative HTML element model. The only JavaScript you write is the function to do something with the returned data. To put the control on your page, you add two script references to your page (live.js and control.js, on versioned URLs), declare an XML namespace (xmlns:devlive=http://dev.live.com), and insert an HTML element tag named "contactscontrol". The long list of parameters required by the previous constructor call are now attributes of the contactscontrol element. Like this:
<devlive:contactscontroldevlive:privacyStatementURL="http://yourdomain.com/privacyStatement.html"devlive:channelEndpointURL="http://yourdomain.com/channel.htm"devlive:dataDesired="name, email"devlive:onData="myDataProc"devlive:onSignin="mySigninProc"devlive:onSignout="mySignoutProc"devlive:onError="myErrorProc" />
You'll probably also want to set the width and height of the box as well, by adding a style="width:250;height:400;float:right" attribute in there. The devlive namespace is optional, but a good idea to avoid colliding with somebody else's contactscontrol tag or channelEndpointURL attribute.
Put that on your page, along with the two required includes and the callback functions you've indicated, and when the page loads, the contacts control code will discover the contactscontrol HTML tag, grab the info it needs from the attributes, and do all the behind the scenes stuff necessary to display its UI and talk to the Windows Live Contacts database server. Full step by step details are on the Getting Started page.
There are two critical pieces you need to get right: placing the channel.htm on your site, and writing your onData callback function. Without those, everything can look fine but you'll get no data.
Channel.htm is easy: just copy the file from http://dev.live.com/scripts/channel/v0.1/channel.htm to some place on your web site. Don't bother clicking on that link in your browser - channel.htm autonavigates to about:blank, so by the time you can click View: Source the source you want is already gone. This isn't an obfuscation measure, it's an integral part of the channel mechanism - immediately navigating to a different URL allows the channel to detect consecutive navigations to the same URL. Otherwise, the browser would ignore the second request because the page is already on the requested URL.
To copy the channel.htm file to your machine, right click on the URL and select Save Target As, or open the URL in Notepad or Visual Studio, then Save As to a local file. It doesn't matter what the file name or path is, it just needs to be in the same domain as the page you want to use the contacts control on.
Do not use MS Word or Write to open channel.htm - word processors are prone to reformatting HTML in ways that make sense for interoffice memos but wreak havoc on HTML and JavaScript syntax. Word is particularly bad helpful about replacing simple double quotes with fancy back slanted and forward slanted quote chars. Very pretty on paper, but nasty, hard to spot syntax errors in JavaScript and HTML. "What do you mean 'Unterminated string'? The friggin quote is right there!!"
Writing the code to receive the contacts is pretty easy, too. The code on the demo page looks like this:
function receiveData(p_contacts) { var s = "Done! " + p_contacts.length + " records received."; 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>"; } document.getElementById("ContactsDisplay").innerHTML = s; }
The p_contacts param is an array of JavaScript objects, one object per contact. The data for each contact is stored in properties / attributes on the object. p_contacts[0].name returns the name field of the first contact in the array.
Keep in mind that some of the contact records you receive may not have data for all the fields you asked for. Currently, that means the field values you receive will be undefined, and will display "undefined" when you convert them to strings. We'll fix that to return empty strings in a future release.
That's tomorrow's post.