Permalink
Browse files

issue #23 feedback

* use type instead of responseType
* deprecate generate({base64:true})
* improve documentation
  • Loading branch information...
1 parent b7bc4bf commit c415e7f3ad4fd93c688e182215718f735f327c25 @dduponchel dduponchel committed Jan 4, 2013
Showing with 71 additions and 43 deletions.
  1. +1 −1 examples/download-zip-file.html
  2. +24 −10 index.html
  3. +17 −12 jszip.js
  4. +29 −20 test/index.html
@@ -19,7 +19,7 @@
var blobLink = document.getElementById('blob');
try {
blobLink.download = "hello.zip";
- blobLink.href = window.URL.createObjectURL(zip.generate({responseType:"blob"}));
+ blobLink.href = window.URL.createObjectURL(zip.generate({type:"blob"}));
} catch(e) {
blobLink.innerHTML += " (not supported on this browser)";
}
View
@@ -233,7 +233,7 @@
<h4>Other solution-ish: Blob URL</h4>
<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>
<pre class="example">
-var blob = zip.generate({responseType:"blob"});
+var blob = zip.generate({type:"blob"});
myLink.href = window.URL.createObjectURL(blob);
myLink.download = "myFile.zip";</pre>
@@ -245,7 +245,7 @@
<p>
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.
</p>
- <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>.
+ <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>.
<h3>Reading a local zip file (File API)</h3>
<p>
@@ -299,8 +299,8 @@ <h4 id="doc_file_name">file(name)</h4>
</li>
<li><code>asText()</code>, string, the content as an utf8 string (utf8 encoded if necessary).</li>
<li><code>asBinary()</code>, string, the content as binary (utf8 decoded if necessary).</li>
- <li><code>asArrayBuffer()</code>, ArrayBuffer, need a compatible browser.</li>
- <li><code>asUint8Array()</code>, Uint8Array, need a compatible browser.</li>
+ <li><code>asArrayBuffer()</code>, ArrayBuffer, need a <a href="#jszip_support">compatible browser</a>.</li>
+ <li><code>asUint8Array()</code>, Uint8Array, need a <a href="#jszip_support">compatible browser</a>.</li>
</ul>
</dd>
</dl>
@@ -317,7 +317,7 @@ <h4 id="doc_file_name">file(name)</h4>
zip.file("amount.txt").data // "&#226;&#130;&#172;15" <!-- something like that -->
zip.file("amount.txt").asText() // "&euro;15"
zip.file("amount.txt").asArrayBuffer() // an ArrayBuffer containing &euro;15
-zip.file("amount.txt").asnt8ArrayArrayBuffer() // an Uint8Array containing &euro;15
+zip.file("amount.txt").asUint8Array() // an Uint8Array containing &euro;15
</pre>
<h4 id="doc_file_regex">file(regex)</h4>
@@ -449,13 +449,14 @@ <h4 id="doc_generate_options">generate(options)</h4>
<dt>Parameters : </dt>
<dd><code>options</code> (Object) the options to generate the zip file :
<ul>
- <li><code>base64</code> (boolean) <code>false</code> to get the result as a raw byte string.
+ <li><code>base64</code> (boolean) <strong>deprecated</strong>, use "type" instead. <code>false</code> to get the result as a raw byte string.
Default : <code>true</code>, encode as base64.</li>
<li><code>compression</code> (String) the compression method to use. <code>"STORE"</code> (no compression) by default,
you can use <code>"DEFLATE"</code> (include the file jszip-deflate.js) or write your own.</li>
- <li><code>responseType</code> (String) the type of zip to return. The possible values are :
+ <li><code>type</code> (String) the type of zip to return. The possible values are :
<ul>
- <li><code>string</code> (default) : the result will be a string in "binary" form, or in a "base64" form (see the base64 option).</li>
+ <li><code>base64</code> (default) : the result will be a string, the binary in a base64 form.</li>
+ <li><code>string</code> : the result will be a string in "binary" form, 1 byte per char.</li>
<li><code>uint8array</code> : the result will be a Uint8Array containing the zip. This requires a compatible browser.</li>
<li><code>arraybuffer</code> : the result will be a ArrayBuffer containing the zip. This requires a compatible browser.</li>
<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>
<dt>Returns : </dt>
<dd>The generated zip file.</dd>
</dl>
- 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.
+ 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>).
+ This method will throw an exception otherwise.
<pre class="example">
content = zip.generate();
location.href="data:application/zip;base64,"+content;</pre>
<pre class="example">
-content = zip.generate({base64:false});
+content = zip.generate({type:"string"});
for (var c = 0; c &lt; content.length; c++)
{
console.log(content.charCodeAt(c));
@@ -535,6 +537,18 @@ <h4 id="doc_filter_predicate">filter(predicate)</h4>
return true/false;
});</pre>
+ <h4 id="jszip_support">JSZip.support</h4>
+ <p>
+ If the browser supports them, JSZip can take advantage of some new features : ArrayBuffer, Blob, Uint8Array.
+ To know if JSZip can use them, you can check the JSZip.support object. It contains the following
+ properties :
+ <ul>
+ <li><code>arraybuffer</code> : true if JSZip can read and generate ArrayBuffer, false otherwise.</li>
+ <li><code>uint8array</code> : true if JSZip can read and generate Uint8Array, false otherwise.</li>
+ <li><code>blob</code> : true if JSZip can read and generate Blob, false otherwise.</li>
+ </ul>
+ </p>
+
<h3 id="zip_load_limits">Loading zip files, limitations</h3>
<p>
The first limitation comes from the limited subset of supported zip features.
View
@@ -487,17 +487,17 @@ JSZip.prototype = (function ()
/**
* Generate the complete zip file
* @param {Object} options the options to generate the zip file :
- * - base64, true to generate base64.
+ * - base64, (deprecated, use type instead) true to generate base64.
* - compression, "STORE" by default.
- * - responseType, "string" by default.
+ * - type, "base64" by default. Values are : string, base64, uint8array, arraybuffer, blob.
* @return {String|Uint8Array|ArrayBuffer|Blob} the zip file
*/
generate : function(options)
{
options = extend(options || {}, {
base64 : true,
compression : "STORE",
- responseType : "string"
+ type : "base64"
});
var compression = options.compression.toUpperCase();
@@ -570,16 +570,18 @@ JSZip.prototype = (function ()
var zip = fileData + dirData + dirEnd;
- switch(options.responseType.toLowerCase())
+ switch(options.type.toLowerCase())
{
case "uint8array" :
return JSZip.utils.string2Uint8Array(zip);
case "arraybuffer" :
return JSZip.utils.string2Uint8Array(zip).buffer;
case "blob" :
return JSZip.utils.string2Blob(zip);
- default : // case "string" :
+ case "base64" :
return (options.base64) ? JSZipBase64.encode(zip) : zip;
+ default : // case "string" :
+ return zip;
}
},
@@ -786,20 +788,23 @@ JSZip.compressions = {
* List features that require a modern browser, and if the current browser support them.
*/
JSZip.support = {
+ // contains true if JSZip can read/generate ArrayBuffer, false otherwise.
arraybuffer : (function(){
return typeof ArrayBuffer !== "undefined" && typeof Uint8Array !== "undefined";
})(),
+ // contains true if JSZip can read/generate Uint8Array, false otherwise.
uint8array : (function(){
return typeof Uint8Array !== "undefined";
})(),
- // the spec started with BlobBuilder then replaced it with a construtor for Blob.
- // Result : we have browsers that :
- // * know the BlobBuilder (but with prefix)
- // * know the Blob constructor
- // * know about Blob but not about how to build them
- // About the "=== 0" test : if given the wrong type, it may be converted to a string.
- // Instead of an empty content, we will get "[object Uint8Array]" for example.
+ // contains true if JSZip can read/generate Blob, false otherwise.
blob : (function(){
+ // the spec started with BlobBuilder then replaced it with a construtor for Blob.
+ // Result : we have browsers that :
+ // * know the BlobBuilder (but with prefix)
+ // * know the Blob constructor
+ // * know about Blob but not about how to build them
+ // About the "=== 0" test : if given the wrong type, it may be converted to a string.
+ // Instead of an empty content, we will get "[object Uint8Array]" for example.
if (typeof ArrayBuffer === "undefined")
{
return false;
View
@@ -111,7 +111,7 @@
* bytes -> JSZip -> bytes
*/
function reload(bytesStream) {
- return new JSZip(bytesStream, {checkCRC32:true}).generate({base64:false});
+ return new JSZip(bytesStream, {checkCRC32:true}).generate({type:"string"});
}
// cache for files
@@ -224,7 +224,7 @@
testZipFile("Zip text file with UTF-8 characters", "ref/utf8.zip", function(expected) {
var zip = new JSZip();
zip.file("amount.txt", "€15\n");
- var actual = zip.generate({base64:false});
+ var actual = zip.generate({type:"string"});
ok(similar(actual, expected, 18) , "Generated ZIP matches reference ZIP");
equals(reload(actual), actual, "Generated ZIP can be parsed");
@@ -234,7 +234,7 @@
testZipFile("Zip text file with UTF-8 characters in filename", "ref/utf8_in_name.zip", function(expected) {
var zip = new JSZip();
zip.file("€15.txt", "€15\n");
- var actual = zip.generate({base64:false});
+ var actual = zip.generate({type:"string"});
ok(similar(actual, expected, 18) , "Generated ZIP matches reference ZIP");
equals(reload(actual), actual, "Generated ZIP can be parsed");
@@ -537,37 +537,46 @@
});
}
- testZipFile("generate : base64:false", "ref/text.zip", function(expected) {
+ testZipFile("generate : base64:false. Deprecated, but it still works", "ref/text.zip", function(expected) {
var zip = new JSZip();
zip.file("Hello.txt", "Hello World\n");
var actual = zip.generate({base64:false});
ok(similar(actual, expected, 18) , "Generated ZIP matches reference ZIP");
});
- testZipFile("generate : responseType:string,base64:false", "ref/text.zip", function(expected) {
+ testZipFile("generate : base64:true. Deprecated, but it still works", "ref/text.zip", function(expected) {
+ var zip = new JSZip();
+ zip.file("Hello.txt", "Hello World\n");
+ var content = zip.generate({base64:true});
+ var actual = JSZipBase64.decode(content);
+
+ ok(similar(actual, expected, 18) , "Generated ZIP matches reference ZIP");
+ });
+
+ testZipFile("generate : type:string", "ref/text.zip", function(expected) {
var zip = new JSZip();
zip.file("Hello.txt", "Hello World\n");
- var actual = zip.generate({responseType:"string",base64:false});
+ var actual = zip.generate({type:"string"});
ok(similar(actual, expected, 18) , "Generated ZIP matches reference ZIP");
});
- testZipFile("generate : responseType:string‚base64:true", "ref/text.zip", function(expected) {
+ testZipFile("generate : type:base64", "ref/text.zip", function(expected) {
var zip = new JSZip();
zip.file("Hello.txt", "Hello World\n");
- var content = zip.generate({responseType:"string",base64:true});
+ var content = zip.generate({type:"base64"});
var actual = JSZipBase64.decode(content);
ok(similar(actual, expected, 18) , "Generated ZIP matches reference ZIP");
});
if (JSZip.support.uint8array) {
- testZipFile("generate : responseType:uint8array", "ref/text.zip", function(expected) {
+ testZipFile("generate : type:uint8array", "ref/text.zip", function(expected) {
var zip = new JSZip();
zip.file("Hello.txt", "Hello World\n");
- var array = zip.generate({responseType:"uint8array"});
+ var array = zip.generate({type:"uint8array"});
ok(array instanceof Uint8Array, "The result is a instance of Uint8Array");
equals(array.length, expected.length);
@@ -576,11 +585,11 @@
ok(similar(actual, expected, 18) , "Generated ZIP matches reference ZIP");
});
} else {
- testZipFile("generate : responseType:uint8array", "ref/text.zip", function(expected) {
+ testZipFile("generate : type:uint8array", "ref/text.zip", function(expected) {
var zip = new JSZip();
zip.file("Hello.txt", "Hello World\n");
try {
- var blob = zip.generate({responseType:"uint8array"});
+ var blob = zip.generate({type:"uint8array"});
ok(false, "Uint8Array is not supported, but no exception thrown");
} catch(e) {
ok(e.message.match("not supported by this browser"), "the error message is useful");
@@ -589,22 +598,22 @@
}
if (JSZip.support.arraybuffer) {
- testZipFile("generate : responseType:arraybuffer", "ref/text.zip", function(expected) {
+ testZipFile("generate : type:arraybuffer", "ref/text.zip", function(expected) {
var zip = new JSZip();
zip.file("Hello.txt", "Hello World\n");
- var buffer = zip.generate({responseType:"arraybuffer"});
+ var buffer = zip.generate({type:"arraybuffer"});
ok(buffer instanceof ArrayBuffer, "The result is a instance of ArrayBuffer");
var actual = String.fromCharCode.apply(null, new Uint8Array(buffer));
ok(similar(actual, expected, 18) , "Generated ZIP matches reference ZIP");
});
} else {
- testZipFile("generate : responseType:arraybuffer", "ref/text.zip", function(expected) {
+ testZipFile("generate : type:arraybuffer", "ref/text.zip", function(expected) {
var zip = new JSZip();
zip.file("Hello.txt", "Hello World\n");
try {
- var blob = zip.generate({responseType:"arraybuffer"});
+ var blob = zip.generate({type:"arraybuffer"});
ok(false, "ArrayBuffer is not supported, but no exception thrown");
} catch(e) {
ok(e.message.match("not supported by this browser"), "the error message is useful");
@@ -613,20 +622,20 @@
}
if (JSZip.support.blob) {
- testZipFile("generate : responseType:blob", "ref/text.zip", function(expected) {
+ testZipFile("generate : type:blob", "ref/text.zip", function(expected) {
var zip = new JSZip();
zip.file("Hello.txt", "Hello World\n");
- var blob = zip.generate({responseType:"blob"});
+ var blob = zip.generate({type:"blob"});
ok(blob instanceof Blob, "The result is a instance of Blob");
equals(blob.type, "application/zip");
equals(blob.size, expected.length);
});
} else {
- testZipFile("generate : responseType:blob", "ref/text.zip", function(expected) {
+ testZipFile("generate : type:blob", "ref/text.zip", function(expected) {
var zip = new JSZip();
zip.file("Hello.txt", "Hello World\n");
try {
- var blob = zip.generate({responseType:"blob"});
+ var blob = zip.generate({type:"blob"});
ok(false, "Blob is not supported, but no exception thrown");
} catch(e) {
ok(e.message.match("not supported by this browser"), "the error message is useful");

0 comments on commit c415e7f

Please sign in to comment.