WL.ui function

Displays either the Live Connect sign-in button or the Microsoft SkyDrive file picker button. The sign-in button either prompts the user for his or her Microsoft account credentials if he or she is not signed in or else signs out the user if he or she is signed in. The file picker button displays the SkyDrive file picker to help the user select files to upload or download to or from his or her SkyDrive storage location.

Parameters

properties

Required. A JSON object containing the following properties for displaying the button.

Name	Type	Description	Default Value
name	string	Required. Specifies the type of button to display. Specify "signin" to display the Live Connect sign-in button. Specify "skydrivepicker" to display the SkyDrive button..	None.
element	string	Required. The value of the id attribute of the <div> tag to display the button in.	None.
state	string	Windows Store apps using JavaScript: not applicable. Web apps: Optional. If the name property is set to "signin", the WL.init function's response_type property is set to "code", and the app uses server-flow authentication, the state object here can be used to track the web app's calling state on the web app server side. For more info, see the description of the state query parameter in the Server-side scenarios topic's "Getting an authorization code" section.	None.

 

If the value of the name property is set to "skydrivepicker", the properties object can also contain the following.

Name	Type	Description	Default Value
mode	string	Required. The type of SkyDrive file picker button to display. Specify "save" to display the upload button. Specify "open" to display the download button.	None.
select	string	Required if the mode property is set to "open". Specifies how many files the user can select to download. Specify "single" for a single file. Specify "multi" for multiple files.	"single"
theme	string	Optional. Defines the color pallette used for the file picker button. Valid values are "white" and "blue".	"white"
lightbox	string	Optional. Defines the color pallette used for the file picker dialog box. Valid values are "white", "gray", and "transparent".	"white"
onselected	object	Optional. If the mode property is set to "save", specifies the function to call after the user clicks either Save or Cancel in the file picker. If the mode property is set to "open", specifies the function to call after the user clicks either Open or Cancel in the file picker.	None.
onerror	object	Optional. Specifies the function to call if the selected files cannot be successfully uploaded or downloaded.	None.

 

If the value of the name property is set to "signin", the properties object can also contain the following.

Name	Type	Description	Default Value
brand	string	Optional. Defines the brand, or type of icon, to be used with the Live Connect sign-in button. Valid values for this property are listed in the next table.	"windows"
theme	string	Optional. Defines the color pallette used for the sign-in button. For Windows Store apps using JavaScript, valid values are "dark" and "light". For web apps, valid values are "blue" and "white".	"dark" (for Windows Store apps using JavaScript) "blue" (for web apps)
type	string	Optional. Defines the type of button. Valid values for this property are listed in the second table following this one.	"signin"
sign_in_text	string	Optional. If the value of the type property is set to "custom", this value specifies the sign-in text to be displayed in the button.	None.
sign_out_text	string	Optional. If the value of the type property is "custom", this value specifies the sign-out text to be displayed in the button.	None.
onloggedin	object	Optional. Specifies the function to call after the user completes the sign-in process.	None.
onloggedout	object	Optional. Specifies the function to call after the user completes the sign-out process.	None.
onerror	object	Optional. Specifies the function to call whenever there is any error while the sign-in control is initializing or while the user is signing in.	None.

 

Tip  Using the onloggedin, onloggedout, and onerror parameters is functionally equivalent to calling the WL.Event.subscribe("auth.login", callback) function.

The sign-in button's brand property can have one of the following values.

Value	Description
"messenger"	Messenger. Shows the Messenger "buddy" icon.
"hotmail"	Hotmail. Shows the "envelope" icon.
"windows"	Live Connect. Shows the Live Connect "flag" icon. This is the default value for both web apps and Windows Store apps using JavaScript.
"skydrive"	SkyDrive. Shows the SkyDrive icon.
"none"	If the value "none" is specified, no icon is shown. If the brand property is left blank, the default value is shown.

 

The sign-in button's type property can have one of the following values.

Value	Sign-in text	Sign-out text	Additional info
"signin"	Sign in	Sign out	Default.
"login"	Login	Logout	Not applicable.
"connect"	Connect	Sign out	Not applicable.
"custom"	The value supplied in the sign_in_text property.	The value supplied in the sign_out_text property.	Your app defines the text. If the app does not provide sign_in_text and sign_out_text property values, the library will return an error, and the button will not be displayed.

 

callback

Optional. A callback function that is executed after the sign-in button or file picker button is displayed.

Note  Do not use the callback parameter to run code after the user finishes interacting with the sign-in button or file picker. Use a combination of the onselected, onloggedin, onloggedout, and onerror properties as previously described.

Remarks

The sign-in coding patterns that are appropriate for Windows Store apps using C# are described in the Guidelines for the Microsoft account sign-in experience.

Examples

The following example demonstrates how to display the Live Connect sign-in button.

WL.ui({
    name: "signin",
    element: "signin"
});

The following example demonstrates how to display the upload version of the SkyDrive file picker.

<div id="uploadFile_div">SkyDrive save button to appear here</div>

WL.ui({
    name: "skydrivepicker",
    element: "uploadFile_div",
    mode: "save",
    onselected: onUploadFileCompleted,
    onerror: onUploadFileError
});

function onUploadFileCompleted(response) {
    WL.upload({
        path: response.data.folders[0].id,
        element: "file",
        overwrite: "rename"
    }).then(
        function (response) {
            document.getElementById("info").innerText = 
                "File uploaded."; 
        },
        function (responseFailed) {
            document.getElementById("info").innerText =
                "Error uploading file: " + responseFailed.error.message;
        }
    );
};

function onUploadFileError(response) {
    document.getElementById("info").innerText =
        "Error getting folder info: " + response.error.message; 
}

The following example demonstrates how to display the download version of the file picker.

<div id="downloadFile_div">SkyDrive open button to appear here</div>

WL.ui({
    name: "skydrivepicker",
    element: "downloadFile_div",
    mode: "open",
    select: "multi",
    onselected: onDownloadFileCompleted,
    onerror: onDownloadFileError
});

function onDownloadFileCompleted(response) {
    var msg = "";
    // For each folder selected...
    if (response.data.folders.length > 0) {
        for (folder = 0; folder < response.data.folders.length; folder++) {
            // Use folder IDs to iterate through child folders and files as needed.
            msg += "\n" + response.data.folders[folder].id;
        }
    }
    // For each file selected...
    if (response.data.files.length > 0) {
        for (file = 0; file < response.data.files.length; file++) {
            // Use file IDs to iterate through files as needed.
            msg += "\n" + response.data.files[file].id;
        }
    }
    document.getElementById("info").innerText =
        "Selected folders/files:" + msg;
};

function onDownloadFileError(responseFailed) {
    document.getElementById("info").innerText =
        "Error getting folder/file info: " + responseFailed.error.message;
}

Requirements

Build date: 3/12/2013