webgme

--- title: "file(name, data [,options])" layout: default section: api --- Add (or update) a file to the zip file. If something goes wrong (the data is not in a supported format for example), an exception will be propagated when accessing the data. __Returns__ : The current JSZip object, for chaining. __Since__: v1.0.0 ## Arguments name | type | description --------------------|---------|------------ name | string | the name of the file. You can specify folders in the name : the folder separator is a forward slash ("/"). data | String/ArrayBuffer/Uint8Array/Buffer/Blob/Promise/Nodejs stream | the content of the file. options | object | the options. Content of `options` : name | type | default | description ------------|---------|---------|------------ base64 | boolean | `false` | set to `true` if the data is base64 encoded. For example image data from a `<canvas>` element. Plain text and HTML do not need this option. [More](#base64-option). binary | boolean | `false` | set to `true` if the data should be treated as raw content, `false` if this is a text. If base64 is used, this defaults to `true`, if the data is not a string, this will be set to `true`. [More](#binary-option). date | date | the current date | the last modification date. [More](#date-option). compression | string | null | If set, specifies compression method to use for this specific file. If not, the default file compression will be used, see [generateAsync(options)]({{site.baseurl}}/documentation/api_jszip/generate_async.html). [More](#compression-and-compressionoptions-options). compressionOptions | object | `null` | the options to use when compressing the file, see [generateAsync(options)]({{site.baseurl}}/documentation/api_jszip/generate_async.html). [More](#compression-and-compressionoptions-options). comment | string | null | The comment for this file. [More](#comment-option). optimizedBinaryString | boolean | `false` | Set to true if (and only if) the input is a "binary string" and has already been prepared with a 0xFF mask. createFolders | boolean | `true` | Set to true if folders in the file path should be automatically created, otherwise there will only be virtual folders that represent the path to the file. [More](#createfolders-option). unixPermissions | 16 bits number | null | The UNIX permissions of the file, if any. [More](#unixpermissions-and-dospermissions-options). dosPermissions | 6 bits number | null | The DOS permissions of the file, if any. [More](#unixpermissions-and-dospermissions-options). dir | boolean | false | Set to true if this is a directory and content should be ignored. [More](#dir-option). ### data input You shouldn't update the data given to this method: it is kept as it so any update will impact the stored data. #### About Promise since v3.0.0 You can use a Promise of content directly to simplify async content handling. Let's use HTTP calls as examples: ```js /** with promises **/ // instead of $.get("url/to.file.txt") // jQuery v3 returns promises .then(function (content) { zip.file("file.txt", content); }) // you can do var promise = $.get("url/to.file.txt"); zip.file("file.txt", promise); ``` ```js /** with callbacks **/ // instead of request('url/to.file.txt', function (error, response, body) { zip.file("file.txt", body); }); // you can do var promise = new Promise(function (resolve, reject) { request('url/to.file.txt', function (error, response, body) { if (error) { reject(error); } else { resolve(body); } }); }); zip.file("file.txt", promise); ``` #### About Blob since v3.0.0 You can use directly [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) as input, no need to use a `FileReader`. [File](https://developer.mozilla.org/en-US/docs/Web/API/File) objects are Blobs so you can use them directly: ```js // in a change callback of a <input type="file"> var files = evt.target.files; for (var i = 0; i < files.length; i++) { var f = files[i]; zip.file(f.name, f); } ``` #### About nodejs stream since v3.0.0 A stream can't be restarted: if it is used once, it can't be used again ( by [generateAsync()]({{site.baseurl}}/documentation/api_jszip/generate_async.html) or by [ZipObject methods]({{site.baseurl}}/documentation/api_zipobject.html)). In that case, the promise/stream (depending on the method called) will get an error. ### `base64` option ```js var zip = new JSZip(); zip.file("hello.txt", "aGVsbG8gd29ybGQK", {base64: true}); ``` ### `binary` option ```js var zip = new JSZip(); // here, we have a correct (unicode) string zip.file("hello.txt", "unicode ♥", {binary: false}); // here, we have a binary string: it can contain binary content, one byte // per character. zip.file("hello.txt", "unicode \xE2\x99\xA5", {binary: true}); ``` If you use a library that returns a binary string for example, you should use this option. Otherwise, you will get a corrupted result: JSZip will try to encode this string with UTF-8 when the content doesn't need to. ### `date` option ```js zip.file("Xmas.txt", "Ho ho ho !", { date: new Date("December 25, 2007 00:00:01") }); ``` ### `compression` and `compressionOptions` options See also the same options on [`JSZip#generateAsync()`]({{site.baseurl}}/documentation/api_jszip/generate_async.html#compression-and-compressionoptions-options). These options will be used when generating a zip file. They let you override entry per entry the compression / compression options to use. ```js zip.file("a.png", contentOfA, { compression: "STORE" // force a compression for this file }); zip.file("b.txt", contentOfA, { compression: "DEFLATE", compressionOptions: { level: 9 // force a compression and a compression level for this file } }); // don't force anything, use the generateAsync options zip.file("c.txt", contentOfB); // here: // - a.png will not be compressed (STORE) // - b.txt will be compressed at maximum level // - c.txt will be compressed with the default compression level zip.generateAsync({ type: "blob", compression: "DEFLATE" }); ``` ### `comment` option ```js zip.file("a.txt", "content", { comment: "comment of a.txt" }); ``` ### `createFolders` option ```js zip.file("a/b/c/d.txt", "content", { createFolders: true // default value }); console.log(zip.files); // will display: // - a/ // - a/b/ // - a/b/c/ // - a/b/c/d.txt zip.file("a/b/c/d.txt", "content", { createFolders: false }); console.log(zip.files); // will display: // - a/b/c/d.txt ``` ### `unixPermissions` and `dosPermissions` options Each permission will be used for matching [platform option of generateAsync()]({{site.baseurl}}/documentation/api_jszip/generate_async.html): on `DOS`, use `dosPermissions`, on `UNIX`, use `unixPermissions`. On nodejs you can use the `mode` attribute of [nodejs' fs.Stats](http://nodejs.org/api/fs.html#fs_class_fs_stats). When not set, a default value will be generated: - `0100664` or `040775` for `UNIX` - standard file or standard directory for `DOS` The field `unixPermissions` also accepts a **string** representing the octal value: "644", "755", etc. ```js zip.file("script.sh", "#!/bin/bash", { unixPermissions: "755" }); ``` ### `dir` option If `dir` is true or if a permission says it's a folder, this entry be flagged as a folder and the content will be ignored. See also [folder(name)]({{site.baseurl}}/documentation/api_jszip/folder_name.html). ```js zip.file("folder/", null, { dir: true }); ``` ## Other examples ```js zip.file("Hello.txt", "Hello World\n"); // base64 zip.file("smile.gif", "R0lGODdhBQAFAIACAAAAAP/eACwAAAAABQAFAAACCIwPkWerClIBADs=", {base64: true}); // from an ajax call with xhr.responseType = 'arraybuffer' zip.file("smile.gif", arraybufferFromXhr); // or on nodejs zip.file("smile.gif", fs.readFileSync("smile.gif")); zip.file("Xmas.txt", "Ho ho ho !", {date : new Date("December 25, 2007 00:00:01")}); zip.file("folder/file.txt", "file in folder"); zip.file("animals.txt", "dog,platypus\n").file("people.txt", "james,sebastian\n"); // result: // - Hello.txt // - smile.gif // - Xmas.txt // - animals.txt // - people.txt // - folder/ // - folder/file.txt ```