Live Connect provides the Microsoft SkyDrive file picker, a pre-built, consistent user interface that enables your JavaScript-based web apps to get either a folder location or a list of files from your user. Your web app can then use this info to upload or download files to and from the user's SkyDrive storage location.
Note The SkyDrive file picker is provided as part of the Live Connect JavaScript API (web) and therefore is available only for JavaScript-based web apps. For Windows Store apps, use a comparable user experience that Windows 8 already provides—for example, the various classes in the Windows.Storage.Pickers namespace. For all other app types, you'll have to provide your own user experience.
- Supported web browsers
- Scenarios
- Coding techniques
- JSON format for folder and file lists
- Related info
Supported web browsers
The following web browsers support the SkyDrive file picker:
- Microsoft Internet Explorer, starting with version 8
- Mozilla Firefox, starting with version 10
- Apple Safari, starting with version 5.1
- Google Chrome, starting with version 17
Scenarios
There are two primary scenarios for using the SkyDrive file picker. In both scenarios, your web app needs to get from the user a list of files to upload to or download from SkyDrive. The file picker provides a user interface that's presented and branded in a familiar way and saves you coding time.
In the first scenario, your web app displays a pre-built button with the SkyDrive logo to upload or download files to or from SkyDrive. After the user clicks this button, the SkyDrive file picker appears.
In the second scenario, your web app displays the SkyDrive file picker in response to the user interacting with your web app's UI (other than clicking the SkyDrive button), or your app displays the SkyDrive file picker proactively, without prior user interaction.
After the SkyDrive file picker appears, to upload a file, the user clicks the SkyDrive folder to upload the file to, and then clicks Save. To download files by using the file picker, the user clicks the combination of folders or files or both to download, and then clicks Open. After the user clicks Save or Open, the file picker returns the user-selected list of folders or files, or both, to your web app. Your web app then uses this list to upload or download the files to or from SkyDrive.
Coding techniques
After you determine which SkyDrive file picker scenario you want to use, you can use the following coding techniques in your web app.
Display the SkyDrive button by calling the WL.ui method
To display the SkyDrive button, create a <div> tag and then call the WL.ui method. If your web app is uploading a file, you also create a <form> tag and an <input> tag to get info about the file to upload. (You can upload only one file at a time.)
The <div> tag must include an id attribute set to a unique value.
The <form> tag must contain one and only one <input> tag. This <input> tag must include name, type, and id attributes. The value of the name and type attributes must be "file". (The id attribute can be set to any value, which is referred to by the WL.upload function's element parameter.) The user must provide info about the file to this <input> tag—typically by clicking the <input> tag's accompanying Browse button and following the on-screen directions—before clicking the SkyDrive button; otherwise the call to the WL.upload method later will fail.
The WL.ui method accepts these parameters:
- The required name parameter specifies the type of user interface control to display. The value of this parameter is always skydrivepicker.
- The required mode parameter specifies the text to display on the SkyDrive button. Specify save to display the text "Save to my SkyDrive" to upload a file. Specify open to display the text "Choose from my SkyDrive" to download files.
- The optional lightbox_color parameter specifies the color theme for the SkyDrive button. Specify white (default), grey, or transparent.
- The theme parameter specifies the color of the picker button. The parameter is optional; the default value is white and the other legal value is blue.
- The required select parameter specifies whether the user can select a single file or folder (specify single) or multiple files and folders (specify multi).
- The required element parameter specifies the id attribute of the <div> tag that displays the SkyDrive button.
- The required callback parameter specifies the name of the app-defined function that the WL.ui method will call after the user clicks the file picker's Save or Open button.
When the user clicks the SkyDrive button, the file picker appears. After the user clicks Save or Open, the WL.ui method calls the function that's specified in its callback parameter. In the callback function, get the SkyDrive upload location (to upload the user-selected file to) or the list of SkyDrive download locations (to download the user-selected files from). Then either call the WL.upload method and supply the SkyDrive upload location and info about the user-selected file, or call the WL.download method and supply the list of SkyDrive download locations.
You can get the SkyDrive upload location from the JavaScript Object Notation (JSON)-formatted data that's returned from the WL.ui method call. From that data, get the value of response.data.folders[0].id, where response is the name of the parameter that's specified in the WL.ui method's onSuccess parameter. For more info, see "JSON format for folder and file lists" later in this topic.
You can also get the list of SkyDrive download locations from the JSON-formatted data that's returned from the WL.ui method call. Loop through the response.data.folders and response.data.files arrays, where response is the name of the parameter that's specified in the WL.ui method's onSuccess parameter. For more info, see "JSON format for folder and file lists" later in this topic.
The WL.upload method accepts these parameters:
-
The required path parameter specifies the unique SkyDrive folder ID to upload the file to. (You can upload only one file at a time.)
-
The required file_name parameter specifies the user-defined or app-defined name of the file to upload. (Do not include the file name extension.)
-
The required element parameter specifies the id attribute of the <input> tag.
-
For the optional overwrite parameter, you can specify one of the following values:
-
true
Overwrites any existing file in the specified SkyDrive folder with the same name.
-
false (the default)
Prevents overwriting an existing file by failing if there is already a file with the same name in the specified SkyDrive folder.
-
rename
Uploads the file to the specified SkyDrive folder even if that folder already has a file with the same name.
When an file exists with the same name in the specified SkyDrive folder, SkyDrive chooses the uploaded file's name and ignores the value of the file_name parameter. The renamed file will start with the name of the existing file and will end with a sequential number. For example, if you specify rename and upload a file named textfile.txt to a folder that already contains a file with that name, the file will be stored in the SkyDrive folder as textfile 1.txt.
-
If the WL.upload method call is successful, you can use its then method's onSuccess parameter to report the success. Otherwise, you can use its then method's onError parameter to report an unsuccessful call. To check the progress of the WL.upload method call, you can use its then method's onProgress parameter; however, checking progress applies only to newer web browsers such as Internet Explorer 10.
The WL.download method accepts only one parameter:
- The required path parameter specifies the unique SkyDrive file ID of the file to download.
If the WL.download method call is unsuccessful, you can use its then method's onError parameter to report the error. (In this case, the WL.download doesn't support the onSuccess and onProgress parameters.) If the WL.download method call is successful, the user experience for actually downloading the files will differ based on the type of web browser in use.
Here's a code example that shows how to upload a file by using a <form> tag, an <input> tag, a <div> tag, the WL.ui method, an app-defined callback function, and the WL.upload method.
<form> <input id="file" name="file" type="file" /> </form>
<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;
}
Here's a code example that shows how to use a <div> tag and the WL.ui method to display a list of files that the user wants to download.
<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;
}
Display the file picker directly by calling the WL.fileDialog method
You can display the SkyDrive file picker directly—for example, in response to a button that is clicked (other than the SkyDrive button). To do this, if your web app is uploading a file, you must create a <form> tag and an <input> tag to get info about the file to upload. (You can only upload one file at a time.) Then, whether your web app is uploading or downloading files, call the WL.fileDialog method.
For details about the <input> tag, see the previous section.
The WL.fileDialog method accepts the following parameters:
- The required mode parameter specifies the type of controls that the file picker displays. Specify save for upload controls or open for download controls.
- The optional lightbox_color parameter specifies the color theme for the file picker's controls. Specify white (default), grey, or transparent.
- The required select parameter specifies how many files or folders the user can select. Specify single to enable the user to select a single file or folder only, or multi to enable the user to select multiple files and folders.
After the user clicks Save or Open, the WL.filedialog method calls its then method. In the then method's onSuccess parameter, get the SkyDrive upload location (to upload the user-selected file to) or the list of SkyDrive download locations (to download the user-selected files from). Then either call the WL.upload method and supply the SkyDrive upload location and info about the user-selected file, or call the WL.download method and supply the list of SkyDrive download locations.
For details about getting either the SkyDrive upload location or the list of SkyDrive download locations, see the previous section.
For details about the WL.upload and WL.download methods, see the previous section.
Here's a code example that shows how to upload a file by using a <form> tag, an <input> tag, a <button> tag, the WL.fileDialog method, and the WL.upload method.
<form> <input id="file" name="file" type="file" /> </form>
<button onclick="uploadFile_fileDialog()">Save file with SkyDrive file picker (calling WL.filedialog)</button>
function uploadFile_fileDialog() { WL.fileDialog({ mode: "save" }).then( function (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 (responseFailed) { document.getElementById("info").innerText = "Error getting folder info: " + responseFailed.error.message; } ); }
Here's a code example that shows how to use a <button> tag and the WL.fileDialog method to display a list of files that the user wants to download.
<button onclick="downloadFile_fileDialog()">Open file with SkyDrive file picker (calling WL.filedialog)</button>
function downloadFile_fileDialog() { WL.fileDialog({ mode: "open", select: "multi" }).then( function (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 (responseFailed) { document.getElementById("info").innerText = "Error getting folder/file info: " + responseFailed.error.message; } ); }
JSON format for folder and file lists
If the WL.ui or WL.fileDialog method call is successful, the method returns the resulting folder info (for upload or download requests) or file info (for download requests) to your app's code. The folder and file info is returned as a JSON-formatted object. Your app's code can then extract the folder ID and use it to call the WL.upload method (for upload requests), or to extract the folder IDs or file IDs, or both, and use them to call the WL.download method (for download requests).
For upload requests, the JSON-formatted object looks similar to this.
{
"data": {
"folders": [
{
"id": "folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!110",
... Additional info about this folder ...
}
]
}
}
Note Because only one folder can be selected for an upload request, there is only one object in the returned folders array. Also, no files array is returned.
Your app can then call the WL.upload method, specifying response.data.folders[0].id for the WL.upload method's path parameter. In the example just given, response is the name of the parameter that's specified in the WL.ui or WL.fileDialog method's onSuccess parameter.
For download requests, the JSON-formatted object looks similar to this, depending on the number of folders or files, or both, that are selected.
{
"data": {
"folders": [
{
"id": "folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!110",
... If this folder was selected, additional info about this folder ...
},
{
"id": "folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!145",
... If this folder was selected, additional info about this folder ...
},
... Info about additional folders that were selected, if any ...
],
"files": [
{
"id": "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!131",
... If this file was selected, additional info about this file ...
},
{
"id": "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!144",
... If this file was selected, additional info about this file ...
},
{
"id": "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!152",
... If this file was selected, additional info about this file ...
},
... Info about additional files that were selected, if any ...
]
}
}
Note If no folders were selected, the folders array is still returned but is empty—for example, "folders": []. Likewise, if no files were selected, the files array is still returned but is empty—for example, "files": [].
Your app can then call the WL.download method to download the files one at a time, specifying response.data.files[i].id for the WL.download method's path parameter. In the example just given, response is the name of the parameter that's specified in the WL.ui or WL.fileDialog method's onSuccess parameter, and i is the name of the variable that's used to iterate through the lists of files. For code examples, see the previous sections.
To download files that are inside a folder, you first need to get the folder ID by specifying response.data.folders[i].id for the WL.api method's path parameter. In this example also, response is the name of the parameter that's specified in the WL.ui or WL.fileDialog method's onSuccess parameter, and i is the name of the variable that's used to iterate through the list of folders. Your app can then use the response to iterate through the list of files in the folder and call the WL.download method on each file. For code examples, see the previous sections.
Tip Of course, you could also specify response.data[j].folders[i].id, where j is the name of the variable that's used to iterate through either the folders array (data[0]) or the files array (data[1]).
Related info
For more info, see:
- The Live Interactive SDK, where you can experiment with the SkyDrive file picker without writing any code
- Working with Microsoft SkyDrive folders and files, "Downloading files" and "Uploading files" sections
- WL.download
- WL.fileDialog
- WL.ui
- WL.upload
Build date: 5/15/2013
