Skip to content
This repository
Browse code

issue #23 feedback

* use type instead of responseType
* deprecate generate({base64:true})
* improve documentation
  • Loading branch information...
commit c415e7f3ad4fd93c688e182215718f735f327c25 1 parent b7bc4bf
David Duponchel dduponchel authored
2  examples/download-zip-file.html
@@ -19,7 +19,7 @@
19 19 var blobLink = document.getElementById('blob');
20 20 try {
21 21 blobLink.download = "hello.zip";
22   - blobLink.href = window.URL.createObjectURL(zip.generate({responseType:"blob"}));
  22 + blobLink.href = window.URL.createObjectURL(zip.generate({type:"blob"}));
23 23 } catch(e) {
24 24 blobLink.innerHTML += " (not supported on this browser)";
25 25 }
34 index.html
@@ -233,7 +233,7 @@
233 233 <h4>Other solution-ish: Blob URL</h4>
234 234 <p>With <a href="http://caniuse.com/bloburls">some recent browsers</a> come a new way to download Blobs (a zip file for example) : blob urls. The <a href="http://updates.html5rocks.com/2011/08/Downloading-resources-in-HTML5-a-download">download attribute on &lt;a&gt;</a> allows you to give the name of the file. Blob urls start to be widely supported but this attribute is currently only supported in Chrome. See <a href="examples/download-zip-file.html">the example</a>.</p>
235 235 <pre class="example">
236   -var blob = zip.generate({responseType:"blob"});
  236 +var blob = zip.generate({type:"blob"});
237 237 myLink.href = window.URL.createObjectURL(blob);
238 238 myLink.download = "myFile.zip";</pre>
239 239
@@ -245,7 +245,7 @@
245 245 <p>
246 246 When doing an ajax call to get the binary data, the browser will try to interpret the binary as text, corrupting it. The solution is to <a href="https://developer.mozilla.org/En/XMLHttpRequest/Using_XMLHttpRequest#Receiving_binary_data_in_older_browsers">set the mimetype to 'text/plain; charset=x-user-defined'</a>. This solution works well in all browsers but IE. If you need IE support, please see what is done in the file test/index.html.
247 247 </p>
248   - <p>An other solution is to use a modern browser (supporting <a href="http://caniuse.com/xhr2">xhr2</a>) : setting <code>xhr.responseType = 'arraybuffer';</code> will do the trick, JSZip supports ArrayBuffers. Please see <a href="examples/get-binary-files-xhr2.html">the example</a>.
  248 + <p>An other solution is to use a modern browser (supporting <a href="http://caniuse.com/xhr2">xhr2</a>) : setting <code>xhr.type = 'arraybuffer';</code> will do the trick, JSZip supports ArrayBuffers. Please see <a href="examples/get-binary-files-xhr2.html">the example</a>.
249 249
250 250 <h3>Reading a local zip file (File API)</h3>
251 251 <p>
@@ -299,8 +299,8 @@ <h4 id="doc_file_name">file(name)</h4>
299 299 </li>
300 300 <li><code>asText()</code>, string, the content as an utf8 string (utf8 encoded if necessary).</li>
301 301 <li><code>asBinary()</code>, string, the content as binary (utf8 decoded if necessary).</li>
302   - <li><code>asArrayBuffer()</code>, ArrayBuffer, need a compatible browser.</li>
303   - <li><code>asUint8Array()</code>, Uint8Array, need a compatible browser.</li>
  302 + <li><code>asArrayBuffer()</code>, ArrayBuffer, need a <a href="#jszip_support">compatible browser</a>.</li>
  303 + <li><code>asUint8Array()</code>, Uint8Array, need a <a href="#jszip_support">compatible browser</a>.</li>
304 304 </ul>
305 305 </dd>
306 306 </dl>
@@ -317,7 +317,7 @@ <h4 id="doc_file_name">file(name)</h4>
317 317 zip.file("amount.txt").data // "&#226;&#130;&#172;15" <!-- something like that -->
318 318 zip.file("amount.txt").asText() // "&euro;15"
319 319 zip.file("amount.txt").asArrayBuffer() // an ArrayBuffer containing &euro;15
320   -zip.file("amount.txt").asnt8ArrayArrayBuffer() // an Uint8Array containing &euro;15
  320 +zip.file("amount.txt").asUint8Array() // an Uint8Array containing &euro;15
321 321 </pre>
322 322
323 323 <h4 id="doc_file_regex">file(regex)</h4>
@@ -449,13 +449,14 @@ <h4 id="doc_generate_options">generate(options)</h4>
449 449 <dt>Parameters : </dt>
450 450 <dd><code>options</code> (Object) the options to generate the zip file :
451 451 <ul>
452   - <li><code>base64</code> (boolean) <code>false</code> to get the result as a raw byte string.
  452 + <li><code>base64</code> (boolean) <strong>deprecated</strong>, use "type" instead. <code>false</code> to get the result as a raw byte string.
453 453 Default : <code>true</code>, encode as base64.</li>
454 454 <li><code>compression</code> (String) the compression method to use. <code>"STORE"</code> (no compression) by default,
455 455 you can use <code>"DEFLATE"</code> (include the file jszip-deflate.js) or write your own.</li>
456   - <li><code>responseType</code> (String) the type of zip to return. The possible values are :
  456 + <li><code>type</code> (String) the type of zip to return. The possible values are :
457 457 <ul>
458   - <li><code>string</code> (default) : the result will be a string in "binary" form, or in a "base64" form (see the base64 option).</li>
  458 + <li><code>base64</code> (default) : the result will be a string, the binary in a base64 form.</li>
  459 + <li><code>string</code> : the result will be a string in "binary" form, 1 byte per char.</li>
459 460 <li><code>uint8array</code> : the result will be a Uint8Array containing the zip. This requires a compatible browser.</li>
460 461 <li><code>arraybuffer</code> : the result will be a ArrayBuffer containing the zip. This requires a compatible browser.</li>
461 462 <li><code>blob</code> : the result will be a Blob containing the zip. This requires a compatible browser.</li>
@@ -466,13 +467,14 @@ <h4 id="doc_generate_options">generate(options)</h4>
466 467 <dt>Returns : </dt>
467 468 <dd>The generated zip file.</dd>
468 469 </dl>
469   - HTML5 note : when using responseType = "uint8array", "arraybuffer" or "blob", be sure to check if the browser supports it. This method will throw an exception otherwise.
  470 + HTML5 note : when using type = "uint8array", "arraybuffer" or "blob", be sure to check if the browser supports it (you can use <a href="#jszip_support"><code>JSZip.support</code></a>).
  471 + This method will throw an exception otherwise.
470 472 <pre class="example">
471 473 content = zip.generate();
472 474 location.href="data:application/zip;base64,"+content;</pre>
473 475
474 476 <pre class="example">
475   -content = zip.generate({base64:false});
  477 +content = zip.generate({type:"string"});
476 478 for (var c = 0; c &lt; content.length; c++)
477 479 {
478 480 console.log(content.charCodeAt(c));
@@ -535,6 +537,18 @@ <h4 id="doc_filter_predicate">filter(predicate)</h4>
535 537 return true/false;
536 538 });</pre>
537 539
  540 + <h4 id="jszip_support">JSZip.support</h4>
  541 + <p>
  542 + If the browser supports them, JSZip can take advantage of some new features : ArrayBuffer, Blob, Uint8Array.
  543 + To know if JSZip can use them, you can check the JSZip.support object. It contains the following
  544 + properties :
  545 + <ul>
  546 + <li><code>arraybuffer</code> : true if JSZip can read and generate ArrayBuffer, false otherwise.</li>
  547 + <li><code>uint8array</code> : true if JSZip can read and generate Uint8Array, false otherwise.</li>
  548 + <li><code>blob</code> : true if JSZip can read and generate Blob, false otherwise.</li>
  549 + </ul>
  550 + </p>
  551 +
538 552 <h3 id="zip_load_limits">Loading zip files, limitations</h3>
539 553 <p>
540 554 The first limitation comes from the limited subset of supported zip features.
29 jszip.js
@@ -487,9 +487,9 @@ JSZip.prototype = (function ()
487 487 /**
488 488 * Generate the complete zip file
489 489 * @param {Object} options the options to generate the zip file :
490   - * - base64, true to generate base64.
  490 + * - base64, (deprecated, use type instead) true to generate base64.
491 491 * - compression, "STORE" by default.
492   - * - responseType, "string" by default.
  492 + * - type, "base64" by default. Values are : string, base64, uint8array, arraybuffer, blob.
493 493 * @return {String|Uint8Array|ArrayBuffer|Blob} the zip file
494 494 */
495 495 generate : function(options)
@@ -497,7 +497,7 @@ JSZip.prototype = (function ()
497 497 options = extend(options || {}, {
498 498 base64 : true,
499 499 compression : "STORE",
500   - responseType : "string"
  500 + type : "base64"
501 501 });
502 502 var compression = options.compression.toUpperCase();
503 503
@@ -570,7 +570,7 @@ JSZip.prototype = (function ()
570 570 var zip = fileData + dirData + dirEnd;
571 571
572 572
573   - switch(options.responseType.toLowerCase())
  573 + switch(options.type.toLowerCase())
574 574 {
575 575 case "uint8array" :
576 576 return JSZip.utils.string2Uint8Array(zip);
@@ -578,8 +578,10 @@ JSZip.prototype = (function ()
578 578 return JSZip.utils.string2Uint8Array(zip).buffer;
579 579 case "blob" :
580 580 return JSZip.utils.string2Blob(zip);
581   - default : // case "string" :
  581 + case "base64" :
582 582 return (options.base64) ? JSZipBase64.encode(zip) : zip;
  583 + default : // case "string" :
  584 + return zip;
583 585 }
584 586 },
585 587
@@ -786,20 +788,23 @@ JSZip.compressions = {
786 788 * List features that require a modern browser, and if the current browser support them.
787 789 */
788 790 JSZip.support = {
  791 + // contains true if JSZip can read/generate ArrayBuffer, false otherwise.
789 792 arraybuffer : (function(){
790 793 return typeof ArrayBuffer !== "undefined" && typeof Uint8Array !== "undefined";
791 794 })(),
  795 + // contains true if JSZip can read/generate Uint8Array, false otherwise.
792 796 uint8array : (function(){
793 797 return typeof Uint8Array !== "undefined";
794 798 })(),
795   - // the spec started with BlobBuilder then replaced it with a construtor for Blob.
796   - // Result : we have browsers that :
797   - // * know the BlobBuilder (but with prefix)
798   - // * know the Blob constructor
799   - // * know about Blob but not about how to build them
800   - // About the "=== 0" test : if given the wrong type, it may be converted to a string.
801   - // Instead of an empty content, we will get "[object Uint8Array]" for example.
  799 + // contains true if JSZip can read/generate Blob, false otherwise.
802 800 blob : (function(){
  801 + // the spec started with BlobBuilder then replaced it with a construtor for Blob.
  802 + // Result : we have browsers that :
  803 + // * know the BlobBuilder (but with prefix)
  804 + // * know the Blob constructor
  805 + // * know about Blob but not about how to build them
  806 + // About the "=== 0" test : if given the wrong type, it may be converted to a string.
  807 + // Instead of an empty content, we will get "[object Uint8Array]" for example.
803 808 if (typeof ArrayBuffer === "undefined")
804 809 {
805 810 return false;
49 test/index.html
@@ -111,7 +111,7 @@
111 111 * bytes -> JSZip -> bytes
112 112 */
113 113 function reload(bytesStream) {
114   - return new JSZip(bytesStream, {checkCRC32:true}).generate({base64:false});
  114 + return new JSZip(bytesStream, {checkCRC32:true}).generate({type:"string"});
115 115 }
116 116
117 117 // cache for files
@@ -224,7 +224,7 @@
224 224 testZipFile("Zip text file with UTF-8 characters", "ref/utf8.zip", function(expected) {
225 225 var zip = new JSZip();
226 226 zip.file("amount.txt", "€15\n");
227   - var actual = zip.generate({base64:false});
  227 + var actual = zip.generate({type:"string"});
228 228
229 229 ok(similar(actual, expected, 18) , "Generated ZIP matches reference ZIP");
230 230 equals(reload(actual), actual, "Generated ZIP can be parsed");
@@ -234,7 +234,7 @@
234 234 testZipFile("Zip text file with UTF-8 characters in filename", "ref/utf8_in_name.zip", function(expected) {
235 235 var zip = new JSZip();
236 236 zip.file("€15.txt", "€15\n");
237   - var actual = zip.generate({base64:false});
  237 + var actual = zip.generate({type:"string"});
238 238
239 239 ok(similar(actual, expected, 18) , "Generated ZIP matches reference ZIP");
240 240 equals(reload(actual), actual, "Generated ZIP can be parsed");
@@ -537,7 +537,7 @@
537 537 });
538 538 }
539 539
540   - testZipFile("generate : base64:false", "ref/text.zip", function(expected) {
  540 + testZipFile("generate : base64:false. Deprecated, but it still works", "ref/text.zip", function(expected) {
541 541 var zip = new JSZip();
542 542 zip.file("Hello.txt", "Hello World\n");
543 543 var actual = zip.generate({base64:false});
@@ -545,18 +545,27 @@
545 545 ok(similar(actual, expected, 18) , "Generated ZIP matches reference ZIP");
546 546 });
547 547
548   - testZipFile("generate : responseType:string,base64:false", "ref/text.zip", function(expected) {
  548 + testZipFile("generate : base64:true. Deprecated, but it still works", "ref/text.zip", function(expected) {
  549 + var zip = new JSZip();
  550 + zip.file("Hello.txt", "Hello World\n");
  551 + var content = zip.generate({base64:true});
  552 + var actual = JSZipBase64.decode(content);
  553 +
  554 + ok(similar(actual, expected, 18) , "Generated ZIP matches reference ZIP");
  555 + });
  556 +
  557 + testZipFile("generate : type:string", "ref/text.zip", function(expected) {
549 558 var zip = new JSZip();
550 559 zip.file("Hello.txt", "Hello World\n");
551   - var actual = zip.generate({responseType:"string",base64:false});
  560 + var actual = zip.generate({type:"string"});
552 561
553 562 ok(similar(actual, expected, 18) , "Generated ZIP matches reference ZIP");
554 563 });
555 564
556   - testZipFile("generate : responseType:string‚base64:true", "ref/text.zip", function(expected) {
  565 + testZipFile("generate : type:base64", "ref/text.zip", function(expected) {
557 566 var zip = new JSZip();
558 567 zip.file("Hello.txt", "Hello World\n");
559   - var content = zip.generate({responseType:"string",base64:true});
  568 + var content = zip.generate({type:"base64"});
560 569
561 570 var actual = JSZipBase64.decode(content);
562 571
@@ -564,10 +573,10 @@
564 573 });
565 574
566 575 if (JSZip.support.uint8array) {
567   - testZipFile("generate : responseType:uint8array", "ref/text.zip", function(expected) {
  576 + testZipFile("generate : type:uint8array", "ref/text.zip", function(expected) {
568 577 var zip = new JSZip();
569 578 zip.file("Hello.txt", "Hello World\n");
570   - var array = zip.generate({responseType:"uint8array"});
  579 + var array = zip.generate({type:"uint8array"});
571 580 ok(array instanceof Uint8Array, "The result is a instance of Uint8Array");
572 581 equals(array.length, expected.length);
573 582
@@ -576,11 +585,11 @@
576 585 ok(similar(actual, expected, 18) , "Generated ZIP matches reference ZIP");
577 586 });
578 587 } else {
579   - testZipFile("generate : responseType:uint8array", "ref/text.zip", function(expected) {
  588 + testZipFile("generate : type:uint8array", "ref/text.zip", function(expected) {
580 589 var zip = new JSZip();
581 590 zip.file("Hello.txt", "Hello World\n");
582 591 try {
583   - var blob = zip.generate({responseType:"uint8array"});
  592 + var blob = zip.generate({type:"uint8array"});
584 593 ok(false, "Uint8Array is not supported, but no exception thrown");
585 594 } catch(e) {
586 595 ok(e.message.match("not supported by this browser"), "the error message is useful");
@@ -589,10 +598,10 @@
589 598 }
590 599
591 600 if (JSZip.support.arraybuffer) {
592   - testZipFile("generate : responseType:arraybuffer", "ref/text.zip", function(expected) {
  601 + testZipFile("generate : type:arraybuffer", "ref/text.zip", function(expected) {
593 602 var zip = new JSZip();
594 603 zip.file("Hello.txt", "Hello World\n");
595   - var buffer = zip.generate({responseType:"arraybuffer"});
  604 + var buffer = zip.generate({type:"arraybuffer"});
596 605 ok(buffer instanceof ArrayBuffer, "The result is a instance of ArrayBuffer");
597 606
598 607 var actual = String.fromCharCode.apply(null, new Uint8Array(buffer));
@@ -600,11 +609,11 @@
600 609 ok(similar(actual, expected, 18) , "Generated ZIP matches reference ZIP");
601 610 });
602 611 } else {
603   - testZipFile("generate : responseType:arraybuffer", "ref/text.zip", function(expected) {
  612 + testZipFile("generate : type:arraybuffer", "ref/text.zip", function(expected) {
604 613 var zip = new JSZip();
605 614 zip.file("Hello.txt", "Hello World\n");
606 615 try {
607   - var blob = zip.generate({responseType:"arraybuffer"});
  616 + var blob = zip.generate({type:"arraybuffer"});
608 617 ok(false, "ArrayBuffer is not supported, but no exception thrown");
609 618 } catch(e) {
610 619 ok(e.message.match("not supported by this browser"), "the error message is useful");
@@ -613,20 +622,20 @@
613 622 }
614 623
615 624 if (JSZip.support.blob) {
616   - testZipFile("generate : responseType:blob", "ref/text.zip", function(expected) {
  625 + testZipFile("generate : type:blob", "ref/text.zip", function(expected) {
617 626 var zip = new JSZip();
618 627 zip.file("Hello.txt", "Hello World\n");
619   - var blob = zip.generate({responseType:"blob"});
  628 + var blob = zip.generate({type:"blob"});
620 629 ok(blob instanceof Blob, "The result is a instance of Blob");
621 630 equals(blob.type, "application/zip");
622 631 equals(blob.size, expected.length);
623 632 });
624 633 } else {
625   - testZipFile("generate : responseType:blob", "ref/text.zip", function(expected) {
  634 + testZipFile("generate : type:blob", "ref/text.zip", function(expected) {
626 635 var zip = new JSZip();
627 636 zip.file("Hello.txt", "Hello World\n");
628 637 try {
629   - var blob = zip.generate({responseType:"blob"});
  638 + var blob = zip.generate({type:"blob"});
630 639 ok(false, "Blob is not supported, but no exception thrown");
631 640 } catch(e) {
632 641 ok(e.message.match("not supported by this browser"), "the error message is useful");

0 comments on commit c415e7f

Please sign in to comment.
Something went wrong with that request. Please try again.