version bump 0.11.19: browser writeFile

- IE6-9 ActiveX + VBScript shim
- `writeFile` supported in browser
- `oldie` demo for IE write strategies

Author: SheetJSDev

.spelling

@@ -36,7 +36,6 @@ CDNjs
 CommonJS
 Ethercalc
 ExtendScript
-FileSaver
 IndexedDB
 JavaScriptCore
 LocalStorage
@@ -58,6 +57,7 @@ webpack
 weex
 
 # Other terms
+ActiveX
 APIs
 ArrayBuffer
 Base64
@@ -66,6 +66,7 @@ JS
 NoSQL
 README
 UTF-16
+VBScript
 XHR
 XMLHttpRequest
 bundler

CHANGELOG.md

@@ -4,6 +4,10 @@ This log is intended to keep track of backwards-incompatible changes, including
 but not limited to API changes and file location changes.  Minor behavioral
 changes may not be included if they are not expected to break existing code.
 
+## 0.11.19
+
+* Error on empty workbook
+
 ## 0.11.16 (2017-12-30)
 
 * XLS ANSI/CP separation

README.md

@@ -215,6 +215,7 @@ The [`demos` directory](demos/) includes sample projects for:
 - [`Headless Browsers`](demos/headless/)
 - [`canvas-datagrid`](demos/datagrid/)
 - [`Swift JSC and other engines`](demos/altjs/)
+- [`internet explorer`](demos/oldie/)
 
 ### Optional Modules
 
@@ -339,7 +340,7 @@ var worksheet = XLSX.read(htmlstr, {type:'string'});
   <summary><b>Browser download file (ajax)</b> (click to show)</summary>
 
 Note: for a more complete example that works in older browsers, check the demo
-at <http://oss.sheetjs.com/js-xlsx/ajax.html>).  The <demos/xhr/> directory also
+at <http://oss.sheetjs.com/js-xlsx/ajax.html>).  The [`xhr` demo](demos/xhr/)
 includes more examples with `XMLHttpRequest` and `fetch`.
 
 ```js
@@ -414,6 +415,8 @@ input_dom_element.addEventListener('change', handleFile, false);
 
 </details>
 
+More specialized cases, including mobile app file processing, are covered in the
+[included demos](demos/)
 
 ### Parsing Examples
 
@@ -590,8 +593,7 @@ Assuming `workbook` is a workbook object:
 <details>
   <summary><b>nodejs write a file</b> (click to show)</summary>
 
-`writeFile` is only available in server environments. Browsers have no API for
-writing arbitrary files given a path, so another strategy must be used.
+`XLSX.writeFile` uses `fs.writeFileSync` in server environments:
 
 ```js
 if(typeof require !== 'undefined') XLSX = require('xlsx');
@@ -603,7 +605,7 @@ XLSX.writeFile(workbook, 'out.xlsb');
 </details>
 
 <details>
-  <summary><b>Browser add to web page</b> (click to show)</summary>
+  <summary><b>Browser add TABLE element to page</b> (click to show)</summary>
 
 The `sheet_to_html` utility function generates HTML code that can be added to
 any DOM element.
@@ -614,29 +616,10 @@ var container = document.getElementById('tableau');
 container.innerHTML = XLSX.utils.sheet_to_html(worksheet);
 ```
 
-
-</details>
-
-<details>
-  <summary><b>Browser save file</b> (click to show)</summary>
-
-Note: browser generates binary blob and forces a "download" to client.  This
-example uses [FileSaver](https://github.com/eligrey/FileSaver.js/):
-
-```js
-/* bookType can be any supported output type */
-var wopts = { bookType:'xlsx', bookSST:false, type:'array' };
-
-var wbout = XLSX.write(workbook,wopts);
-
-/* the saveAs call downloads a file on the local machine */
-saveAs(new Blob([wbout],{type:"application/octet-stream"}), "test.xlsx");
-```
-
 </details>
 
 <details>
-  <summary><b>Browser upload to server</b> (click to show)</summary>
+  <summary><b>Browser upload file (ajax)</b> (click to show)</summary>
 
 A complete example using XHR is [included in the XHR demo](demos/xhr/), along
 with examples for fetch and wrapper libraries.  This example assumes the server
@@ -658,6 +641,65 @@ req.send(formdata);
 
 </details>
 
+<details>
+  <summary><b>Browser save file</b> (click to show)</summary>
+
+`XLSX.writeFile` wraps a few techniques for triggering a file save:
+
+- `URL` browser API creates an object URL for the file, which the library uses
+  by creating a link and forcing a click. It is supported in modern browsers.
+- `msSaveBlob` is an IE10+ API for triggering a file save.
+- `IE_FileSave` uses VBScript and ActiveX to write a file in IE6+ for Windows
+  XP and Windows 7.  The shim must be included in the containing HTML page.
+
+There is no standard way to determine if the actual file has been downloaded.
+
+```js
+/* output format determined by filename */
+XLSX.writeFile(workbook, 'out.xlsb');
+/* at this point, out.xlsb will have been downloaded */
+```
+
+</details>
+
+<details>
+  <summary><b>Browser save file (compatibility)</b> (click to show)</summary>
+
+`XLSX.writeFile` techniques work for most modern browsers as well as older IE.
+For much older browsers, there are workarounds implemented by wrapper libraries.
+
+[`FileSaver.js`](https://github.com/eligrey/FileSaver.js/) implements `saveAs`.
+Note: `XLSX.writeFile` will automatically call `saveAs` if available.
+
+```js
+/* bookType can be any supported output type */
+var wopts = { bookType:'xlsx', bookSST:false, type:'array' };
+
+var wbout = XLSX.write(workbook,wopts);
+
+/* the saveAs call downloads a file on the local machine */
+saveAs(new Blob([wbout],{type:"application/octet-stream"}), "test.xlsx");
+```
+
+[`Downloadify`](https://github.com/dcneiner/downloadify) uses a Flash SWF button
+to generate local files, suitable for environments where ActiveX is unavailable:
+
+```js
+Downloadify.create(id,{
+	/* other options are required! read the downloadify docs for more info */
+	filename: "test.xlsx",
+	data: function() { return XLSX.write(wb, {bookType:"xlsx", type:'base64'}); },
+	append: false,
+	dataType: 'base64'
+});
+```
+
+The [`oldie` demo](demos/oldie/) shows an IE-compatible fallback scenario.
+
+</details>
+
+The [included demos](demos/) cover mobile apps and other special deployments.
+
 ### Writing Examples
 
 - <http://sheetjs.com/demos/table.html> exporting an HTML table
@@ -705,7 +747,8 @@ Parse options are described in the [Parsing Options](#parsing-options) section.
 
 `XLSX.write(wb, write_opts)` attempts to write the workbook `wb`
 
-`XLSX.writeFile(wb, filename, write_opts)` attempts to write `wb` to `filename`
+`XLSX.writeFile(wb, filename, write_opts)` attempts to write `wb` to `filename`.
+In browser-based environments, it will attempt to force a client-side download.
 
 `XLSX.writeFileAsync(filename, wb, o, cb)` attempts to write `wb` to `filename`.
 If `o` is omitted, the writer will use the third argument as the callback.
@@ -2015,6 +2058,7 @@ produces HTML output.  The function takes an options argument:
 
 | Option Name |  Default | Description                                         |
 | :---------- | :------: | :-------------------------------------------------- |
+|`id`         |          | Specify the `id` attribute for the `TABLE` element  |
 |`editable`   |  false   | If true, set `contenteditable="true"` for every TD  |
 |`header`     |          | Override header (default `html body`)               |
 |`footer`     |          | Override footer (default `/body /html`)             |

bits/01_version.js

@@ -1 +1 @@
-XLSX.version = '0.11.18';
+XLSX.version = '0.11.19';

bits/05_buf.js

@@ -19,11 +19,16 @@ function s2ab(s/*:string*/) {
 	return buf;
 }
 
-function arr2str(data/*:any*/)/*:string*/ {
+function a2s(data/*:any*/)/*:string*/ {
 	if(Array.isArray(data)) return data.map(_chr).join("");
 	var o/*:Array<string>*/ = []; for(var i = 0; i < data.length; ++i) o[i] = _chr(data[i]); return o.join("");
 }
 
+function a2u(data/*:Array<number>*/)/*:Uint8Array*/ {
+	if(typeof Uint8Array === 'undefined') throw new Error("Unsupported");
+	return new Uint8Array(data);
+}
+
 function ab2a(data/*:ArrayBuffer|Uint8Array*/)/*:Array<number>*/ {
 	if(typeof ArrayBuffer == 'undefined') throw new Error("Unsupported");
 	if(data instanceof ArrayBuffer) return ab2a(new Uint8Array(data));

bits/19_fsutils.js

@@ -0,0 +1,37 @@
+var _fs;
+if(typeof require !== 'undefined') try { _fs = require('fs'); } catch(e) {}
+
+/* normalize data for blob ctor */
+function blobify(data) {
+	if(typeof data === "string") return s2ab(data);
+	if(Array.isArray(data)) return a2u(data);
+	return data;
+}
+/* write or download file */
+function write_dl(fname/*:string*/, payload/*:any*/, enc/*:?string*/) {
+	/*global IE_SaveFile, Blob, navigator, saveAs, URL, document */
+	if(typeof _fs !== 'undefined' && _fs.writeFileSync) return enc ? _fs.writeFileSync(fname, payload, enc) : _fs.writeFileSync(fname, payload);
+	var data = (enc == "utf8") ? utf8write(payload) : payload;
+	/*:: declare var IE_SaveFile: any; */
+	if(typeof IE_SaveFile !== 'undefined') return IE_SaveFile(data, fname);
+	if(typeof Blob !== 'undefined') {
+		var blob = new Blob([blobify(data)], {type:"application/octet-stream"});
+		/*:: declare var navigator: any; */
+		if(typeof navigator !== 'undefined' && navigator.msSaveBlob) return navigator.msSaveBlob(blob, fname);
+		/*:: declare var saveAs: any; */
+		if(typeof saveAs !== 'undefined') return saveAs(blob, fname);
+		if(typeof URL !== 'undefined' && typeof document !== 'undefined' && document.createElement && URL.createObjectURL) {
+			var a = document.createElement("a");
+			if(a.download != null) {
+				var url = URL.createObjectURL(blob);
+				/*:: if(document.body == null) throw new Error("unreachable"); */
+				a.download = fname; a.href = url; document.body.appendChild(a); a.click();
+				/*:: if(document.body == null) throw new Error("unreachable"); */ document.body.removeChild(a);
+				if(URL.revokeObjectURL && typeof setTimeout !== 'undefined') setTimeout(function() { URL.revokeObjectURL(url); }, 60000);
+				return url;
+			}
+		}
+	}
+	throw new Error("cannot initiate download");
+}
+

bits/21_ziputils.js

@@ -51,14 +51,13 @@ function getzipstr(zip, file/*:string*/, safe/*:?boolean*/)/*:?string*/ {
 	try { return getzipstr(zip, file); } catch(e) { return null; }
 }
 
-var _fs, jszip;
+var jszip;
 /*:: declare var JSZip:any; */
 /*global JSZip:true */
 if(typeof JSZip !== 'undefined') jszip = JSZip;
-if (typeof exports !== 'undefined') {
-	if (typeof module !== 'undefined' && module.exports) {
+if(typeof exports !== 'undefined') {
+	if(typeof module !== 'undefined' && module.exports) {
 		if(typeof jszip === 'undefined') jszip = require('./jszip.js');
-		try { _fs = require('fs'); } catch(e) { }
 	}
 }
 

bits/71_wbcommon.js

@@ -132,6 +132,7 @@ function check_wb_names(N) {
 }
 function check_wb(wb) {
 	if(!wb || !wb.SheetNames || !wb.Sheets) throw new Error("Invalid Workbook");
+	if(!wb.SheetNames.length) throw new Error("Workbook is empty");
 	check_wb_names(wb.SheetNames);
 	/* TODO: validate workbook */
 }

bits/75_xlml.js

@@ -833,7 +833,7 @@ function parse_xlml(data/*:RawBytes|string*/, opts)/*:Workbook*/ {
 	switch(opts.type||"base64") {
 		case "base64": return parse_xlml_xml(Base64.decode(data), opts);
 		case "binary": case "buffer": case "file": return parse_xlml_xml(data, opts);
-		case "array": return parse_xlml_xml(arr2str(data), opts);
+		case "array": return parse_xlml_xml(a2s(data), opts);
 	}
 	/*:: throw new Error("unsupported type " + opts.type); */
 }

bits/79_html.js

@@ -84,9 +84,9 @@ var HTML_ = (function() {
 		var preamble = "<tr>";
 		return preamble + oo.join("") + "</tr>";
 	}
-	function make_html_preamble(/*::ws:Worksheet, R:Range, o:Sheet2HTMLOpts*/)/*:string*/ {
+	function make_html_preamble(ws/*:Worksheet*/, R/*:Range*/, o/*:Sheet2HTMLOpts*/)/*:string*/ {
 		var out/*:Array<string>*/ = [];
-		return out.join("") + '<table>';
+		return out.join("") + '<table' + (o && o.id ? ' id="' + o.id + '"' : "") + '>';
 	}
 	var _BEGIN = '<html><head><meta charset="utf-8"/><title>SheetJS Table Export</title></head><body>';
 	var _END = '</body></html>';