Windows Live UI Controls

Following on from my previous tutorial on how to integrate the Windows Live Web Bar into your site, we’ll build upon this and show you some of the other UI controls that you can use in your site.

One thing that a lot of people might want to do is display the signed-on users’ display picture somewhere on the site other than in the web-bar.

MessytwitDisplayPic

As with most everything Microsoft does in the web space there are a couple of ways of doing this. Lets start by doing it the easy way. Take the default.aspx page from the last tutorial and add a new <div> element under the <form> tag :-

<form id="form1" runat="server">
<div id="msgrDisplayPic"></div>

 

 

Into the div tag we will add the display picture UI control. This control has a few different options you can specify but only one is actually required, the cid of the user who’s image you wish to display. How do you get the cid of the signed-in user? Again there are a couple of ways of doing this but we’ll take the easy route again. For use with their tags on the aspx page, Microsoft has thoughtfully provided a variable that automatically gets populated with the users’ cid, $user. So the base tag that we need to enter into our div looks like this :-

<msgr:display-picture cid='$user'></msgr:display-picture>

 

 

When you run the page you’ll notice the default “blank” user image as nobody has signed in yet :-

MessytwitDisplayPic1

When a user signs in then this image will change to the users’ display picture as seen above.

There are a couple of options that you can add to the control. You can adjust it’s size by supplying it with a size attribute. Size can take three pre-defined values, Small, Medium and Large. By default the control is set to Medium size. You can also tell it whether to enable or disable presence information (the “glow” around the border of the image). By default this is set to true so presence information is displayed. Finally you can also state whether a logo is displayed in the bottom right of the image or not by setting the logo-enabled attribute. The default is set to false. When set to true, a small logo is displayed :-

messytwitDisplayPic3

So here is our final display-picture tag :-

<msgr:display-picture cid='$user' presence-enabled='true' size='Large' logo-enabled='true'></msgr:display-picture>

 

 

 

Microsoft also allow you to override their default style sheets for this control giving you a range of options :-

  • DisplayPictureControl: The outermost container of the display-picture tag.
  • DisplayPictureControl Border: Specified when presence is enabled.
  • DisplayPictureControl Large: Specified when the size is “large”.
  • DisplayPictureControl Medium: Specified when the size is “medium”.
  • DisplayPictureControl Small: Specified when the size is “small”.
  • DisplayPictureControl_Icon: The logo if the logo is enabled.
  • DisplayPictureControl_Image: The display picture.
  • DisplayPictureControl_Image Online: Specified when the status is Online.
  • DisplayPictureControl_Image BeRightBack: Specified when the status is Be Right Back.
  • DisplayPictureControl_Image Busy: Specified when the status is Busy.
  • DisplayPictureControl_Image Away: Specified when the status is Away.
  • DisplayPictureControl_Image InACall: Specified when the status is In A Call.
  • DisplayPictureControl_Image OutToLunch: Specified when the status is Out To Lunch.
  • DisplayPictureControl_Image AppearOffline: Specified when the status is Appear Offline.
  • DisplayPictureControl_Image Offline: Specified when the status is Offline.

And that’s it, you can now add the users’ display picture to anywhere on your site with one tag.

If you want more fine grained control over the process or you wish to do all this programmatically Microsoft also allows you to do this.

First remove the <msgr:display-picture> tag from the default.aspx, but keep the <div> tag in place. Next create a Javascript file and add a reference to it at the top of the default.aspx :-

<script type="text/javascript" src="JScript/Messenger.js"></script>

 

In this Javascript file we will programmatically insert the users’ display picture control onto the site. I’ve added a couple of extra event handlers to this file that you don’t necessarily need but are very handy to have as well. First off we want to declare a couple of global variables, one to hold the users’ token that gets generated when they give their consent to sign-in to your site, and the second is to hold the actual user object :-

var userToken = null;
var msgrUser = null;

 

 

Our first event handler gets fired once the user gives his permission to sign into your site :-

function onUserConsentCompleted(e)
{
    userToken = e.get_consentToken();
}

 

 

All that we’re doing here is getting the consent token that gets generated and storing it in our global variable for use later.

The next event handler gets fired once the user has authenticated (i.e. the windows live credentials are correct) :-

function onAuthenticated(e)
{
    msgrUser = e.get_user();
    msgrUser.add_signInCompleted(SignInCompleted);
}

 

 

Here we capture the actual user object (the most important object you use when dealing programmatically with Windows Live Web Messenger) and store it in our global variable. Then we add an event handler for when the sign-in process has completed.

function SignInCompleted(sender, e)
{
    if (e.get_resultCode() === Microsoft.Live.Messenger.SignInResultCode.success)
    {
        if (typeof (InvokeOnUserSignIn) === 'function')
        {
            InvokeOnUserSignIn();
        }
    }
    else
    {
        OnUserSignedOut();
    }
    var usercid = msgrUser.get_identity().get_cid();
    var signinframe = document.getElementById("msgrDisplayPic");
    var tag = Microsoft.Live.Messenger.UI.Tags.TagsFactory.createTag('display-picture', 
    { 'cid': usercid, 'presence-enabled': 'true', 'size': 'Large', 'logo-enabled': 'true' });
    signinframe.appendChild(tag);
}

 

 

The SignInCompleted handler first of all checks to see if authorization was correct (did the user really sign in or did they perhaps have a typo and sign-in wasn’t completed successfully). If sign-in was not correct then we make sure our page reflects that by calling our sign-out routine which should house any clean-up code.

If the user has successfully signed in then we grab their cid. Remember, this is the one required field for the display-picture control (and most other controls as well). Next we get a reference to our <div> element where we want to place the display-picture control. All Windows Live Messenger UI Controls are instantiated through the TagFactory object. Here we simply call the method createTag and pass into it two values. The first is the type of control that we wish to create, in this case the display-picture control. The second value is a set of key:value pairs containing any attributes that we wish to supply. In the example code above we are simply re-creating the <msgr:display-picture> tag we created earlier on the page itself. The only difference here is that we are passing in the cid manually. Finally we simply add this control into the <div> tag we got a reference for earlier.

The final entry in our Javascript file is the event handler for when the user signs out :-

function OnUserSignedOut()
{
    //add code for sign-out.
}

 

And that’s it, you will end up with exactly the same screen as we did earlier, only this time you have gained knowledge in how to do it programmatically.

The basics on what we have covered here applies to all the other Web Messnger UI controls. For example, if we wanted to add the contact-list control to our page we simply add the appropriate tag within our page or do it programmatically :-

<msgr:contact-list word-wheel-enabled="false"></msgr:contact-list>

 

 

And this results in the following :-

MessytwitContacts

There are a lot of UI controls to explore. You can find more information about what’s available, their methods and parameters etc. over on msdn :- http://msdn.microsoft.com/en-us/library/microsoft.live.messenger.ui.tags.aspx