How to save files through file pickers (HTML)

Article
10/13/2015

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

Use fileSavePicker to let users specify the name and location where they want to save your app’s content.

Prerequisites

Understand async programming for Windows Runtime apps using JavaScript

You can learn how to write asynchronous apps in Quickstart: Using promises in JavaScript.

Instructions

Step 1: Create and customize the file picker to display locations where users can save

Use fileSavePicker so that your user can specify the name, file type, and location of a file to save. You can customize the file picker by setting properties on the fileSavePicker you create.

The File picker sample demonstrates how to create and customize a fileSavePicker object.

// Create the picker object and set options
var savePicker = new Windows.Storage.Pickers.FileSavePicker();
savePicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.documentsLibrary;
// Dropdown of file types the user can save the file as
savePicker.fileTypeChoices.insert("Plain Text", [".txt"]);
// Default file name if the user does not type one in or select a file to replace
savePicker.suggestedFileName = "New Document";

You should set fileSavePicker properties that are relevant to your users and your app. For guidelines to help you decide how to customize the file picker, see Guidelines and checklist for file pickers.

The File picker sample customizes the file picker by setting three fileSavePicker properties: suggestedStartLocation, fileTypeChoices and suggestedFileName properties.

Note fileSavePicker objects use pickerViewMode.list to display data.

JJ150595.wedge(en-us,WIN.10).gif Customizing a fileSavePicker, in detail

Because our user is saving a document or text file, the sample sets savePicker.suggestedStartLocation to the app's local folder by using LocalFolder.
```
savePicker.suggestedStartLocation = Windows.Storage.ApplicationData.localFolder;
```
You should set suggestedStartLocation to file system location that is appropriate for the type of file that is being picked. If the user is picking music, pictures, or videos, set the start location to Music, Pictures, or Videos respectively. For all other types of files, set the start location to the app's local folder. This is just a starting location. Users can navigate to other locations while they are using the file picker.
Because we want to make sure our app can open the file after it is saved, the sample uses savePicker.fileTypeChoices.insert to specify file types that the sample supports (Microsoft Word documents and text files).
```
savePicker.fileTypeChoices.insert("Plain Text", [".txt"]);
```
Make sure all the file types that you specify are supported by your app.

Users will be able to save their file as any of the file types you specify in this list. They can also change the file type by selecting a different file type (that you specified) from the drop-down control in the lower right of the file picker. The first file-type choice in the list will be selected by default. To change which file type is selected by default, set the savePicker.defaultFileExtension property.

Note The file picker also uses the currently selected file type to filter which files it displays, so that only file types that match the selected files types are displayed to the user.
Because we want to save the user some typing, the sample sets a savePicker.suggestedFileName for the file to save.
```
savePicker.suggestedFileName = "New Document";
```
Try to make your suggested file name as relevant as possible to the file that your user is saving. For example, like Word, you can suggest the existing file name if there is one, or the first line of a document if the user is saving a file that does not yet have a name.

Step 2: Show the fileSavePicker to save a file

After you create and customize the file picker, let the user save the file by calling savePicker.pickSaveFileAsync.

After the user specifies the name, file type, and location, and confirms to save the files, pickSaveFileAsync returns a storageFile object that represents the saved file. You can capture and process this file by using then or done.

The File picker sample demonstrates how to display the file picker to let the user save a file.

savePicker.pickSaveFileAsync().then(function (file) {
    if (file) {
        // Prevent updates to the remote version of the file until we finish making changes and call CompleteUpdatesAsync.
        Windows.Storage.CachedFileManager.deferUpdates(file);
        // write to file
        Windows.Storage.FileIO.writeTextAsync(file, file.name).done(function () {
            // Let Windows know that we're finished changing the file so the other app can update the remote version of the file.
            // Completing updates may require Windows to ask for user input.
            Windows.Storage.CachedFileManager.completeUpdatesAsync(file).done(function (updateStatus) {
                if (updateStatus === Windows.Storage.Provider.FileUpdateStatus.complete) {
                    WinJS.log && WinJS.log("File " + file.name + " was saved.", "sample", "status");
                } else {
                    WinJS.log && WinJS.log("File " + file.name + " couldn't be saved.", "sample", "status");
                }
            });
        });
    } else {
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});

After the file is saved, the app has read and write access to that file. The sample captures the saved file in the file parameter and checks that the file is valid, but the sample doesn't actually process the file further. You can learn how to write to and read from the resulting file in Quickstart: Reading and writing a file.

Tip You should always check the saved file (file in the sample) to make sure it is valid before you perform any other processing. Then, you can save content to the file as appropriate for your app, and provide appropriate behavior if the picked file is not valid.

Remarks

If you use code similar to what is shown here, your app should display the file picker to your users and let them specify the name, file type, and location for a file to save. You can learn how to write to and read from the resulting file in Quickstart: Reading and writing a file.

If you want to add "save as" to your app, add a control to your app's UI that calls the fileSavePicker. To learn about adding controls, see Adding controls and content.

If you want your app to provide a save location to users through the file picker see Quickstart: Integrating with file picker contracts.