Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Microsoft OneDrive file picker for web apps

Live Connect provides the Microsoft OneDrive 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 OneDrive storage location.

Note  The OneDrive 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

The following web browsers support the OneDrive 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

Top

Scenarios

There are two primary scenarios for using the OneDrive file picker. Your web app can either:

Display the OneDrive file picker after the user has clicked a pre-built button with the OneDrive logo.

-or-

Display the OneDrive file picker in response to the user interacting with your web app's UI (other than clicking the OneDrive button), or proactively without prior user interaction.

In both scenarios, the user must provide a list of files to upload or download from OneDrive to your web app. Using the file picker, you can provide a user interface that's presented and branded in a familiar way and also saves you coding time. Here's how it works.

  1. When the OneDrive file picker appears, the user either:
    • Clicks the OneDrive folder to upload a file to.
    • Clicks the combination of folders or files or both to download, and then clicks Open.
  2. The user then clicks Save.
  3. The file picker returns the user-selected list of folders or files, or both, to your web app.
  4. Your web app then uses this list to upload or download the files to or from OneDrive.

Top

Coding techniques

After you decide which OneDrive file picker scenario you want to use, you can use the following coding techniques in your web app.

Display the OneDrive button by calling the WL.ui method

To display the OneDrive button, create a <div> tag and call the WL.ui method. Then follow these guidelines.

  • The <div> tag must include an id attribute set to a unique value.
  • 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.

    Note  You can upload only one file at a time.

  • 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 OneDrive button; otherwise the call to the WL.upload method later will fail.

The WL.ui method accepts these parameters:

ParameterRequired/OptionalDescriptionValid valuesDefault value
nameRequired.The type of user interface control to display.The value of this parameter is always skydrivepicker.None.
modeRequired. The text to display on the OneDrive button.

save: Displays the text "Save to my OneDrive" to upload a file.

open: Displays the text "Choose from my OneDrive" to download a file.

None.
lightbox_colorOptional. The color theme for the OneDrive button.white, grey, or transparent.white
themeOptional.The color of the picker button.white or blue.white
selectRequired.Specifies whether the user can select a single file or folder or multiple files and folders.

single: single file

multi: multiple files and folders

None.
elementRequired.The id attribute of the <div> tag that displays the OneDrive button.Can be any unique value.None.
callbackRequired.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.The name of the app-defined function.None.

 

When the user clicks the OneDrive 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 OneDrive upload location (to upload the user-selected file to) or the list of OneDrive download locations (to download the user-selected files from). Then either call the WL.upload method and supply the OneDrive upload location and info about the user-selected file, or call the WL.download method and supply the list of OneDrive download locations.

You can get the OneDrive upload location from the JavaScript Object Notation (JSON)-formatted data by getting the value of response.data.folders[0].id that's returned from the WL.ui method call. You can also get the list of OneDrive download locations from the JSON-formatted data by getting the response.data.folders and response.data.files arrays that are returned from the WL.ui method call. 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:

ParameterRequired/OptionalDescriptionValid valuesDefault value
pathRequired.The unique OneDrive folder ID to upload the file to.

Note  You can upload only one file at a time.

A path or folder ID.None.
file_nameRequired.The user-defined or app-defined name of the file to upload.

Note  Don't include the file name extension.

A file name, without the extension.None.
elementRequired.The id attribute of the <input> tag.Can be any unique value.None.
overwriteOptional.Specifies whether to overwrite the file if a file of the same name exists.
  • true: Overwrites any existing file in the specified OneDrive folder with the same name.

  • false: Prevents overwriting an existing file by failing if there is already a file with the same name in the specified OneDrive folder.

  • rename: Uploads the file to the specified OneDrive folder even if that folder already has a file with the same name.

    Note  When an file exists with the same name in the specified OneDrive folder, OneDrive 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 OneDrive folder as textfile 1.txt.

false

 

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 OneDrive 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">OneDrive 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">OneDrive 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 OneDrive file picker directly—for example, in response to a button that is clicked (other than the OneDrive 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.

Note  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:

ParameterRequired/OptionalDescriptionValid valuesDefault value
modeRequired.The type of controls that the file picker displays.

save: upload controls

open: download controls

None.
lightbox_colorOptional.The color theme for the file picker's controls.white, grey, or transparent.white
selectRequired.The number of files or folders the user can select.

single: Enable the user to select a single file or folder only.

multi: Enable the user to select multiple files and folders.

None.

 

After the user clicks Save or Open, the WL.filedialog method calls its then method. If the then method's onSuccess parameter gets the OneDrive upload location (to upload the user-selected file to), call the WL.upload method and supply the OneDrive upload location and info about the user-selected file. If onSuccess gets the list of OneDrive download locations (to download the user-selected files from), call the WL.download method and supply the list of OneDrive download locations.

For details about getting either the OneDrive upload location or the list of OneDrive 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 OneDrive 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 OneDrive 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;
        }
    );
}


Top

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  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:

Top

 

 

Show:
© 2014 Microsoft