download

========

Summary

---------
The download() function is used to trigger a file download from JavaScript.

It specifies the contents and name of a new file placed in the browser's download directory. The input can be a URL, String, Blob, or Typed Array of data, or via a dataURL representing the file's data as base64 or url-encoded string. No matter the input format, download() saves a file using the specified file name and mime information in the same manner as a server using a Content-Disposition HTTP header.

Getting and Using

---------

$3

npm install downloadjs

bower install downloadjs

require("downloadjs")(data, strFileName, strMimeType);

$3

download(data, strFileName, strMimeType);

$3

require(['path/to/file'], function(download) {
download(data, strFileName, strMimeType);
});

$3

---------
* data - The Blob, File, String, or dataURL containing the soon-to-be File's contents.
* strFileName - The name of the file to be created. Note that older browsers (like FF3.5, Ch5) don't honor the file name you provide, instead they automatically name the downloaded file.
* strMimeType - The MIME content-type of the file to download. While optional, it helps the browser present friendlier information about the download to the user, encouraging them to accept the download.

Example Usage

---------

$3

#### text string - live demo
download("hello world", "dlText.txt", "text/plain");

#### text dataURL - live demo
download("data:text/plain,hello%20world", "dlDataUrlText.txt", "text/plain");

#### text blob - live demo
download(new Blob(["hello world"]), "dlTextBlob.txt", "text/plain");

#### text url - live demo
download("/robots.txt");

#### text UInt8 Array - live demo
var str= "hello world", arr= new Uint8Array(str.length);
str.split("").forEach(function(a,b){
arr[b]=a.charCodeAt();
});

download( arr, "textUInt8Array.txt", "text/plain" );

$3

#### html string - live demo
download(document.documentElement.outerHTML, "dlHTML.html", "text/html");

#### html Blob - live demo
download(new Blob(["hello world".bold()]), "dlHtmlBlob.html", "text/html");

#### ajax callback - live demo
(note that callback mode won't work on vanilla ajax or with binary files)

$.ajax({
url: "/download.html",
success: download.bind(true, "text/html", "dlAjaxCallback.html")
});

$3

#### image from URL - live demo
download("/diff6.png");

#### Image via ajax for custom filename - live demo
var x=new XMLHttpRequest();
x.open( "GET", "/diff6.png" , true);
x.responseType="blob";
x.onload= function(e){download(e.target.response, "awesomesauce.png", "image/png");};
x.send();

Compatibility

---------
download.js works with a wide range of devices and browsers.

You can expect it to work for the vast majority of your users, with some common-sense limits:

* Devices without file systems like iPhone, iPad, Wii, et al. have nowhere to save the file to, sorry.
* Android support starts at 4.2 for the built-in browser, though chrome 36+ and firefox 20+ on android 2.3+ work well.
* Devices without Blob support won't be able to download Blobs or TypedArrays
* Legacy devices (no a[download]) support can only download a few hundred kilobytes of data, and can't give the file a custom name.
* Devices without window.URL support can only download a couple megabytes of data
* IE versions of 9 and before are NOT supported because the don't support a[download] or dataURL frame locations.

FAQ

---------

* Can I tell when a download is done/canceled? No.
* How can I style the temporary download link? Define CSS class styles for .download-js-link.
* What's up with Safari? I don't know either but pull requests that improve the situation are welcome.
* Why is my binary file corrupted? Likely: an incorrect MIME or using jQuery ajax, which has no bin support.
* How big of files work? Depends, try yourself: File Echo Demo... I do a 1GB dl routinely on a thinkpad...

Change Log (v4.1)

---------
* 2008 :: landed a FF+Chrome compat way of downloading strings to local un-named files, upgraded to use a hidden frame and optional mime
* 2012 :: added named files via a[download], msSaveBlob() for IE (10+) support, and window.URL support for larger+faster saves than dataURLs
* 2014 :: added dataURL and Blob Input, bind-toggle arity, and legacy dataURL fallback was improved with force-download mime and base64 support
* 2015 :: converted to amd/commonJS module with browser-friendly fallback
* 2015 :: 4.1 added direct URL downloading via a single URL argument.
* 2016 :: 4.2 added large dataURL support, a more semantic codebase, and hidden temp links
* 2017 :: added support for empty dataURLs
* 20XX :: ???? Considering Zip, Tar, and other multi-file outputs, Blob.prototype.download option, and more, stay tuned folks.