Signing Users In (UI Control)

Ff752139.note(en-us,MSDN.10).gifNote:
Current information about Live Connect is now available in the Windows Live Developer Center. The information in the following sections is provided for legacy purposes only.

To add sign-in capability to your application declaratively, you include the Sign In user interface (UI) control in your webpage by means of the <wl:signin> tag. In its simplest form, the <wl:signin /> markup provides the necessary sign-in capability. You can optionally add attributes to customize the look and feel of the button that appears on the page, as shown in the following example.

<wl:signin id="signInControl" 
           signedintext="You are signed in!" 
           signedouttext="Goodbye." 
           onsignin="{{signInCallback}}"
           theme="white"
           buttonsize="large"/>

All attributes must be lowercase. The id attribute is optional but is helpful for referring to the control programmatically. For more information about all attributes, see Sign In Control.

Sometimes you may want to construct the Sign In control programmatically—for example, when the Document Object Model (DOM) elements on the page are not known until after the DOM is ready, or when the appearance of the Sign In control is determined dynamically based on some other application feature.

You can use the SignIn class to construct the Sign In Control programmatically. To create a new SignIn control follow these steps:

  1. Create a new instance of the SignIn class, specifying the DOM element that the sign-in UI will appear in.
  2. Specify the properties of the Sign In control.
  3. Call the initialize method to associate the Sign In control with the DOM element.

The following code demonstrates the syntax for adding a Sign In control.

var signInControl;
Microsoft.Live.Core.Loader.load(['microsoft.live.ui'], function () {
    signInControl = new Microsoft.Live.UI.SignIn(domElement);
    signInControl.set_signedInText('Welcome!');
    signInControl.set_signedOutText('Connect.');
    signInControl.add_signin(signInCallback);
    signInControl.add_signout(signOutCallback);
    signInControl.initialize();
});
function signInCallback(eventArgs) {
    // check eventArgs.get_resultCode()
}
function signOutCallback() {
    // alert('Signed out.');
}

For an API usage overview, see Using the JavaScript Library and Controls for Messenger Connect.

The following two samples demonstrate how to sign in to Messenger Connect declaratively, using markup. The first sample uses the Sign In Control in a page. The second sample creates the Sign In control programmatically.

To test this page, set up the Getting Started Sample for ASP.NET. Then, add a page to that project as follows:

  1. Create a new ASP.NET page in the project.
  2. Replace the <html> element with the sample code.
  3. Update the sample code by providing your client ID in the <wl:app> tag.

Sample 1

This sample uses <wl:signin> UI control to add sign-in functionality to the page, and the <wl:app> tag to provide application configuration information.

<html xmlns="http://www.w3.org/1999/xhtml" xmlns:wl="http://apis.live.net/js/2010">
<head>
    <title> SignIn Example</title>
    <script type="text/javascript" src="http://js.live.net/4.1/loader.js"></script>
    <script type="text/javascript">
        function appLoaded(appLoadedEventArgs) {
        }
        function signInCallback(signInCompletedEventArgs) {
            if (signInCompletedEventArgs.get_resultCode() === Microsoft.Live.AsyncResultCode.success) {
                alert('Sign-in successful.');
            }
            else {
                alert('Sign-in failed.');
            }        }
    </script>
</head>
<body>
    <wl:app 
    channel-url="/channel.htm" 
    callback-url="/OAuthWrapCallback.ashx?wl_session_id=<%= Session.SessionID %>"
    client-id="<Your-Client-Id>" 
    scope="WL_Profiles.View" 
    onload="{{appLoaded}}">
    </wl:app>
    <wl:signin id="signInControl" 
               signedintext="Signed in. Click to sign out." 
               signedouttext="Click to sign in." 
               onsignin="{{signInCallback}}"  />
</body>
</html>

Sample 2

This sample shows a webpage that defines a button whose handler creates a Sign In Control and adds it to a <div> element on the page. Like the first sample, this one uses the <wl:app> tag to provide application configuration information.

<html xmlns="http://www.w3.org/1999/xhtml" xmlns:wl="http://apis.live.net/js/2010">
<head>
    <title> SignIn Example</title>
    <script type="text/javascript" src="http://js.live.net/4.1/loader.js"></script>
    <script type="text/javascript">
        var signInControl, domElement, toggleButton, isDefined, state;
        function appLoaded(appLoadedEventArgs) {
        }
        function addSignInControl() {
            domElement =  $get('SignInControlDiv');
            toggleButton = $get('ToggleSignInButton');
            switch (toggleButton.value) {
                case 'Show SignIn':
                    toggleButton.value = 'Hide SignIn';
                    domElement.style.visibility = 'visible';
                    break;
                case 'Hide SignIn':
                    toggleButton.value = 'Show SignIn';
                    domElement.style.visibility = 'hidden';
                    break;
            }
            // Create a new SignIn control.
            if (!isDefined) {
                Microsoft.Live.Core.Loader.load(['microsoft.live.ui'], function () {
                    signInControl = new Microsoft.Live.UI.SignIn(domElement);
                    signInControl.set_signedInText('Click to sign out!');
                    signInControl.set_signedOutText('Click to sign in.');
                    signInControl.add_signin(signInCallback);
                    signInControl.add_signout(signOutCallback);
                    signInControl.initialize();
                    isDefined = true;
                });
            }
        }
        function signInCallback(eventArgs) {
            // check eventArgs.get_resultCode()
            alert('Signed in.');
        }
        function signOutCallback() {
            alert('Signed out.');
        }

    </script>
</head>
<body>
    <wl:app 
    channel-url="/channel.htm" 
    callback-url="/OAuthWrapCallback.ashx?wl_session_id=<%= Session.SessionID %>"
    client-id="<Your-Client-Id>" 
    scope="WL_Profiles.View" 
    onload="{{appLoaded}}">
    </wl:app>
    <input type="button" id="ToggleSignInButton" value="Show SignIn" onclick="addSignInControl()" />
    <div id="SignInControlDiv" />
</body>
</html>
Show: