afb-client/bower_components/jszip/documentation/api_jszip/file_data.md

   1 ---
   2 title: "file(name, data [,options])"
   3 layout: default
   4 section: api
   5 ---
   6
   7 __Description__ : Add (or update) a file to the zip file.
   8
   9 __Arguments__
  10
  11 name                | type    | description
  12 --------------------|---------|------------
  13 name                | string  | the name of the file. You can specify folders in the name : the folder separator is a forward slash ("/").
  14 data                | String/ArrayBuffer/Uint8Array/Buffer | the content of the file.
  15 options             | object  | the options.
  16
  17 Content of `options` :
  18
  19 name        | type    | default | description
  20 ------------|---------|---------|------------
  21 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.
  22 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`.
  23 date        | date    | the current date | the last modification date.
  24 compression | string  | null    | If set, specifies compression method to use for this specific file. If not, the default file compression will be used, see [generate(options)]({{site.baseurl}}/documentation/api_jszip/generate.html).
  25 compressionOptions | object | `null` | the options to use when compressing the file, see [generate(options)]({{site.baseurl}}/documentation/api_jszip/generate.html).
  26 comment     | string  | null    | The comment for this file.
  27 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.
  28 createFolders | boolean | `false` | 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.
  29 unixPermissions | 16 bits number | null    | The UNIX permissions of the file, if any.
  30 dosPermissions  | 6 bits number  | null    | The DOS permissions of the file, if any.
  31 dir             | boolean        | false   | Set to true if this is a directory and content should be ignored.
  32
  33 You shouldn't update the data given to this method : it is kept as it so any
  34 update will impact the stored data.
  35
  36 __For the permissions__ :
  37
  38 The field `unixPermissions` also accepts a string representing the octal value :
  39 "644", "755", etc. On nodejs you can use the `mode` attribute of
  40 [nodejs' fs.Stats](http://nodejs.org/api/fs.html#fs_class_fs_stats).
  41
  42 See also [the platform option of generate()]({{site.baseurl}}/documentation/api_jszip/generate.html).
  43
  44 __About `dir`__ :
  45
  46 If `dir` is true or if a permission says it's a folder, this entry be flagged
  47 as a folder and the content will be ignored.
  48
  49 __Returns__ : The current JSZip object, for chaining.
  50
  51 __Throws__ : An exception if the data is not in a supported format.
  52
  53 <!--
  54 __Complexity__ : **O(1)** for anything but binary strings.
  55 For binary strings (`data` is a string and `binary` = true), if
  56 `optimizedBinaryString` is not set, the 0xFF mask will be applied giving a
  57 complexity in **O(n)** where n is the size of the added data.
  58 -->
  59
  60 __Example__
  61
  62 ```js
  63 zip.file("Hello.txt", "Hello World\n");
  64
  65 // base64
  66 zip.file("smile.gif", "R0lGODdhBQAFAIACAAAAAP/eACwAAAAABQAFAAACCIwPkWerClIBADs=", {base64: true});
  67 // from an ajax call with xhr.responseType = 'arraybuffer'
  68 zip.file("smile.gif", arraybufferFromXhr);
  69 // or on nodejs
  70 zip.file("smile.gif", fs.readFileSync("smile.gif"));
  71
  72 zip.file("Xmas.txt", "Ho ho ho !", {date : new Date("December 25, 2007 00:00:01")});
  73 zip.file("folder/file.txt", "file in folder");
  74
  75 zip.file("animals.txt", "dog,platypus\n").file("people.txt", "james,sebastian\n");
  76
  77 // result : Hello.txt, smile.gif, Xmas.txt, animals.txt, people.txt,
  78 // folder/, folder/file.txt
  79 // In the above case, the "folder" folder will not have a 'D'irectory attribute or Method property. The
  80 // folder only exists as part of the path to "file.txt".
  81
  82 zip.file("folder/file.txt", "file in folder", {createFolders: true});
  83 // In this case, the "folder" folder WILL have a 'D'irectory attribute and a Method property of "store".
  84 // It will exist whether or not "file.txt" is present.
  85
  86 zip.file("script.sh", "echo 'hello world'", {
  87   unixPermissions : "755"
  88 });
  89 // when generated with platform:UNIX, the script.sh file will be executable
  90 ```