afm-client/bower_components/jszip/documentation/examples.md

   1 ---
   2 title: "How to use JSZip"
   3 layout: default
   4 section: example
   5 ---
   6
   7 An instance of JSZip represents a set of files. You can add them, remove them,
   8 modify them. You can also import an existing zip file or generate one.
   9
  10 ### Getting the object
  11
  12 #### In a browser
  13
  14 For a browser, there are two interesting files : `dist/jszip.js` and
  15 `dist/jszip.min.js` (include just one).
  16
  17 If you use an AMD loader (RequireJS for example) JSZip will register itself :
  18 you just have to put the js file at the right place, or configure the loader
  19 (see [here for RequireJS](http://requirejs.org/docs/api.html#config-paths)).
  20
  21 Without any loader, JSZip will declare in the global scope a variable named `JSZip`.
  22
  23 #### In nodejs
  24
  25 In nodejs, you can `require` it :
  26
  27 ```js
  28 var JSZip = require("jszip");
  29 ```
  30
  31 ### Basic manipulations
  32
  33 The first step is to create an instance of JSZip :
  34
  35 ```js
  36 var zip = new JSZip();
  37 ```
  38
  39 On this instance, we can add (and update) files and folders with
  40 `.file(name, content)` and `.folder(name)`.
  41 They return the current JSZip instance so you can chain the calls.
  42
  43 ```js
  44 // create a file
  45 zip.file("hello.txt", "Hello[p my)6cxsw2q");
  46 // oops, cat on keyboard. Fixing !
  47 zip.file("hello.txt", "Hello World\n");
  48
  49 // create a file and a folder
  50 zip.file("nested/hello.txt", "Hello World\n");
  51 // same as
  52 zip.folder("nested").file("hello.txt", "Hello World\n");
  53 ```
  54
  55 With `.folder(name)`, the returned object has a different root : if you add files
  56 on this object, you will put them in the created subfolder. This is just a
  57 view, the added files will also be in the "root" object.
  58
  59 ```js
  60 var photoZip = zip.folder("photos");
  61 // this call will create photos/README
  62 photoZip.file("README", "a folder with photos");
  63 ```
  64
  65 You can access the file content with `.file(name)` and
  66 [its getters]({{site.baseurl}}/documentation/api_zipobject.html) :
  67
  68 ```js
  69 zip.file("hello.txt").asText(); // "Hello World\n"
  70
  71 if (JSZip.support.uint8array) {
  72   zip.file("hello.txt").asUint8Array(); // Uint8Array { 0=72, 1=101, 2=108, more...}
  73 }
  74 ```
  75
  76 You can also remove files or folders with `.remove(name)` :
  77
  78 ```js
  79 zip.remove("photos/README");
  80 zip.remove("photos");
  81 // same as
  82 zip.remove("photos"); // by removing the folder, you also remove its content.
  83 ```
  84
  85 ### Generate a zip file
  86
  87 With `.generate(options)` you can generate a zip file (not a real file but its
  88 representation in memory). Check
  89 [this page]({{site.baseurl}}/documentation/howto/write_zip.html) for more
  90 informations on how to write / give the file to the user.
  91
  92 ```js
  93 var content = null;
  94 if (JSZip.support.uint8array) {
  95   content = zip.generate({type : "uint8array"});
  96 } else {
  97   content = zip.generate({type : "string"});
  98 }
  99 ```
 100
 101 ### Read a zip file
 102
 103 With `.load(data)` you can load a zip file. Check
 104 [this page]({{site.baseurl}}/documentation/howto/read_zip.html) to see how to
 105 do properly (it's more tricky that it seems).
 106
 107 ```js
 108 var new_zip = new JSZip();
 109 // more files !
 110 new_zip.load(content);
 111
 112 // you now have every files contained in the loaded zip
 113 new_zip.file("hello.txt").asText(); // "Hello World\n"
 114 ```
 115