Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/rndme/download

file downloading using client-side javascript
https://github.com/rndme/download

Last synced: about 2 months ago
JSON representation

file downloading using client-side javascript

Awesome Lists containing this project

README 

        
# download 



[![NPM version][npm-image]][npm-url] 

[![Size][size-image]][size-url] 

[![License][license-image]][license-url] 

[![CDNJS](https://img.shields.io/cdnjs/v/downloadjs.svg)](https://cdnjs.com/libraries/downloadjs)



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

---------



### Via NPM/Bower 

`npm install downloadjs`  


`bower install downloadjs`



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



### Simple global `download` function via `` include

    download(data, strFileName, strMimeType);



### Included via AMD

    require(['path/to/file'], function(download) {

        download(data, strFileName, strMimeType);

    });



### Parameters

---------

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

---------



### Plain Text

#### text string  -  [live demo](http://pagedemos.com/hw24em95rsfq/output/)

    download("hello world", "dlText.txt", "text/plain");



#### text dataURL  -  [live demo](http://pagedemos.com/r9ywm98s6b29/output/)

    download("data:text/plain,hello%20world", "dlDataUrlText.txt", "text/plain");



#### text blob  -  [live demo](http://pagedemos.com/ckcah2vp8kza/output/)

    download(new Blob(["hello world"]), "dlTextBlob.txt", "text/plain");



#### text url - [live demo](http://pagedemos.com/pz6hkyqutjtw/output/)

    download("/robots.txt");



#### text UInt8 Array -  [live demo](http://pagedemos.com/zuyk46wbkktq/output/)

    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" );



### HTML

#### html string -  [live demo](http://pagedemos.com/k7rwq7msu3eb/output/)

    download(document.documentElement.outerHTML, "dlHTML.html", "text/html");



#### html Blob -  [live demo](http://pagedemos.com/bxehm2fdf3g4/output/)

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



#### ajax callback -  [live demo](http://pagedemos.com/arr2ym74aw8t/output/)

(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")

    });



### Binary Files

#### image from URL  -  [live demo](http://pagedemos.com/yvvmxbjrwq7u/output/)

    download("/diff6.png");



#### Image via ajax for custom filename - [live demo](http://pagedemos.com/v2848zfgwrju/output/)

	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](http://pagedemos.com/gqs6hbmjcpem/)... I do a 1GB dl routinely on a thinkpad...



## Change Log (v4.1)

---------

* 2008 :: landed a FF+Chrome compatible 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.



[MIT license]: http://opensource.org/licenses/MIT

[npm-image]: https://badge.fury.io/js/downloadjs.svg

[npm-url]: https://npmjs.org/package/downloadjs

[license-image]: https://img.shields.io/badge/license-MIT-green.svg

[license-url]: http://opensource.org/licenses/MIT

[size-image]: http://img.badgesize.io/rndme/download/master/download.min.js.svg?compression=gzip&label=gzip%20size

[size-url]: https://unpkg.com/downloadjs