Creating a Web Messenger control from Scratch – Part 3

In the last part of this series we added the necessary framework to put in the place the sign-in control and get it working.

messplainsignin_thumb_14c40049 Developer

So now that you’ve got the sign-in control displayed in your User Control, what can you do with it?  Well there are a few options that allow you customize certain parts of the control and get some default information. First off we’ll take a look at the Links collection :-

messlinksproperties_thumb_222a134f Developer

As you can see the links collection supplies you with a bunch of different URL’s to various Microsoft pages relating to either the messenger control or a users’ passport account. 

Here’s a brief description of what the various links hold :-

  • AboutMessengerUrl gets the URL for the Windows Live Messenger Overview page. Here your users can learn more about the Windows Live Messenger service.
  • ChangeAccountUrl gets the URL for the Windows Live ID Sign In page where your users can choose the Windows Live ID account to sign in with.
  • PrivacyUrl gets the URL for the Microsoft Online Privacy Statement (not the privacy statement page you had to include as part of the Sign-In control).
  • ReportAbustUrl gets the URL for the Windows Live Messenger Abuse reporting form.
  • SettingsUrl gets the URL for the Settings page where your users can set their Windows Live ID preferences.
  • SignUpUrl gets the URL for the Windows Live ID Sign Up page where your users can sign up for a new Windows Live ID account.
  • TermOfUseUrl gets the URL for the Windows Live Help page that contains the Terms of Use as defined in the Microsoft Service Agreement.

 

The links collection becomes available to you after successful sign-in, and not until that point. So if we take a look at the code that we already have then you’ll see that we already have a function that gets called once sign-in has been completed.  All that we need to do is place a call to our function to get the links in there :-

function signInCompleted(sender, e)
    {
        if (e.get_resultCode() === Microsoft.Live.Messenger.SignInResultCode.success)
        {
            var selectStatus = $get('selectStatus');
            selectStatus.selectedIndex = 6;
            getMessengerLinks();
        }
    }

 

 

If you take a look at the Sign-In Control API then you’ll notice that there are three properties that we can use. All of them are getters :-

messsigninapi_thumb_24669c0b Developer

The one we’re interested in at the moment is the Links getter method. First off, lets add a section to our base Messenger framework where we will place these links.

<div id="signinlinks">
    <span><a href="" target="_blank" id="about">About</a>
    <a href="" target="_blank" id="privacy">Privacy</a>
    <a href="" target="_blank" id="reportAbuse">ReportAbuse</a>
    <a href="" target="_blank" id="termsofUse">Terms Of Use</a>
    <a href="" target="_blank" id="changeAccount">Change Account</a>
    <a href="" target="_blank" id="settings"><img src="WebMessenger/Images/Passport.gif" id="PassportImage" /></a>
    <a href="" target="_blank" id="signUp"><img src="WebMessenger/Images/SignUp.gif" /></a>
    </span>
</div>

 

and add some styling to it in our style sheet :-

 

#signinlinks
{
    width: 100%;
    position: relative;
    text-align: right;
    display: none;
}
#signinlinks span a
{
    font-family: Tahoma,arial,sans-serif;
    font-size:9px;
    text-decoration: none;
    text-indent: 2px;
    color: #000000;
}

 

 

Next we need to code our Javascript function that will get the links collection and parse it out to our various links. As mentioned this is a property getter method so although the API says the property name is “Links” the actual call that you have to place is “get_links()”. Also notice that the case of “L” has changed :-

function getMessengerLinks()
{
    var links = signincontrol.get_links();
    var about = $get("about");
    var changeAccount = $get("changeAccount");
    var privacy = $get("privacy");
    var reportAbuse = $get("reportAbuse");
    var settings = $get("settings");
    var signUp = $get("signUp");
    var termOfUse = $get("termsOfUse");
    about.href = links.get_aboutMessengerUrl();
    changeAccount.href = links.get_changeAccountUrl();
    privacy.href = links.get_privacyUrl();
    reportAbuse.href = links.get_reportAbuseUrl();
    settings.href = links.get_settingsUrl();
    signUp.href = links.get_signUpUrl();
    termOfUse.href = links.get_termsOfUseUrl();
}

 

 

So here we get the links class and assign it to a variable. Next we simply get pointers to the various links that we defined in our User Control and finally we assign the actual href attribute of each anchor tag to the values supplied in the links.

messsigninwithlinks_thumb_31ccaf11 Developer

If you click on the “About” link it will take you to this page :-

messaboutlink_thumb_6600d857 Developer

Clicking on the Privacy link takes you here :-

messprivacylink_thumb_611e249b Developer

The Report Abuse link takes you to the following page. Notice that when you click on this link, your details are forwarded and the form already has your information based on your passport account that you signed in with :-

messreportabuselink_thumb_1f1a460b Developer

The terms of use link takes you to the following page. Again this link is customized with the market that you supplied to the Sign-In control :-

messtou_thumb_6c4a3f96 Developer

The Change Account link takes you to the standard Passport sign-in page that lists all of your accounts. There is a return URL embedded into the string so that when you change accounts it will automatically redirect you back to your own application :-

messchangeaccount_thumb_356feb50 Developer

 

 

 

 

 

The settings link takes you to a page where you can adjust the settings based on each 3rd party site that you visit that uses the Windows Live authentication. It allows you to select whether you want to sign in automatically or manually each time you visit that site. Of course, sign-in automatically only works if you’re currently signed into your passport account before you visit that site :-

messsettings_thumb_1791674f Developer

And lastly we have the Sign-Up screen. Surprisingly this link actually takes you to a very old passport sign-up screen. Notice the big MSN logo at the top left (perhaps this should be updated?) :-

messsignup_thumb_4bc59095 Developer

With regards to the links, the following is taken from the WL Messenger Library TOC :-

Display links to various Messenger Library options prominently within the user interface when a user is signed in via the library. This requirement can be met either by rendering the Sign-in Control, or rendering the links with Windows Live Messenger Library icon directly within the application user interface (see the Windows Live SDK License Agreement for information about licensing the icon). If the Windows Live Messenger Library icon is used, it must link to http://messenger.live.com. The following links are required.

  • Sign out
  • Change settings
  • Privacy statement
  • Terms of use
  • Send feedback

Basically what this is saying is that if you are displaying the Sign-In Control on your form then you don’t need to display any of the links (I would however at least display the Sign-Up link information). However if you hide the Sign-In Control (see later in this article) then you MUST display the links stated above.

Now before this part of the series gets too long we will quickly take a look at some new functionality that was introduced as part of the new 2.5 release API. If we take a quick look at the methods that are available for the actual Sign-In Control itself, you will notice that they now include Show and Hide :-

messsigninapimethods_thumb_520c6723 Developer

Lets take advantage of them. These are standard methods that you call directly against your instance of the Sign-In Control class. First off we’ll put a toggle on the page that users can click to show and hide the Sign-In control. You may ask, why not just hide the control after the user signs in?  The Sign-In control also acts as the log off control. So if you hide it after the user signs in then they will have no way of signing out again. This functionality should really be surfaced as part of the API so that you could hide the Sign-in control (which is rather large) and supply your own button or link that would show the Sign-In Control again and automatically logs them out rather than the user having to click on your logout button or link then click again on the logout button in the actual Sign-In control. Anyway, here is the complete source for our Sign-In section in our User Control’s ascx page :-

<div id="showhideSignIn">
            <span><b>Sign In/Out
            <a href="Javascript:ToggleSignIn();">
            <img alt="ToggleContacts" src="WebMessenger/Images/minus_icon.gif" id="SignInExpand" class="SignInImage" />
            </a>
        </b></span>
<div id="signinframe">
</div>
<div id="signinlinks">
    <span><a href="" target="_blank" id="about">About</a>
    <a href="" target="_blank" id="privacy">Privacy</a>
    <a href="" target="_blank" id="reportAbuse">ReportAbuse</a>
    <a href="" target="_blank" id="termsofUse">Terms Of Use</a>
    <a href="" target="_blank" id="changeAccount">Change Account</a>
    <a href="" target="_blank" id="settings"><img src="WebMessenger/Images/Passport.gif" id="PassportImage" /></a>
    <a href="" target="_blank" id="signUp"><img src="WebMessenger/Images/SignUp.gif" /></a>
    </span>
</div>
</div>

 

 

The only new thing here is the initial Sign In/Out span that also contains a image and a Javascript call. The Javascript call is fairly straightforward :-

function ToggleSignIn()
{
    var SignInImg = $get("SignInExpand");
    if (signincontroldisplayed == true)
    {
        SignInImg.src = "WebMessenger/Images/plus_icon.gif";
        signincontrol.hide();
        signincontroldisplayed = false;
        var signinlinks = $get("signinlinks");
        signinlinks.style.display = "block";
    }
    else
    {
        SignInImg.src = "WebMessenger/Images/minus_icon.gif";
        signincontrol.show();
        signincontroldisplayed = true;
        var signinlinks = $get("signinlinks");
        signinlinks.style.display = "none";
 
    }
}

 

We first get a reference to the image that we displayed (a simple + and – gif image) then we check to see whether this div is currently showing or not. If it’s showing then we change the image, call the hide() method on our Sign-In Control class instance and show our links section. We do the opposite if the Sign-In Control is current hidden.  We are showing the links section when we hide the Sign-In control to be in compliance with the TOC as stated previously. Finally I’ve added a call to this ToggleSignIn function to our authentication completed function that gets called once the user has initially authenticated. This way the Sign-In Control will automatically hide when the user signs in :-

 

function authenticationCompleted(sender, e)
{
    ToggleSignIn();
   msgruser = new Microsoft.Live.Messenger.User(e.get_identity());
   msgruser.add_signInCompleted(Delegate.create(null, signInCompleted));
   msgruser.signIn(null);
    }

 

So here’s our control before we sign in. Notice that the links section is not displayed as none of these links will work until after the user has signed in :-

messoriginal_thumb_0d5fcce2 Developer

After we sign in, we hide the Sign-In control :-

messsignedin_thumb_4b90158b Developer

Finally if we click our Sign In/Out link we should get back to the first image but showing Sign Out rather than Sign-In and we can at this point display our Links section. Unfortunately there appears to be a bug with the Show() method and this is what we actually end up with :-

messsignedinexpanded_thumb_1fdf4b8f Developer

As you can see, the Show() method did not actually work. In the next installment of this series I promise we will get around to customizing the Sign-In Control itself.