Skip to content

Commit

Permalink
issue #7 : modify the API
Browse files Browse the repository at this point in the history
  • Loading branch information
@dduponchel
dduponchel committed Nov 26, 2011
1 parent f02df57 commit 773196f
Show file tree
Hide file tree
Showing 6 changed files with 953 additions and 432 deletions.
298 changes: 229 additions & 69 deletions index.html
View file
Expand Up @@ -74,6 +74,12 @@
border-top: 1px solid #CCCCCC; border-top: 1px solid #CCCCCC;
} }


dt
{
/*font-weight:bold;*/
text-decoration:underline;
}

#where p #where p
{ {
text-align: center; text-align: center;
Expand Down Expand Up @@ -146,9 +152,9 @@ <h1>JS<span style="font-weight:100">Zip</span></h1>
<h2>How?</h2> <h2>How?</h2>
<textarea id="demo-code" rows="7" class="grid_5 alpha omega" spellcheck="false"> <textarea id="demo-code" rows="7" class="grid_5 alpha omega" spellcheck="false">
var zip = new JSZip(); var zip = new JSZip();
zip.add("Hello.txt", "Hello World\n"); zip.file("Hello.txt", "Hello World\n");
img = zip.folder("images"); img = zip.folder("images");
img.add("smile.gif", imgData, {base64: true}); img.file("smile.gif", imgData, {base64: true});
content = zip.generate(); content = zip.generate();
location.href="data:application/zip;base64,"+content; location.href="data:application/zip;base64,"+content;
</textarea> </textarea>
Expand Down Expand Up @@ -179,7 +185,9 @@ <h2>Where?</h2>
<div class="grid_9 border"> <div class="grid_9 border">
<h2>Tell me more!</h2> <h2>Tell me more!</h2>


<h3>Browser support</h3> <p>While JSZip should work everywhere, the tricky part is to give the zip file to the user.</p>

<h3>Browser support for <a href="https://en.wikipedia.org/wiki/Data_URI_scheme">data URI scheme</a> with zip</h3>
<table cellspacing="0"> <table cellspacing="0">
<tr><th class="op">Opera</th> <th class="ff">Firefox</th> <th class="sf">Safari</th> <th class="cr">Chrome</th> <th class="ie">Internet Explorer</th> </tr> <tr><th class="op">Opera</th> <th class="ff">Firefox</th> <th class="sf">Safari</th> <th class="cr">Chrome</th> <th class="ie">Internet Explorer</th> </tr>
<tr><td>7.5+</td> <td>3.0+</td> <td>Yes</td> <td>Yes</td> <td>No</td></tr> <tr><td>7.5+</td> <td>3.0+</td> <td>Yes</td> <td>Yes</td> <td>No</td></tr>
Expand Down Expand Up @@ -218,99 +226,251 @@ <h3>Usage with Google Gears</h3>


<h2 style="margin-top: 2em;">Documentation</h2> <h2 style="margin-top: 2em;">Documentation</h2>


<h4>new JSZip([compressionMethod])</h4> <h4 id="JSZip()">new JSZip()</h4>
<p>The constructor</p> <dl>
<p><code>compressionMethod</code>, string. The compression method to use for the zip file.</p> <dt>Description : </dt>
<p> <dd>The default constructor.</dd>
Available methods : <dt>Returns : </dt>
<ul> <dd>A new JSZip.</dd>
<li><code>"STORE"</code> no compression, the default.</li> </dl>
<li><code>"DEFLATE"</code> default zip compression, need the file jszip-deflate.js</li>
</ul> <h4 id="new JSZip(data [,options])">new JSZip(data [,options])</h4>
</p> <dl>
<dt>Description : </dt>
<dd>Create a new JSZip file and load an existing zip file. See the documentation of <a href="#load(data, options)"><code>load()</code></a> for more details.</dd>
<dt>Parameters : </dt>
<dd><code>data</code> (String/binary) the content of the zip file to load.</dd>
<dd><code>options</code> (Object) options to pass to the <a href="#load(data, options)"><code>load()</code></a> method..</dd>
<dt>Returns : </dt>
<dd>A new JSZip.</dd>
</dl>
<pre class="example"> <pre class="example">
var zip = new JSZip(); // same as new JSZip("STORE"); new JSZip(zipDataFromXHR, {base64:false});
var zip = new JSZip("DEFLATE");</pre> // same as

var zip = new JSZip();
<h4>add(name, data [,options])</h4> zip.load(zipDataFromXHR, {base64:false});</pre>
<p>Add a file to the zip file. Supports chaining.</p>
<p>Options:</p> <h4 id="file(name)">file(name)</h4>
<ul> <dl>
<li><code>base64</code>, boolean. Set to <code>true</code> if the data <dt>Description : </dt>
is base64 encoded. For example image data from a <code>&lt;canvas&gt;</code> element. <dd>Get a file with the specified name.</dd>
Plain text and HTML do not need this option.</li> <dt>Parameters : </dt>
<li><code>binary</code>, boolean. Defaults to <code>true</code> if the data <dd><code>name</code> (String) the name of the file.</dd>
is base64 encoded, <code>false</code> otherwise. If set to false then <dt>Returns : </dt>
UTF-8 characters will be encoded.</li> <dd>The file if any, <code>null</code> otherwise. The file has the following structure :
<li><code>date</code>, Date. Use it to specify the last modification date. <ul>
If not set the current date is used.</li> <li><code>name</code> the absolute path of the file</li>
</ul> <li><code>data</code> the data contained in the file</li>
<li><code>options</code> the options of the file. The available options are :
<ul>
<li><code>base64</code>, boolean, cf <a href="#file(name, data [,options])">file(name, data [,options])</a></li>
<li><code>binary</code>, boolean, cf <a href="#file(name, data [,options])">file(name, data [,options])</a></li>
<li><code>dir</code>, boolean, true if this is a directory</li>
<li><code>date</code>, date, <a href="#file(name, data [,options])">file(name, data [,options])</a></li>
</ul>
</li>
</ul>
</dd>
</dl>
<pre class="example">
var zip = new JSZip();
zip.file("file.txt", "content");

zip.file("file.txt").name // "file.txt"
zip.file("file.txt").data // "content"
zip.file("file.txt").options.dir // false</pre>

<h4 id="file(regex)">file(regex)</h4>
<dl>
<dt>Description : </dt>
<dd>Search a file in the current folder and subfolders with a <a href="http://www.javascriptkit.com/javatutors/redev.shtml">regular expression</a>. The regex is tested against the relative filename.</dd>
<dt>Parameters : </dt>
<dd><code>regex</code> (RegExp) the regex to use.</dd>
<dt>Returns : </dt>
<dd>An array of matching files (an empty array if none matched).</dd>
</dl>
<pre class="example">
var zip = new JSZip();
zip.file("file1.txt", "content");
zip.file("file2.txt", "content");

zip.file(/file/); // array of size 2

// example with a relative path :
var folder = zip.folder("sub");
folder
.file("file3.txt", "content") // relative path from folder : file3.txt
.file("file4.txt", "content"); // relative path from folder : file4.txt

folder.file(/file/); // array of size 2
folder.file(/^file/); // array of size 2, the relative paths start with file

// arrays contain objects in the form:
// {name: "file2.txt", data: "content", dir: false}</pre>

<h4 id="file(name, data [,options])">file(name, data [,options])</h4>
<dl>
<dt>Description : </dt>
<dd>Add a file to the zip file.</dd>
<dt>Parameters : </dt>
<dd><code>name</code> (String) the name of the file.</dd>
<dd><code>data</code> (binary) the content of the file.</dd>
<dd><code>options</code> (Object) the options :
<ul>
<li><code>base64</code> (boolean) set to <code>true</code> if the data
is base64 encoded. For example image data from a <code>&lt;canvas&gt;</code> element.
Plain text and HTML do not need this option.</li>
<li><code>binary</code> (boolean) defaults to <code>true</code> if the data
is base64 encoded, <code>false</code> otherwise. If set to false then
UTF-8 characters will be encoded.</li>
<li><code>date</code> (Date) use it to specify the last modification date.
If not set the current date is used.</li>
</ul>
</dd>
<dt>Returns : </dt>
<dd>A JSZip object, for chaining.</dd>
</dl>
<pre class="example"> <pre class="example">
zip.add("Hello.txt", "Hello World\n"); zip.add("Hello.txt", "Hello World\n");
zip.add("smile.gif", "R0lGODdhBQAFAIACAAAAAP/eACwAAAAABQAFAAACCIwPkWerClIBADs=", {base64: true}); zip.add("smile.gif", "R0lGODdhBQAFAIACAAAAAP/eACwAAAAABQAFAAACCIwPkWerClIBADs=", {base64: true});
zip.add("magic.txt", "U2VjcmV0IGNvZGU=", {base64: true, binary: false}); zip.add("magic.txt", "U2VjcmV0IGNvZGU=", {base64: true, binary: false});
zip.add("Xmas.txt", "Ho ho ho !", {date : new Date("December 25, 2007 00:00:01")}); zip.add("Xmas.txt", "Ho ho ho !", {date : new Date("December 25, 2007 00:00:01")});

zip.add("folder/file.txt", "file in folder");
zip.add("animals.txt", "dog,platypus\n").add("people.txt", "james,sebastian\n");</pre>
<p> zip.add("animals.txt", "dog,platypus\n").add("people.txt", "james,sebastian\n");
Result: <code>Hello.txt, smile.gif, magic.txt, Xmas.txt, animals.txt, people.txt</code>
</p> // result : Hello.txt, smile.gif, magic.txt, Xmas.txt, animals.txt, people.txt,

// folder/, folder/file.txt</pre>
<h4>folder(name)</h4>
<p>Add a directory to the zip file. Supports chaining.</p> <h4 id="folder(name)">folder(name)</h4>
<dl>
<dt>Description : </dt>
<dd>Add a directory to the zip file.</dd>
<dt>Parameters : </dt>
<dd><code>name</code> (String) the name of the directory.</dd>
<dt>Returns : </dt>
<dd>a new JSZip (for chaining), with the new folder as root.</dd>
</dl>
<pre class="example"> <pre class="example">
zip.folder("images"); zip.folder("images");
zip.folder("css").add("style.css", "body {background: #FF0000}"); zip.folder("css").add("style.css", "body {background: #FF0000}");
// or specify an absolute path (using forward slashes) // or specify an absolute path (using forward slashes)
zip.add("css/font.css", "body {font-family: sans-serif}")</pre> zip.add("css/font.css", "body {font-family: sans-serif}")
<p>
Result: <code>images/, css/, css/style.css, css/font.css</code> // result : images/, css/, css/style.css, css/font.css</pre>
</p>

<h4 id="folder(regex)">folder(regex)</h4>
<h4>find(needle)</h4> <dl>
<p>Compare a string or <a href="http://www.javascriptkit.com/javatutors/redev.shtml">regular expression</a> <dt>Description : </dt>
against all of the filenames and returns an informational object for each that matches.</p> <dd>Search a subdirectory.</dd>
<dd>Search a subdirectory in the current directory with a <a href="http://www.javascriptkit.com/javatutors/redev.shtml">regular expression</a>. The regex is tested against the relative path.</dd>
<dt>Parameters : </dt>
<dd><code>regex</code> (RegExp) the regex to use.</dd>
<dt>Returns : </dt>
<dd>An array of matching folders (an empty array if none matched).</dd>
</dl>
<pre class="example"> <pre class="example">
zip.add("Readme", "Hello World!\n"); var zip = new JSZip();
zip.add("Readme.French", "Bonjour tout le monde!\n"); zip.folder("home/Pierre/videos");
zip.add("Readme.Pirate", "Ahoy m'hearty!\n"); zip.folder("home/Pierre/photos");
zip.folder("home/Jean/videos");
zip.folder("home/Jean/photos");


zip.find("Readme"); // only finds "Readme" zip.folder(/videos/); // array of size 2
zip.find(/^Readme/); // Regular expression finds all three</pre>
<p>
Result: Array of matched file objects in the form:
<code>{name: "Readme", data: "Hello World!", dir: false}</code>
</p>


<h4>remove(name)</h4> zip.folder("home/Jean").folder(/^vid/); // array of 1</pre>

<h4 id="remove(name)">remove(name)</h4>
<p>Delete a file or folder.</p> <p>Delete a file or folder.</p>
<dl>
<dt>Description : </dt>
<dd>Delete a file or folder (recursively).</dd>
<dt>Parameters : </dt>
<dd><code>name</code> (String) the name of the file/folder to delete.</dd>
<dt>Returns : </dt>
<dd>The current JSZip object.</dd>
</dl>
<pre class="example"> <pre class="example">
var zip = new JSZip();
zip.add("Hello.txt", "Hello World\n"); zip.add("Hello.txt", "Hello World\n");
zip.add("temp.txt", "nothing").remove("temp.txt");</pre> zip.add("temp.txt", "nothing").remove("temp.txt");
<p> // result : Hello.txt
Result: <code>Hello.txt</code>
</p>
<pre class="example">
zip.add("Hello.txt", "Hello World\n");
zip.folder("css").add("style.css", "body {background: #FF0000}");
zip.remove("Hello.txt").remove("css");</pre>
<p>
Result: Empty zip.
</p>


<h4>generate(asBytes = false)</h4> zip.folder("css").add("style.css", "body {background: #FF0000}");
<p>Generates the complete zip file. By default encoded as base64, pass <code>true</code> to get the raw byte string</p> zip.remove("Hello.txt").remove("css");
//result : empty zip</pre>

<h4 id="generate(options)">generate(options)</h4>
<dl>
<dt>Description : </dt>
<dd>Generates the complete zip file.</dd>
<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.
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>
</ul>
</dd>
<dt>Returns : </dt>
<dd>The generated zip file.</dd>
</dl>
<pre class="example"> <pre class="example">
content = zip.generate(); content = zip.generate();
location.href="data:application/zip;base64,"+content;</pre> location.href="data:application/zip;base64,"+content;</pre>


<pre class="example"> <pre class="example">
content = zip.generate(true); content = zip.generate({base64:false});
for (var c = 0; c &lt; content.length; c++) for (var c = 0; c &lt; content.length; c++)
{ {
console.log(content.charCodeAt(c)); console.log(content.charCodeAt(c));
// do other things // do other things
}</pre> }</pre>

<h4 id="load(data, options)">load(data, options)</h4>
<dl>
<dt>Description : </dt>
<dd>Read an existing zip and merge the data in the current JSZip object. The implementation is in jszip-load.js, don't forget to include it.</dd>
<dt>Parameters : </dt>
<dd><code>data</code> (binary) the zip file</dd>
<dd><code>options</code> (Object) the options to load the zip file :
<ul>
<li><code>base64</code> (boolean) <code>true</code> if the data is base64 encoded, <code>false</code> for binary. Default : <code>false</code>.</li>
</ul>
</dd>
<dt>Returns : </dt>
<dd>The current JSZip object.</dd>
</dl>
<pre class="example">
var zip = new JSZip();
zip.load(zipDataFromXHR);</pre>

<h4 id="filter(predicate)">filter(predicate)</h4>
<dl>
<dt>Description : </dt>
<dd>Filter nested files/folders with the specified function.</dd>
<dt>Parameters : </dt>
<dd><code>predicate</code> (function) the predicate to use : <code>function (relativePath, file) {...}</code> It takes 2 arguments : the relative path and the file.
<ul>
<li><code>relativePath</code> (String) The filename and its path, reliatively to the current folder.</li>
<li><code>file</code> (Object) The file being tested. Like the result of <a href="#file(name)"><code>file(name)</code></a>, the file has the form <code>{name:"...", data:"...", options:{...}}</code>.</li>
<li>Return true if the file should be included, false otherwise.</li>
</ul>
</dd>
<dt>Returns : </dt>
<dd>An array of matching elements.</dd>
</dl>
<pre class="example">
var zip = new JSZip().folder("dir");
zip.file("readme.txt", "content");
zip.filter(function (relativePath, file){
// relativePath == "readme.txt"
// file = {name:"dir/readme.txt",data:"content",options:{...}}
return true/false;
});
</pre>

</div> </div>


<div id="who" class="grid_3"> <div id="who" class="grid_3">
Expand Down
3 changes: 3 additions & 0 deletions jszip-inflate.js
View file
Expand Up @@ -19,6 +19,9 @@ if(!JSZip)
*/ */


(function(){ (function(){
// the original implementation leaks a global variable.
// Defining the variable here doesn't break anything.
var zip_fixed_bd;


/* Copyright (C) 1999 Masanao Izumo <iz@onicos.co.jp> /* Copyright (C) 1999 Masanao Izumo <iz@onicos.co.jp>
* Version: 1.0.0.1 * Version: 1.0.0.1
Expand Down
2 changes: 1 addition & 1 deletion jszip-load.js
View file
Expand Up @@ -383,7 +383,7 @@ Licenced under the GPLv3 and the MIT licences
for (i in files) for (i in files)
{ {
input = files[i]; input = files[i];
this.add(input.fileName, input.uncompressedFileData, { this.file(input.fileName, input.uncompressedFileData, {
binary:true, binary:true,
date:input.date, date:input.date,
dir:input.dir dir:input.dir
Expand Down

0 comments on commit 773196f

Please sign in to comment.