Open-ILS/web/js/file-saver/README.md

   1 If you need to save really large files bigger then the blob's size limitation or don't have
   2 enough RAM, then have a look at the more advanced [StreamSaver.js](https://github.com/jimmywarting/StreamSaver.js)
   3 that can save data directly to the hard drive asynchronously with the power of the new streams API. That will have
   4 support for progress, cancelation and knowing when it's done writing
   5
   6 FileSaver.js
   7 ============
   8
   9 FileSaver.js implements the `saveAs()` FileSaver interface in browsers that do
  10 not natively support it. There is a [FileSaver.js demo][1] that demonstrates saving
  11 various media types.
  12
  13 FileSaver.js is the solution to saving files on the client-side, and is perfect for
  14 webapps that need to generate files, or for saving sensitive information that shouldn't be
  15 sent to an external server.
  16
  17 Looking for `canvas.toBlob()` for saving canvases? Check out
  18 [canvas-toBlob.js][2] for a cross-browser implementation.
  19
  20 Supported browsers
  21 ------------------
  22
  23 | Browser        | Constructs as | Filenames    | Max Blob Size | Dependencies |
  24 | -------------- | ------------- | ------------ | ------------- | ------------ |
  25 | Firefox 20+    | Blob          | Yes          | 800 MiB       | None         |
  26 | Firefox < 20   | data: URI     | No           | n/a           | [Blob.js](https://github.com/eligrey/Blob.js) |
  27 | Chrome         | Blob          | Yes          | [500 MiB][3]  | None         |
  28 | Chrome for Android | Blob      | Yes          | [500 MiB][3]  | None         |
  29 | Edge           | Blob          | Yes          | ?             | None         |
  30 | IE 10+         | Blob          | Yes          | 600 MiB       | None         |
  31 | Opera 15+      | Blob          | Yes          | 500 MiB       | None         |
  32 | Opera < 15     | data: URI     | No           | n/a           | [Blob.js](https://github.com/eligrey/Blob.js) |
  33 | Safari 6.1+*   | Blob          | No           | ?             | None         |
  34 | Safari < 6     | data: URI     | No           | n/a           | [Blob.js](https://github.com/eligrey/Blob.js) |
  35
  36 Feature detection is possible:
  37
  38 ```js
  39 try {
  40     var isFileSaverSupported = !!new Blob;
  41 } catch (e) {}
  42 ```
  43
  44 ### IE < 10
  45
  46 It is possible to save text files in IE < 10 without Flash-based polyfills.
  47 See [ChenWenBrian and koffsyrup's `saveTextAs()`](https://github.com/koffsyrup/FileSaver.js#examples) for more details.
  48
  49 ### Safari 6.1+
  50
  51 Blobs may be opened instead of saved sometimes—you may have to direct your Safari users to manually
  52 press <kbd>⌘</kbd>+<kbd>S</kbd> to save the file after it is opened. Using the `application/octet-stream` MIME type to force downloads [can cause issues in Safari](https://github.com/eligrey/FileSaver.js/issues/12#issuecomment-47247096).
  53
  54 ### iOS
  55
  56 saveAs must be run within a user interaction event such as onTouchDown or onClick; setTimeout will prevent saveAs from triggering. Due to restrictions in iOS saveAs opens in a new window instead of downloading, if you want this fixed please [tell Apple](https://bugs.webkit.org/show_bug.cgi?id=102914) how this bug is affecting you.
  57
  58 Syntax
  59 ------
  60
  61 ```js
  62 FileSaver saveAs(Blob/File data, optional DOMString filename, optional Boolean disableAutoBOM)
  63 ```
  64
  65 Pass `true` for `disableAutoBOM` if you don't want FileSaver.js to automatically provide Unicode text encoding hints (see: [byte order mark](https://en.wikipedia.org/wiki/Byte_order_mark)).
  66
  67 Examples
  68 --------
  69
  70 ### Saving text
  71
  72 ```js
  73 var blob = new Blob(["Hello, world!"], {type: "text/plain;charset=utf-8"});
  74 saveAs(blob, "hello world.txt");
  75 ```
  76
  77 The standard W3C File API [`Blob`][4] interface is not available in all browsers.
  78 [Blob.js][5] is a cross-browser `Blob` implementation that solves this.
  79
  80 ### Saving a canvas
  81
  82 ```js
  83 var canvas = document.getElementById("my-canvas"), ctx = canvas.getContext("2d");
  84 // draw to canvas...
  85 canvas.toBlob(function(blob) {
  86     saveAs(blob, "pretty image.png");
  87 });
  88 ```
  89
  90 Note: The standard HTML5 `canvas.toBlob()` method is not available in all browsers.
  91 [canvas-toBlob.js][6] is a cross-browser `canvas.toBlob()` that polyfills this.
  92
  93 ### Saving File
  94
  95 You can save a File constructor without specifying a filename. The
  96 File itself already contains a name, There is a hand full of ways to get a file
  97 instance (from storage, file input, new constructor)
  98 But if you still want to change the name, then you can change it in the 2nd argument
  99
 100 ```js
 101 var file = new File(["Hello, world!"], "hello world.txt", {type: "text/plain;charset=utf-8"});
 102 saveAs(file);
 103 ```
 104
 105
 106
 107 ![Tracking image](https://in.getclicky.com/212712ns.gif)
 108
 109   [1]: http://eligrey.com/demos/FileSaver.js/
 110   [2]: https://github.com/eligrey/canvas-toBlob.js
 111   [3]: https://code.google.com/p/chromium/issues/detail?id=375297
 112   [4]: https://developer.mozilla.org/en-US/docs/DOM/Blob
 113   [5]: https://github.com/eligrey/Blob.js
 114   [6]: https://github.com/eligrey/canvas-toBlob.js
 115
 116 Contributing
 117 ------------
 118
 119 The `FileSaver.js` distribution file is compiled with Uglify.js like so:
 120
 121 ```bash
 122 uglifyjs FileSaver.js --mangle --comments /@source/ > FileSaver.min.js
 123 # or simply:
 124 npm run build
 125 ```
 126
 127 Please make sure you build a production version before submitting a pull request.
 128
 129 Installation
 130 ------------------
 131
 132 ```bash
 133 npm install file-saver --save
 134 bower install file-saver
 135 ```