Question

I’m trying to understand HTML5 API.
I’m designing the web application where the browser client need to download multiple files from server; user will perform something with the downloaded files and the application than need to save the state on user hard-rive. I understand that the browser can save these files only to its sandbox which is fine as long as the user can retrieve those files on the second time he starts the application.
Should I use BlobBuilder or FileSaver? I’m a bit lost here.

Answer 1

I’m going to show you how to download files with the XMLHttpRequest Level 2 and save them with the FileSystem API or with the FileSaver interface.

##Downloading Files##

To download a file you will use the XMLHttpRequest Level 2 (aka XHR2), which supports cross-origin requests, uploading progress events, and uploading/downloading of binary data. In the post "New Tricks in XMLHttpRequest2" there’s plenty of examples of use of XHR2.

To download a file as a blob all you have do to is specify the responseType to "blob". You can also use the types "text", "arraybuffer" or "document". The function below downloads the file in the url and sends it to the success callback:

function downloadFile(url, success) {
    var xhr = new XMLHttpRequest(); 
    xhr.open('GET', url, true); 
    xhr.responseType = "blob";
    xhr.onreadystatechange = function () { 
        if (xhr.readyState == 4) {
            if (success) success(xhr.response);
        }
    };
    xhr.send(null);
}

The success callback will receive as argument an instance of Blob that can be later modified and saved and/or uploaded to a server.

##Saving Files with the FileSystem API##

As the Can i use… site points out there aren’t many browsers with support to the FileSystem API. For Firefox there’s an explanation for the lack of support. So, you will have to use Chrome to do this.

First you will have to request a storage space, it can be either temporary or persistent. You will probably want to have a persistent storage, in this case you will have request a quota of storage space upfront (some facts):

window.requestFileSystem  = window.requestFileSystem || window.webkitRequestFileSystem;
window.storageInfo = window.storageInfo || window.webkitStorageInfo;

// Request access to the file system
var fileSystem = null         // DOMFileSystem instance
    , fsType = PERSISTENT       // PERSISTENT vs. TEMPORARY storage 
    , fsSize = 10 * 1024 * 1024 // size (bytes) of needed space 
;
    
window.storageInfo.requestQuota(fsType, fsSize, function(gb) {
    window.requestFileSystem(fsType, gb, function(fs) {
        fileSystem = fs;
    }, errorHandler);
}, errorHandler);

Now that you have access to the file system you can save and read files from it. The function below can save a blob in the specified path into the file system:

function saveFile(data, path) {
    if (!fileSystem) return;
    
    fileSystem.root.getFile(path, {create: true}, function(fileEntry) {
        fileEntry.createWriter(function(writer) {
            writer.write(data);
        }, errorHandler);
    }, errorHandler);
}

And to read a file by its path:

function readFile(path, success) {
    fileSystem.root.getFile(path, {}, function(fileEntry) {
        fileEntry.file(function(file) {
            var reader = new FileReader();

            reader.onloadend = function(e) {
                if (success) success(this.result);
            };

            reader.readAsText(file);
        }, errorHandler);
    }, errorHandler);
}

In addition to the readAsText method, according to the FileReader API you can call readAsArrayBuffer and readAsDataURL.

##Using the FileSaver##

The post "Saving Generated Files on Client-Side" explains very well the use of this API. Some browsers may need the FileSaver.js in order to have the saveAs interface.

If you use it together with the downloadFile function, you could have something like this:

downloadFile('image.png', function(blob) {
    saveAs(blob, "image.png");
});

Of course it would make more sense if the user could visualize the image, manipulate it and then save it in his drive.

###Error Handler###

Just to fulfill the example:

function errorHandler(e) {
    var msg = '';

    switch (e.code) {
        case FileError.QUOTA_EXCEEDED_ERR:
            msg = 'QUOTA_EXCEEDED_ERR';
            break;
        case FileError.NOT_FOUND_ERR:
            msg = 'NOT_FOUND_ERR';
            break;
        case FileError.SECURITY_ERR:
            msg = 'SECURITY_ERR';
            break;
        case FileError.INVALID_MODIFICATION_ERR:
            msg = 'INVALID_MODIFICATION_ERR';
            break;
        case FileError.INVALID_STATE_ERR:
            msg = 'INVALID_STATE_ERR';
            break;
        default:
            msg = 'Unknown Error';
            break;
    };

    console.log('Error: ' + msg);
}

##Useful links##

• Saving Generated Files on the Client-Side
• Exploring the FileSystem APIs
• New Tricks in XMLHttpRequest2
• Reading Files in JavaScript Using the File APIs